Scope3 Advertisers API

openapi: 3.2.0
info:
  title: Scope3 Buyer Advertisers API
  version: 2.0.0
  description: 'REST API for advertisers to manage advertisers, campaigns, and reporting.


    ## Authentication


    All endpoints require a Bearer token in the Authorization header:

    ```

    Authorization: Bearer your-api-key

    ```


    ## Base URL


    `https://api.interchange.io/api/v2/buyer`


    ## For AI Agents


    AI agents can use the MCP endpoint at `/mcp/v2/buyer` with three tools:

    - `initialize`: Start an MCP session

    - `api_call`: Make REST API calls

    - `ask_about_capability`: Learn about API features'
servers:
- url: https://api.interchange.io/api/v2/buyer
  description: Production server
tags:
- name: Advertisers
  description: Manage advertisers
paths:
  /advertisers:
    get:
      operationId: listAdvertisers
      summary: List advertisers
      description: List all advertisers with optional filtering and pagination.
      tags:
      - Advertisers
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: status
        schema:
          description: Filter by advertiser status. Use ALL to include both active and archived. Defaults to ACTIVE.
          default: ACTIVE
          type: string
          enum:
          - ACTIVE
          - ARCHIVED
          - ALL
        description: Filter by advertiser status. Use ALL to include both active and archived. Defaults to ACTIVE.
      - in: query
        name: name
        schema:
          description: Filter by advertiser name (case-insensitive, partial match)
          example: Acme
          type: string
        description: Filter by advertiser name (case-insensitive, partial match)
      - in: query
        name: linkedAccountPartnerId
        schema:
          description: Filter to advertisers linked to at least one account from this partner / sales agent ID.
          example: snap
          type: string
        description: Filter to advertisers linked to at least one account from this partner / sales agent ID.
      - in: query
        name: sandbox
        schema:
          description: Filter by sandbox mode. true returns only sandbox advertisers, false returns only production advertisers. Omit to return all.
          type: boolean
        description: Filter by sandbox mode. true returns only sandbox advertisers, false returns only production advertisers. Omit to return all.
      - in: query
        name: includeBrand
        schema:
          description: When true, include linked brand identity data on advertiser summary rows so creative agents can use brand logos, colors, tone, and catalog data.
          type: boolean
        description: When true, include linked brand identity data on advertiser summary rows so creative agents can use brand logos, colors, tone, and catalog data.
      - in: query
        name: limit
        schema:
          description: 'Maximum number of advertisers to return per page (default: 100, max: 100)'
          example: 100
          default: 100
          type: integer
          maximum: 100
          minimum: 1
        description: 'Maximum number of advertisers to return per page (default: 100, max: 100)'
      - in: query
        name: offset
        schema:
          description: 'Number of advertisers to skip for pagination (default: 0)'
          example: 0
          default: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
        description: 'Number of advertisers to skip for pagination (default: 0)'
      responses:
        '200':
          description: List advertisers
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvertiserListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: createAdvertiser
      summary: Create advertiser
      description: Create a new advertiser. Advertisers are the top-level entity for campaigns.
      tags:
      - Advertisers
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAdvertiserBody'
      responses:
        '201':
          description: Create advertiser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Advertiser'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /all-advertisers-home:
    get:
      operationId: listAllAdvertisersHome
      summary: List all advertisers home
      description: 'Pre-assembled data for the buyer "All Advertisers Landing" widget: advertiser rows (brand kit, campaign count, resumable-draft flag) plus a portfolio summary. Money rollups (`managed`/`tracked`) are always null pending AI-5642; `attention`/`nextAction` are omitted pending AI-5643.'
      tags:
      - Advertisers
      security:
      - bearerAuth: []
      responses:
        '200':
          description: List all advertisers home
          content:
            application/json:
              schema:
                type: object
                properties:
                  portfolio:
                    type: object
                    properties:
                      tracked:
                        type: string
                      managed:
                        type: string
                      waitingOnYou:
                        type: number
                    required:
                    - tracked
                    - managed
                    - waitingOnYou
                    additionalProperties: false
                  advertisers:
                    type: array
                    items:
                      type: object
                      properties:
                        advertiserId:
                          type: string
                        name:
                          type: string
                        initials:
                          type: string
                        brandColors:
                          type: object
                          additionalProperties:
                            type: string
                        logoUrl:
                          type: string
                        logoTileColor:
                          type: string
                        logoFill:
                          type: boolean
                        managed:
                          type:
                          - string
                          - 'null'
                        tracked:
                          type:
                          - string
                          - 'null'
                        campaignCount:
                          type: number
                        resumableDraft:
                          type: boolean
                        attention:
                          type: object
                          properties:
                            flags:
                              type: array
                              items:
                                type: object
                                properties:
                                  label:
                                    type: string
                                  tone:
                                    type: string
                                    enum:
                                    - critical
                                    - needsAction
                                    - info
                                required:
                                - label
                                - tone
                                additionalProperties: false
                          required:
                          - flags
                          additionalProperties: false
                        nextAction:
                          type: object
                          properties:
                            label:
                              type: string
                          required:
                          - label
                          additionalProperties: false
                      required:
                      - advertiserId
                      - name
                      - initials
                      - managed
                      - tracked
                      - campaignCount
                      - resumableDraft
                      additionalProperties: false
                  currentAdvertiserId:
                    type: string
                required:
                - portfolio
                - advertisers
                additionalProperties: false
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}:
    get:
      operationId: getAdvertiser
      summary: Get advertiser
      description: Get a single advertiser by ID. Always returns full brand details including the ADCP manifest.
      tags:
      - Advertisers
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: advertiserId
        schema:
          description: Unique identifier for the advertiser
          example: '12345'
          type: string
          minLength: 1
        required: true
        description: Unique identifier for the advertiser
      responses:
        '200':
          description: Get advertiser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Advertiser'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      operationId: updateAdvertiser
      summary: Update advertiser
      description: Update an existing advertiser.
      tags:
      - Advertisers
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: advertiserId
        schema:
          description: Unique identifier for the advertiser
          example: '12345'
          type: string
          minLength: 1
        required: true
        description: Unique identifier for the advertiser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAdvertiserBody'
      responses:
        '200':
          description: Update advertiser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Advertiser'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      operationId: deleteAdvertiser
      summary: Delete advertiser
      description: Delete (archive) an advertiser.
      tags:
      - Advertisers
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: advertiserId
        schema:
          description: Unique identifier for the advertiser
          example: '12345'
          type: string
          minLength: 1
        required: true
        description: Unique identifier for the advertiser
      responses:
        '204':
          description: No content
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/restore:
    post:
      operationId: restoreAdvertiser
      summary: Restore advertiser
      description: Restore a previously deleted (archived) advertiser, making it active again.
      tags:
      - Advertisers
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: advertiserId
        schema:
          description: Unique identifier for the advertiser
          example: '12345'
          type: string
          minLength: 1
        required: true
        description: Unique identifier for the advertiser
      responses:
        '200':
          description: Restore advertiser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Advertiser'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No archived advertiser with this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/data-delivery-credentials/{name}/validate:
    post:
      operationId: revalidateDataDeliveryCredential
      summary: Revalidate data delivery credential
      description: Re-runs the destination Probe for a supported object-storage credential and returns the updated record with a fresh status (VALIDATED or FAILED). Use after fixing a buyer-side destination access issue (e.g., re-granting GCS bucket IAM) without otherwise editing the credential.
      tags:
      - Advertisers
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: advertiserId
        schema:
          description: Advertiser ID (numeric, as a string).
          type: string
          minLength: 1
        required: true
        description: Advertiser ID (numeric, as a string).
      - in: path
        name: name
        schema:
          description: Credential name (unique per advertiser).
          type: string
          minLength: 1
        required: true
        description: Credential name (unique per advertiser).
      responses:
        '200':
          description: Revalidate data delivery credential
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RevalidateDataDeliveryCredentialResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/accounts:
    get:
      operationId: listAdvertiserAccounts
      summary: List advertiser accounts
      description: List the sales-agent accounts already linked to an advertiser, with optional filtering by sales agent.
      tags:
      - Advertisers
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: storefrontId
        schema:
          description: Filter accounts to those reachable through this storefront. Pair with `sourceId`.
          example: 42
          type: integer
          maximum: 9007199254740991
          minimum: 1
        description: Filter accounts to those reachable through this storefront. Pair with `sourceId`.
      - in: query
        name: sourceId
        schema:
          description: Filter accounts to those reachable through this inventory source. Pair with `storefrontId`.
          example: src_main
          type: string
          minLength: 1
        description: Filter accounts to those reachable through this inventory source. Pair with `storefrontId`.
      - in: query
        name: status
        schema:
          description: Filter by account status
          type: string
          enum:
          - active
          - pending_approval
          - payment_required
          - suspended
          - closed
          - unreachable
        description: Filter by account status
      - in: query
        name: take
        schema:
          description: Number of results to return (max 250)
          example: 50
          default: 50
          type: integer
          maximum: 250
          minimum: 1
        description: Number of results to return (max 250)
      - in: query
        name: skip
        schema:
          description: Number of results to skip for pagination
          example: 0
          default: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
        description: Number of results to skip for pagination
      - in: path
        name: advertiserId
        schema:
          description: Unique identifier for the advertiser
          example: '12345'
          type: string
          minLength: 1
        required: true
        description: Unique identifier for the advertiser
      responses:
        '200':
          description: List advertiser accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    post:
      operationId: assignAccount
      summary: Assign account
      description: Link a partner (source) account discovered via `list_available_accounts` to an advertiser.
      tags:
      - Advertisers
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: advertiserId
        schema:
          description: Unique identifier for the advertiser
          example: '12345'
          type: string
          minLength: 1
        required: true
        description: Unique identifier for the advertiser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignAccountBody'
      responses:
        '201':
          description: Assign account
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/accounts/{accountId}:
    get:
      operationId: getAdvertiserAccount
      summary: Get advertiser account
      description: Get a single linked sales-agent account on an advertiser by its account id.
      tags:
      - Advertisers
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: advertiserId
        schema:
          description: Unique identifier for the advertiser
          example: '12345'
          type: string
          minLength: 1
        required: true
        description: Unique identifier for the advertiser
      - in: path
        name: accountId
        schema:
          description: Unique identifier for the account
          example: acc_67890
          type: string
          minLength: 1
        required: true
        description: Unique identifier for the account
      responses:
        '200':
          description: Get advertiser account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdvertiserAccount'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No linked account with this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/accounts/available:
    get:
      operationId: listAvailableAccounts
      summary: List available accounts
      description: Discover accounts available to link to an advertiser from a specific sales agent.
      tags:
      - Advertisers
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: storefrontId
        schema:
          description: Storefront the source lives on. Pair with `sourceId` to identify the source whose accounts to list.
          example: 42
          type: integer
          maximum: 9007199254740991
          minimum: 1
        required: true
        description: Storefront the source lives on. Pair with `sourceId` to identify the source whose accounts to list.
      - in: query
        name: sourceId
        schema:
          description: Inventory source within `storefrontId` whose accounts to list.
          example: src_main
          type: string
          minLength: 1
        required: true
        description: Inventory source within `storefrontId` whose accounts to list.
      - in: query
        name: refresh
        schema:
          description: When true, re-fetches accounts from the source before returning results. Defaults to false (returns cached accounts).
          example: 'false'
          type: string
          enum:
          - 'true'
          - 'false'
        description: When true, re-fetches accounts from the source before returning results. Defaults to false (returns cached accounts).
      - in: query
        name: billingType
        schema:
          description: Billing arrangement type to filter accounts by (e.g. "advertiser", "operator", "agent"). Must be one of the values supported by this source. Defaults to the source's default billing type if omitted.
          example: advertiser
          type: string
        description: Billing arrangement type to filter accounts by (e.g. "advertiser", "operator", "agent"). Must be one of the values supported by this source. Defaults to the source's default billing type if omitted.
      - in: query
        name: credentialId
        schema:
          description: ID of a specific registered credential to use for account discovery. Required when the customer has multiple credentials registered for this source. Use GET /storefronts/credentials to list registered credentials and their IDs.
          example: '42'
          type: string
        description: ID of a specific registered credential to use for account discovery. Required when the customer has multiple credentials registered for this source. Use GET /storefronts/credentials to list registered credentials and their IDs.
      - in: query
        name: take
        schema:
          description: Number of results to return (max 250)
          example: 50
          default: 50
          type: integer
          maximum: 250
          minimum: 1
        description: Number of results to return (max 250)
      - in: query
        name: skip
        schema:
          description: Number of results to skip for pagination
          example: 0
          default: 0
          type: integer
          minimum: 0
          maximum: 9007199254740991
        description: Number of results to skip for pagination
      - in: path
        name: advertiserId
        schema:
          description: Unique identifier for the advertiser
          example: '12345'
          type: string
          minLength: 1
        required: true
        description: Unique identifier for the advertiser
      responses:
        '200':
          description: List available accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AvailableAccountListResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/accounts/{linkId}:
    delete:
      operationId: unassignAccount
      summary: Unmap a partner account from an advertiser
      description: Soft-delete an advertiser-account link by its `linkId` (returned on mapping rows). The link is preserved for period history; buys for the advertiser on that platform fail with `account_mapping_required` until a new mapping is made.
      tags:
      - Advertisers
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: advertiserId
        schema:
          description: Unique identifier for the advertiser
          example: '12345'
          type: string
          minLength: 1
        required: true
        description: Unique identifier for the advertiser
      - in: path
        name: linkId
        schema:
          description: Identifier of the advertiser-account link row (numeric primary key)
          example: '42'
          type: string
          pattern: ^\d{1,15}$
        required: true
        description: Identifier of the advertiser-account link row (numeric primary key)
      responses:
        '200':
          description: Unmap a partner account from an advertiser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountUnlinked'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The advertiser does not belong to the caller
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: The link does not exist or belongs to another advertiser
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/accounts/{linkId}/reporting-bucket:
    put:
      operationId: updateAccountReportingBucket
      summary: Update account reporting bucket
      description: 'Set or clear the offline `reporting_bucket` configuration on a linked partner account, then notify the seller via `sync_accounts`. Pass `reporting_bucket: null` to clear the bucket.'
      tags:
      - Advertisers
      security:
      - bearerAuth: []
      parameters:
      - in: path
        name: advertiserId
        schema:
          description: Unique identifier for the advertiser
          example: '12345'
          type: string
          minLength: 1
        required: true
        description: Unique identifier for the advertiser
      - in: path
        name: linkId
        schema:
          description: Identifier of the advertiser-account link row (numeric primary key)
          example: '42'
          type: string
          pattern: ^\d{1,15}$
        required: true
        description: Identifier of the advertiser-account link row (numeric primary key)
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateReportingBucketBody'
      responses:
        '200':
          description: Update account reporting bucket
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountResponse'
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /advertisers/{advertiserId}/catalogs:
    get:
      operationId: listCatalogs
      summary: List catalogs
      description: List catalogs that have been synced for an advertiser.
      tags:
      - Advertisers
      security:
      - bearerAuth: []
      parameters:
      - in: query
        name: type
        schema:
          type: string
          enum:
          - offering
          - product
          - inventory
       

# --- truncated at 32 KB (223 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/scope3/refs/heads/main/openapi/scope3-advertisers-api-openapi.yml