IAB Tech Lab Change Requests Lines API

openapi: 3.2.0
info:
  version: 1.5.1
  title: OpenDirect Change Requests Lines 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: Change Requests Lines
paths:
  /accounts/{accountId}/changerequest/{changerequestId}/lines:
    get:
      tags:
      - Change Requests Lines
      description: Gets a list of all lines in the change request.
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/changerequestId'
      - name: $filter
        in: query
        description: 'Gets a list of lines that match the specified filter criteria. The user may use OData expressions and method calls with the following Line properties.

          - Name

          - StartDate

          - EndDate

          May support getting a list by IDs.

          '
        schema:
          type: string
      responses:
        200:
          $ref: '#/components/responses/LinesResponse'
        401:
          $ref: '#/components/responses/Standard401ErrorResponse'
        404:
          $ref: '#/components/responses/Standard404ErrorResponse'
        500:
          $ref: '#/components/responses/Standard500ErrorResponse'
      summary: Get accounts by account id changerequest by changerequest id lines
      x-summary-source: derived
      operationId: getAccountsByAccountIdChangerequestByChangerequestIdLines
      x-operation-id-source: derived
    post:
      tags:
      - Change Requests Lines
      description: Adds a line to the change request.
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/changerequestId'
      responses:
        201:
          $ref: '#/components/responses/LineResponse'
        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/Line'
        required: true
      summary: Create accounts by account id changerequest by changerequest id lines
      x-summary-source: derived
      operationId: postAccountsByAccountIdChangerequestByChangerequestIdLines
      x-operation-id-source: derived
  /accounts/{accountId}/changerequest/{changerequestId}/lines/{lineId}:
    get:
      tags:
      - Change Requests Lines
      description: Gets the specified line from the change request.
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/changerequestId'
      - $ref: '#/components/parameters/lineId'
      responses:
        200:
          $ref: '#/components/responses/LineResponse'
        401:
          $ref: '#/components/responses/Standard401ErrorResponse'
        404:
          $ref: '#/components/responses/Standard404ErrorResponse'
        500:
          $ref: '#/components/responses/Standard500ErrorResponse'
      summary: Get accounts by account id changerequest by changerequest id lines by line id
      x-summary-source: derived
      operationId: getAccountsByAccountIdChangerequestByChangerequestIdLinesByLineId
      x-operation-id-source: derived
    put:
      tags:
      - Change Requests Lines
      description: Updates the specified line in the change request. To update a line, the line must be in the Pending state.
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/changerequestId'
      - $ref: '#/components/parameters/lineId'
      responses:
        200:
          $ref: '#/components/responses/LineResponse'
        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 changerequest by changerequest id lines by line…
      x-summary-source: derived
      operationId: putAccountsByAccountIdChangerequestByChangerequestIdLinesByLineId
      x-operation-id-source: derived
    delete:
      tags:
      - Change Requests Lines
      description: Deletes the specified line from the change request. May delete a line only if it’s in the Pending state. Must also delete assignments that reference the line.
      parameters:
      - $ref: '#/components/parameters/accountId'
      - $ref: '#/components/parameters/changerequestId'
      - $ref: '#/components/parameters/lineId'
      responses:
        204:
          description: Line successfully deleted.
        401:
          $ref: '#/components/responses/Standard401ErrorResponse'
        404:
          $ref: '#/components/responses/Standard404ErrorResponse'
        500:
          $ref: '#/components/responses/Standard500ErrorResponse'
      summary: Delete accounts by account id changerequest by changerequest id lines by line id
      x-summary-source: derived
      operationId: deleteAccountsByAccountIdChangerequestByChangerequestIdLinesByLineId
      x-operation-id-source: derived
components:
  schemas:
    Errors:
      type: array
      items:
        $ref: '#/components/schemas/Error'
    Segment:
      description: The segment object is made up of TARGET and TARGET VALUE reference data objects and is used to specify targeting options for a LINE resource
      required:
      - Target
      - TargetValues
      properties:
        Target:
          $ref: '#/components/schemas/Target'
        TargetValues:
          description: A list of target values. For example, age range 18-24 and 25-34.
          type: array
          items:
            $ref: '#/components/schemas/TargetValue'
    FrequencyCapInterval:
      description: 'Defines the frequency cap intervals that the API supports.

        The frequency interval specifies the units in which the frequency count is expressed. For example, if a line’s frequency count is 2 and interval is Day, display the ad to the same user a Max 2 times in the same calendar day.

        '
      allOf:
      - $ref: '#/components/schemas/Identity'
      - required:
        - Name
        properties:
          Name:
            description: The name of the interval.
            type: string
            enum:
            - Day
            - Month
            - Week
            - Hour
            - LineDuration
    Lines:
      required:
      - Lines
      properties:
        Lines:
          type: array
          items:
            $ref: '#/components/schemas/Line'
    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
    RateType:
      description: Defines a unit of measure that a cost (i.e. BasePrice) is expressed in. The API may support all or a subset of the specified values.
      allOf:
      - $ref: '#/components/schemas/Identity'
      - required:
        - Name
        properties:
          Name:
            description: The rate type’s display name.
            type: string
            enum:
            - CPM
            - CPMV
            - CPC
            - CPD
            - FlatRate
    Target:
      description: Defines a target category. The API must support the specified target categories and may support additional categories such as zip code or postal code.
      allOf:
      - $ref: '#/components/schemas/Identity'
      - required:
        - Name
        properties:
          Name:
            description: The target category.
            type: string
            enum:
            - Age
            - Gender
            - DMA
            - Country
            - State/Province
            - Daypart
            - Weekpart
            - Behavioral
            - Device
    TargetValue:
      description: 'Defines a target value.

        The API must support the specified values per target category.

        '
      allOf:
      - $ref: '#/components/schemas/Identity'
      - required:
        - Value
        - TargetId
        properties:
          Value:
            description: The target value
            type: string
            enum:
            - Age - Publisher-defined age ranges
            - Gender - Female
            - Gender - Male
            - DMA - Publisher-defined  source (such as Digital Envoy)
            - Country - Publisher-defined source
            - State-Province - Publisher-defined source
            - Daypart - 0 through 23 hours
            - Weekpart - Sunday
            - Weekpart - Monday
            - Weekpart - Tuesday
            - Weekpart - Wednesday
            - Weekpart - Thursday
            - Weekpart - Friday
            - Weekpart - Saturday
          TargetId:
            description: A system-generated ID that identifies the target category that this value belongs to.
            type: string
    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
    Line:
      description: 'Line resources are included in an order and provide details about the product being booked, status, start and end dates, and other settings for the order item.

        Creative are assigned to the LINE resource of an order using the ASSIGNMENT resource. Notes: The user may update a line only if it’s in the Draft state. If the line is in the Reserved or Declined state, the user may call Reset to move the line back to the Draft state in order to update the line.

        '
      allOf:
      - $ref: '#/components/schemas/Identity'
      - $ref: '#/components/schemas/ProviderData'
      - required:
        - BookingStatus
        - Cost
        - EndDate
        - Quantity
        - Name
        - OrderId
        - ProductId
        - Rate
        - RateType
        - StartDate
        - StateChangeReason
        properties:
          BookingStatus:
            description: A value that determines whether the line is booked and is capable of delivering ads. If the line is reset, the StateChangeReason should be cleared.
            type: string
            enum:
            - Draft
            - PendingReservation
            - Reserved
            - PendingBooking
            - Booked
            - InFlight
            - Finished
            - Stopped
            - Canceled
            - Pause
            - Expired
            - Declined
            - ChangePending
            readOnly: true
          Comment:
            description: User notes related to this line.
            type: string
            maxLength: 255
          Cost:
            description: 'The projected cost of the line is based on the specified quantity, rate and targeting. The actual cost (the amount billed) is based on the actual number of impressions.

              The cost is specified in the currency for the order. If the order uses a different currency than what the product uses, the cost for the line must be converted to the order’s currency.

              The cost is determined at the time the line is saved with the following statuses: Drafted, Reserved, or Booked.

              '
            type: number
            readOnly: true
          EndDate:
            description: 'The date and time that the line will stop.

              If the time is missing, 11:59 PM is assumed.

              The line end date must be later than the line start date and should be less than or equal to the order’s end date.

              If the line end date is later than the order’s end date, the order’s end date should be extended to match the line’s end date.

              '
            type: string
            format: date-time
          FrequencyCount:
            description: The maximum number of times that a unique user must see ads from this line during the specified interval (see FrequencyInterval).
            type: integer
          FrequencyInterval:
            $ref: '#/components/schemas/FrequencyCapInterval'
          Quantity:
            description: 'The quantity requested for the specified date range. This value will differ based on various cost types. For CPM, for examples, the value would be impressions.

              The line must contain a quantity before the user may reserve or book it. If the requested quantity is not available, reserving or booking the line must fail and bookingStatus must be set to Declined.

              '
            type: integer
          Name:
            description: 'The line’s display name.

              Should be unique.

              '
            type: string
            maxLength: 200
          OrderId:
            description: The ID of the order that this line belongs to.
            type: string
            maxLength: 36
            readOnly: true
          ProductId:
            description: The ID of the product where the creatives run.
            type: string
            maxLength: 36
          Rate:
            description: 'The price per unit of impressions. For example, $10 per 1,000 impressions (CPM).

              The rate is determined each time the line is saved (added, updated, booked, or reserved).

              Value in currency for the order.

              '
            type: number
            readOnly: true
          RateType:
            description: The rate type is determined at the time the line is saved (added, updated, booked, or reserved).
            $ref: '#/components/schemas/RateType'
            readOnly: true
          ReservedExpiryDate:
            description: 'The date and time that the reserved inventory will expire.

              If the line is reserved, the expiry date must be set.

              '
            type: string
            format: date-time
            readOnly: true
          StartDate:
            description: 'The date and time that the line will start.

              If the time is missing, 12:00 AM is assumed.

              The date and time must be greater than or equal to now and should be greater than or equal to the order’s start date.

              If the line start date is earlier than the order’s start date, the order’s start date should be moved to match the line’s start date. Both dates must be later than the present day.

              Start dates that are in the past may not be updated.

              '
            type: string
            format: date-time
          StateChangeReason:
            description: 'The reason why the state was changed by the publisher.

              The reason must be specified if:

              - The publisher declined the booking or reservation.

              - The publisher or user canceled the flight.

              '
            type: string
            readOnly: true
          Targeting:
            description: The creative assigned to the LINE resource is display when the line includes user segments and the delivery engine can determine whether the user matches the specified segments.
            $ref: '#/components/schemas/Segment'
          UsesExpandables:
            description: 'A Boolean value that indicates whether the line will be assigned expandable creatives. Used to determine availability.

              The default is false.

              '
            type: boolean
  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"
    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"
    LineResponse:
      description: Line resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Line'
          example: "{\n  \"BookingStatus\": \"Draft\",\n  \"Comment\": \"Free form comment\",\n  \"EndDate\": \"2014-12-10T18:00:00.000Z\",\n  \"FrequencyCount\": 3,\n  \"FrequencyInterval\": \"Day\",\n  \"Id\": \"345233\",\n  \"Quantity\": 30000,\n  \"Name\": \"My Line 1\",\n  \"OrderId\": \"1235872\",\n  \"ProductId\": \"456366\",\n  \"ProviderData\": \"cid=88873\",\n  \"StartDate\": \"2014-12-05T06:00:00.000Z\",\n  \"Targeting\": [\n    {\n      \"Target\": \"Age\",\n      \"TargetValues\": [\"18-24\",\"25-34\"]\n    },\n    {\n      \"Target\": \"Gender\",\n      \"TargetValues\": [\"Male\"]\n    }\n  ]\n  \"UsesExpandables\": False\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"
    LinesResponse:
      description: Collection of Line
      headers:
        X-Total-Count:
          description: Total number of results
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Lines'
          example: "{\n  \"Lines\": [\n    {\n      \"BookingStatus\": \"Draft\",\n      \"Comment\": \"Free form comment\",\n      \"EndDate\": \"2014-12-10T18:00:00.000Z\",\n      \"FrequencyCount\": 3,\n      \"FrequencyInterval\": \"Day\",\n      \"Id\": \"345233\",\n      \"Quantity\": 30000,\n      \"Name\": \"My Line 1\",\n      \"OrderId\": \"1235872\",\n      \"ProductId\": \"456366\",\n      \"ProviderData\": \"cid=88873\",\n      \"StartDate\": \"2014-12-05T06:00:00.000Z\",\n      \"Targeting\": [\n        {\n          \"Target\": \"Age\",\n          \"TargetValues\": [\"18-24\",\"25-34\"]\n        },\n        {\n          \"Target\": \"Gender\",\n          \"TargetValues\": [\"Male\"]\n        }\n      ]\n      \"UsesExpandables\": False\n    }\n  ]\n}\n"
  parameters:
    accountId:
      name: accountId
      in: path
      required: true
      x-example: '23873345'
      schema:
        type: string
        maxLength: 36
    changerequestId:
      name: changerequestId
      in: path
      required: true
      x-example: '398421'
      schema:
        type: string
        maxLength: 36
    lineId:
      name: lineId
      in: path
      required: true
      x-example: '345233'
      schema:
        type: string
        maxLength: 36
  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.