IAB Tech Lab Accounts API

openapi: 3.2.0
info:
  version: 1.5.1
  title: OpenDirect Accounts 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: Accounts
paths:
  /accounts:
    get:
      tags:
      - Accounts
      description: 'Gets a list of all accounts.

        For an advertiser, the list of accounts will include only accounts that they own. However, for an agency, the list of accounts will include the accounts that they own and the accounts that they manage on behalf of advertisers.

        User should be able to filter the accounts by any of the fields or field values of the owned account. Logical AND/OR condition of the fields shall be allowed.'
      parameters:
      - $ref: '#/components/parameters/count'
      - $ref: '#/components/parameters/offset'
      - name: $filter
        in: query
        description: 'Allows to get a list of accounts that match the specified filter criteria. The user may use OData expressions with the following Account properties:

          - AdvertiserId

          - BuyerId

          May also support getting a list of IDs.

          '
        schema:
          type: string
      responses:
        200:
          $ref: '#/components/responses/AccountsResponse'
        401:
          $ref: '#/components/responses/Standard401ErrorResponse'
        500:
          $ref: '#/components/responses/Standard500ErrorResponse'
      summary: Get accounts
      x-summary-source: derived
      operationId: getAccounts
      x-operation-id-source: derived
    post:
      tags:
      - Accounts
      description: 'Adds an account.

        An advertiser or agency may add accounts to only the organization they own; an agency may not add accounts to an advertiser’s organization. If an advertiser wants an agency to manage an account on their behalf, the advertiser must add the account and set the account’s BuyerId to the agency’s organization ID.

        An organization may add as many accounts as needed to create a buying structure that supports their needs. For example, the organization may create a single account, an account for each region, an account for each brand, and so on.'
      responses:
        201:
          $ref: '#/components/responses/AccountResponse'
        400:
          $ref: '#/components/responses/Standard400ErrorResponse'
        401:
          $ref: '#/components/responses/Standard401ErrorResponse'
        500:
          $ref: '#/components/responses/Standard500ErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Account'
        required: true
      summary: Create accounts
      x-summary-source: derived
      operationId: postAccounts
      x-operation-id-source: derived
  /accounts/{accountId}:
    get:
      tags:
      - Accounts
      description: 'Gets the specified account.

        The user must have permissions to perform the requested action. For example, advertisers and agencies may get the accounts that they own. In addition, an agency may get the accounts that they manage on behalf of advertisers.'
      parameters:
      - $ref: '#/components/parameters/accountId'
      responses:
        200:
          $ref: '#/components/responses/AccountResponse'
        401:
          $ref: '#/components/responses/Standard401ErrorResponse'
        404:
          $ref: '#/components/responses/Standard404ErrorResponse'
        500:
          $ref: '#/components/responses/Standard500ErrorResponse'
      summary: Get accounts by account id
      x-summary-source: derived
      operationId: getAccountsByAccountId
      x-operation-id-source: derived
components:
  responses:
    AccountResponse:
      description: Account resource
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Account'
          example: "{\n  \"AdvertiserId\": \"1234987\",\n  \"BuyerId\": \"34587\",\n  \"Id\": \"23873345\",\n  \"Name\": \"Brand A\",\n  \"ProviderData\": \"cid=934759\"\n}\n"
    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"
    AccountsResponse:
      description: Collection of Account
      headers:
        X-Total-Count:
          description: Total number of results
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Accounts'
          example: "{\n  \"Accounts\": [\n    {\n      \"AdvertiserId\": \"1234987\",\n      \"BuyerId\": \"1234987\",\n      \"Id\": \"9876542\",\n      \"Name\": \"Brand B\",\n      \"ProviderData\": \"cid=8934579\"\n    },\n    {\n      \"AdvertiserId\": \"1234987\",\n      \"BuyerId\": \"34587\",\n      \"Id\": \"23873345\",\n      \"Name\": \"Brand A\",\n      \"ProviderData\": \"cid=934759\"\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"
  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
    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:
    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
    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
    Account:
      description: 'An account defines a buyer-advertiser relationship. A buyer is typically an agency that places orders on behalf of several advertisers. Each account associates a buyer with one advertiser and is used to manage orders for one publisher. An advertiser may also work with several buyers, and therefore, advertisers have a separate account for each buyer they work with. If an advertiser represents itself, the account identifies the advertiser as both the buyer and the advertiser.

        Before an agency may create accounts and perform buys on behalf of the advertiser, the advertiser must give permissions to the agency. The process of giving or removing permissions is publisher-defined. Creating an account must fail if the advertiser has not given the agency permissions.

        The Account owns the orders and creative.

        '
      allOf:
      - $ref: '#/components/schemas/Identity'
      - $ref: '#/components/schemas/ProviderData'
      - required:
        - AdvertiserId
        - BuyerId
        - Name
        properties:
          AdvertiserId:
            description: An ID that identifies the organization that is acting as the advertiser. Advertiser ID may be generated by the buyer (agency) or by the publisher if the advertiser is also the buyer. An advertiser that is representing itself must have an AdvertiserId and BuyerId that match.
            type: string
            maxLength: 36
          BuyerId:
            description: An ID that identifies the organization that is acting as the buyer. The Publisher generates the BuyerId. If the advertiser is performing their own buys, AdvertiserId and BuyerId must be the same.
            type: string
            maxLength: 36
          Name:
            description: The name of the account. Used for display purposes.
            type: string
            maxLength: 36
    Accounts:
      required:
      - Accounts
      properties:
        Accounts:
          type: array
          items:
            $ref: '#/components/schemas/Account'
  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.