IAB Tech Lab Assignments API

openapi: 3.2.0
info:
  version: 1.5.1
  title: OpenDirect Assignments API
  description: OpenDirect enables publishers to offer premium inventory using a programmatic interface that partners and vendors build according to the OpenDirect specifications.
servers:
- url: https://opendirect.example.com/v1.5.1
security:
- OauthSecurity:
  - https://opendirect.example.com/scope/example
tags:
- name: Assignments
paths:
  /accounts/{accountId}/assignments:
    get:
      tags:
      - Assignments
      description: 'Gets a list of all assignments that belong to the account.

        For advertisers, the list will include only assignments that they own. For agencies, the list will include the assignments that they own and the assignments that belong to accounts that they manage on behalf of advertisers.'
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/count'
      - $ref: '#/components/parameters/offset'
      - name: $filter
        in: query
        description: 'Allows to get a list of assignments that match the specified filter criteria. The caller may use OData expressions with the following Assignment properties:

          - CreativeId

          - LineId

          - StartDate

          - EndDate

          The user must have permissions to access the assignment. For example, advertisers and agencies may get assignments that they own. In addition, an agency may get assignments that belong to the accounts that they manage on behalf of advertisers.

          '
        schema:
          type: string
      responses:
        200:
          $ref: '#/components/responses/AssignmentsResponse'
        401:
          $ref: '#/components/responses/Standard401ErrorResponse'
        404:
          $ref: '#/components/responses/Standard404ErrorResponse'
        500:
          $ref: '#/components/responses/Standard500ErrorResponse'
      summary: Get accounts by account id assignments
      x-summary-source: derived
      operationId: getAccountsByAccountIdAssignments
      x-operation-id-source: derived
    post:
      tags:
      - Assignments
      description: 'Adds an assignment to the specified account. To add an assignment, the creative must be approved. An assignment may be added at any time prior to the order finishing its flight.

        An advertiser or agency may add assignments to accounts that they own. In addition; an agency may add assignments to accounts that they manage on behalf of advertisers.'
      parameters:
      - $ref: '#/components/parameters/accountId'
      responses:
        201:
          $ref: '#/components/responses/AssignmentResponse'
        400:
          $ref: '#/components/responses/Standard400ErrorResponse'
        401:
          $ref: '#/components/responses/Standard401ErrorResponse'
        404:
          $ref: '#/components/responses/Standard404ErrorResponse'
        500:
          $ref: '#/components/responses/Standard500ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Assignment'
        required: true
      summary: Create accounts by account id assignments
      x-summary-source: derived
      operationId: postAccountsByAccountIdAssignments
      x-operation-id-source: derived
  /accounts/{accountId}/assignments/{assignmentId}:
    get:
      tags:
      - Assignments
      description: 'Gets the specified assignment.

        The user must have permissions to perform the requested action. For example, advertisers and agencies may get the assignments that they own. In addition, an agency may get assignments that belong to the accounts that they manage on behalf of advertisers.'
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/assignmentId'
      responses:
        200:
          $ref: '#/components/responses/AssignmentResponse'
        400:
          $ref: '#/components/responses/Standard400ErrorResponse'
        401:
          $ref: '#/components/responses/Standard401ErrorResponse'
        404:
          $ref: '#/components/responses/Standard404ErrorResponse'
        500:
          $ref: '#/components/responses/Standard500ErrorResponse'
      summary: Get accounts by account id assignments by assignment id
      x-summary-source: derived
      operationId: getAccountsByAccountIdAssignmentsByAssignmentId
      x-operation-id-source: derived
    put:
      tags:
      - Assignments
      description: 'Updates the specified assignment.

        The user must have permissions to perform the requested action. For example, advertisers and agencies may update the assignments that they own. In addition, an agency may update assignments that belong to the accounts that they manage on behalf of advertisers.'
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/assignmentId'
      responses:
        200:
          $ref: '#/components/responses/AssignmentResponse'
        400:
          $ref: '#/components/responses/Standard400ErrorResponse'
        401:
          $ref: '#/components/responses/Standard401ErrorResponse'
        404:
          $ref: '#/components/responses/Standard404ErrorResponse'
        500:
          $ref: '#/components/responses/Standard500ErrorResponse'
      summary: Replace accounts by account id assignments by assignment id
      x-summary-source: derived
      operationId: putAccountsByAccountIdAssignmentsByAssignmentId
      x-operation-id-source: derived
    delete:
      tags:
      - Assignments
      description: 'Deletes the specified assignment. May delete an assignment only if it has never delivered impressions.

        The user must have permissions to perform the requested action. For example, advertisers and agencies may delete the assignments that they own. In addition, an agency may delete assignments that belong to the accounts that they manage on behalf of advertisers.'
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/assignmentId'
      responses:
        204:
          description: Assignment successfully deleted.
        400:
          $ref: '#/components/responses/Standard400ErrorResponse'
        401:
          $ref: '#/components/responses/Standard401ErrorResponse'
        404:
          $ref: '#/components/responses/Standard404ErrorResponse'
        500:
          $ref: '#/components/responses/Standard500ErrorResponse'
      summary: Delete accounts by account id assignments by assignment id
      x-summary-source: derived
      operationId: deleteAccountsByAccountIdAssignmentsByAssignmentId
      x-operation-id-source: derived
  /accounts/{accountId}/assignments/{assignmentId}?disable:
    put:
      tags:
      - Assignments
      description: 'Changes the status to “Inactive”.

        The user must have permissions to access the assignment. For example, advertisers and agencies may disable Assignments that they own. In addition, an agency may disable assignments that belong to the accounts that they manage on behalf of advertisers.'
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/assignmentId'
      responses:
        200:
          $ref: '#/components/responses/AssignmentResponse'
        400:
          $ref: '#/components/responses/Standard400ErrorResponse'
        401:
          $ref: '#/components/responses/Standard401ErrorResponse'
        404:
          $ref: '#/components/responses/Standard404ErrorResponse'
        500:
          $ref: '#/components/responses/Standard500ErrorResponse'
      summary: Replace accounts by account id assignments {assignment id}?disable
      x-summary-source: derived
      operationId: putAccountsByAccountIdAssignments{assignmentId}?disable
      x-operation-id-source: derived
components:
  parameters:
    offset:
      name: offset
      in: query
      description: Indicates the starting point from which the number of records should be returned in the response.
      schema:
        type: integer
        default: 0
        minimum: 0
    accountId:
      name: accountId
      in: path
      required: true
      x-example: '23873345'
      schema:
        type: string
        maxLength: 36
    assignmentId:
      name: assignmentId
      in: path
      required: true
      x-example: '453365'
      schema:
        type: string
        maxLength: 36
    count:
      name: count
      in: query
      description: Indicates the number of desired records to be returned in the response.
      schema:
        type: integer
        default: 250
        minimum: 1
  schemas:
    Assignment:
      description: 'Defines an Assignment resource. An Assignment associates a creative with a line of the order. A creative may be assigned to one or more lines and a line may be assigned one or more creative.

        Notes: The assignment must fail if the following are true.

        - The language property for the creative does not match any of the languages in the language property for the product (products are defined in the LINE resource for an Order).

        - The specified maturity level property for the creative does not match the maturity level property for the product specified in the LINE resource.

        '
      allOf:
      - $ref: '#/components/schemas/Identity'
      - $ref: '#/components/schemas/ProviderData'
      - required:
        - CreativeId
        - LineId
        - Status
        properties:
          CreativeId:
            description: The ID of the creative to display when the line runs.
            type: string
            maxLength: 36
          LineId:
            description: The ID of the line that will display the creative.
            type: string
            maxLength: 36
          Status:
            description: 'A value that determines whether the creative serves.

              The status may not transition from Inactive to Active.

              '
            type: string
            enum:
            - Active
            - Inactive
            readOnly: true
          Weight:
            description: 'Determines how much the creative is displayed relative to the other creative assigned to the same line.

              To provide even rotation, do not specify a weight.

              If weight is specified, all assignments that specify the same line must specify a weight and the weight of all the assignments must add up to 100. If the weight of all assignments does not add up to 100, even rotation is applied.

              Assignments with heavier weight get proportionally more rotation compared to those with lesser weight.

              For example, if the line has 2 creative, A and B, assigned with the same dates, and A has weight 25 and B has weight 75, B will serve three times as often as A.

              '
            type: integer
            minimum: 1
            maximum: 100
    Errors:
      type: array
      items:
        $ref: '#/components/schemas/Error'
    ProviderData:
      description: Common definition for all entities with provider data.
      properties:
        ProviderData:
          description: 'An opaque blob of provider-defined data. Providers may use this field as needed (for example, to store an ID that correlates this object with resources within their system).

            Note that any provider that edits this object may override the data in this field. The data should include a marker that you can identify to ensure the data is yours.

            '
          type: string
          maxLength: 1000
    Assignments:
      required:
      - Assignments
      properties:
        Assignments:
          type: array
          items:
            $ref: '#/components/schemas/Assignment'
    Error:
      type: object
      required:
      - ErrorCode
      - ErrorMessage
      properties:
        ErrorCode:
          type: string
        ErrorMessage:
          type: string
        Context:
          type: object
        Link:
          type: string
    Identity:
      description: Common definition for all entities with identity.
      required:
      - Id
      properties:
        Id:
          description: A system-generated opaque ID that uniquely identifies this resource.
          type: string
          maxLength: 36
          readOnly: true
  responses:
    Standard500ErrorResponse:
      description: Unexpected error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          example: "{\n  \"ErrorCode\": \"internalError\",\n  \"ErrorMessage\": \"Unexpected error occurred\"\n}\n"
    Standard400ErrorResponse:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          example: "{\n  \"ErrorCode\": \"badRequest\",\n  \"ErrorMessage\": \"Request contains invalid data\"\n}\n"
    AssignmentsResponse:
      description: Collection of Assignment
      headers:
        X-Total-Count:
          description: Total number of results
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Assignments'
          example: "{\n  \"Assignments\": [\n    {\n      \"CreativeId\": \"394857\",\n      \"LineId\": \"394578\",\n      \"Weight\": 75,\n      \"Id\": \"34534\",\n      \"Status\": \"Active\",\n      \"ProviderData\": \"cid=98374\"\n    },\n    {\n      \"CreativeId\": \"54345\",\n      \"LineId\": \"394578\",\n      \"Weight\": 25,\n      \"Id\": \"453365\",\n      \"Status\": \"Active\",\n      \"ProviderData\": \"cid=34325\"\n    }\n  ]\n}\n"
    Standard404ErrorResponse:
      description: Not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          example: "{\n  \"ErrorCode\": \"notFound\",\n  \"ErrorMessage\": \"Requested resource is not found\"\n}\n"
    Standard401ErrorResponse:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Errors'
          example: "{\n  \"ErrorCode\": \"unauthorized\",\n  \"ErrorMessage\": \"You are not authorized to use this service\"\n}\n"
    AssignmentResponse:
      description: Assignment resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Assignment'
          example: "{\n  \"CreativeId\": \"54345\",\n  \"LineId\": \"394578\",\n  \"Weight\": 25,\n  \"Id\": \"453365\",\n  \"Status\": \"Active\",\n  \"ProviderData\": \"cid=34325\"\n}\n"
  securitySchemes:
    OauthSecurity:
      type: oauth2
      flows:
        implicit:
          scopes:
            https://opendirect.example.com/scope/example: Example scope
          authorizationUrl: https://opendirect.example.com/connect/authorize
      description: Example of one of OAuth 2.0 authorization flow that can be used according to specification.