> ## Documentation Index
> Fetch the complete documentation index at: https://docs.interchange.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an organization advertiser lifecycle

> Create and return either an owned managed advertiser lifecycle or a single-use confined self-serve invitation lifecycle. This limited beta requires an active advertiser-lifecycle entitlement with separate managed and self-serve limits; self-serve invitations also require the storefront self-service buyer rollout gate.



## OpenAPI

````yaml /v2/buyer-api-v2.yaml post /organization/advertisers
openapi: 3.0.0
info:
  title: Scope3 Buyer 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
security: []
tags:
  - name: Signup
    description: Request reviewed access to Interchange
  - name: Account
    description: Account management, service tokens, and preferences
  - name: Asks
    description: >-
      What you are waiting on Scope3 for — support, product, and supply asks in
      one list
  - name: Advertisers
    description: Manage advertisers
  - name: Product Discovery
    description: Discover and select products
  - name: Campaigns
    description: Manage advertising campaigns
  - name: Creatives
    description: Build, manage, and sync campaign creatives via AdCP Creative Protocol
  - name: Reporting
    description: Access performance metrics
  - name: Event Sources
    description: >-
      Manage event source configurations and log conversion/marketing events for
      attribution
  - name: Property Lists
    description: Validate property lists against AAO registry
  - name: Sales Agents
    description: View and connect sales agents
  - name: Measurement
    description: Measurement sources, records, context, and freshness
  - name: Syndication
    description: Syndicate resources to ADCP agents
  - name: Tasks
    description: Track async operation status
  - name: Buyer Billing
    description: >-
      Consolidated invoicing for buyers — invoices and pending invoice items
      issued by Scope3 across the buyer customer.
  - name: MCP
    description: Model Context Protocol endpoints for AI agents
paths:
  /organization/advertisers:
    servers:
      - url: https://api.interchange.io/api/v2
        description: Production server
    post:
      tags:
        - Advertisers
      summary: Create an organization advertiser lifecycle
      description: >-
        Create and return either an owned managed advertiser lifecycle or a
        single-use confined self-serve invitation lifecycle. This limited beta
        requires an active advertiser-lifecycle entitlement with separate
        managed and self-serve limits; self-serve invitations also require the
        storefront self-service buyer rollout gate.
      operationId: createOrganizationAdvertiser
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                operatingMode:
                  type: string
                  enum:
                    - managed
                displayName:
                  type: string
                  minLength: 1
                  maxLength: 255
                accountId:
                  type: integer
                  minimum: 0
                  exclusiveMinimum: true
                  maximum: 9007199254740991
                sandbox:
                  default: false
                  type: boolean
              required:
                - operatingMode
                - displayName
              additionalProperties: false
      responses:
        '201':
          description: Create an organization advertiser lifecycle
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrganizationAdvertiserMutationApiResponse'
        '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: >-
            Organization administrator, advertiser-lifecycle entitlement, or
            self-service rollout access is missing
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The explicit per-mode capacity is exhausted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearerAuth: []
components:
  schemas:
    OrganizationAdvertiserMutationApiResponse:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/OrganizationAdvertiserMutationResponse'
        error:
          type: string
          nullable: true
          enum:
            - null
      required:
        - data
        - error
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        data:
          type: string
          nullable: true
          enum:
            - null
        error:
          $ref: '#/components/schemas/ApiError'
      required:
        - data
        - error
      additionalProperties: false
      description: Standard error response
    OrganizationAdvertiserMutationResponse:
      type: object
      properties:
        lifecycle:
          type: object
          properties:
            lifecycleId:
              type: string
              pattern: ^\d+$
            displayName:
              type: string
              minLength: 1
            provisioningMode:
              type: string
              enum:
                - managed
                - self_serve
            state:
              type: string
              enum:
                - invited
                - provisioning
                - ready
                - failed
                - revoked
            advertiserId:
              nullable: true
              type: string
              pattern: ^\d+$
            targetAccountId:
              nullable: true
              type: integer
              minimum: 0
              exclusiveMinimum: true
              maximum: 9007199254740991
            managementCapability:
              type: string
              enum:
                - available
                - account_switch_required
                - unavailable
            joinLink:
              type: string
              nullable: true
              enum:
                - null
            failure:
              nullable: true
              type: object
              properties:
                code:
                  type: string
                  minLength: 1
                recoverable:
                  type: boolean
                  enum:
                    - true
              required:
                - code
                - recoverable
              additionalProperties: false
            createdAt:
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
            updatedAt:
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
          required:
            - lifecycleId
            - displayName
            - provisioningMode
            - state
            - advertiserId
            - targetAccountId
            - managementCapability
            - joinLink
            - failure
            - createdAt
            - updatedAt
          additionalProperties: false
        advertiser:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/AdvertiserRosterEntry'
      required:
        - lifecycle
        - advertiser
      additionalProperties: false
      description: Audited lifecycle result for a managed advertiser creation or mutation.
    ApiError:
      type: object
      properties:
        code:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error message
        field:
          description: Field path associated with the error
          type: string
        details:
          description: Additional error context
          type: object
          additionalProperties: {}
      required:
        - code
        - message
      additionalProperties: false
      description: Structured error object
    AdvertiserRosterEntry:
      type: object
      properties:
        rosterEntryId:
          type: string
          minLength: 1
        advertiserId:
          type: string
          minLength: 1
        displayName:
          type: string
          minLength: 1
        relationshipClass:
          type: string
          enum:
            - owned
            - delegated
            - counterparty
        operatorRelationship:
          type: string
          enum:
            - organization
            - client
            - external
        operatingMode:
          type: string
          enum:
            - managed
            - self_serve
        sandbox:
          type: boolean
        system:
          type: boolean
        binding:
          type: object
          properties:
            provenance:
              type: string
              enum:
                - compatibility_account
                - seller_buyer_sponsorship
                - advertiser_grant
                - adcp_account
            state:
              type: string
              enum:
                - resolved
                - partial
                - conflict
            reason:
              nullable: true
              type: string
              enum:
                - backing_account_missing
                - backing_account_is_container
                - display_name_missing
                - self_serve_sponsorship_missing
                - sponsorship_parent_mismatch
                - sponsorship_storefront_missing
                - duplicate_backing_records
          required:
            - provenance
            - state
            - reason
          additionalProperties: false
        backing:
          $ref: '#/components/schemas/AdvertiserRosterBacking'
        delegation:
          nullable: true
          type: object
          properties:
            grantRef:
              type: string
              format: uuid
              pattern: >-
                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            owner:
              type: object
              properties:
                organizationRef:
                  type: string
                  format: uuid
                  pattern: >-
                    ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                displayName:
                  type: string
                  minLength: 1
                  maxLength: 200
              required:
                - organizationRef
                - displayName
              additionalProperties: false
            capabilities:
              minItems: 1
              type: array
              items:
                type: string
                enum:
                  - advertiser.read
                  - campaign.read
                  - campaign.manage
            status:
              type: string
              enum:
                - active
            expiresAt:
              type: string
              format: date-time
              pattern: >-
                ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
          required:
            - grantRef
            - owner
            - capabilities
            - status
            - expiresAt
          additionalProperties: false
        capabilities:
          type: object
          properties:
            read:
              type: boolean
              enum:
                - true
            advertiserManagement:
              type: string
              enum:
                - available
                - account_switch_required
                - unavailable
            campaignManagement:
              type: string
              enum:
                - available
                - account_switch_required
                - unavailable
            relationshipManagement:
              type: string
              enum:
                - available
                - account_switch_required
                - unavailable
          required:
            - read
            - advertiserManagement
            - campaignManagement
            - relationshipManagement
          additionalProperties: false
        readiness:
          type: object
          properties:
            state:
              type: string
              enum:
                - ready
                - pending
                - suspended
                - revoked
                - disabled
                - incomplete
          required:
            - state
          additionalProperties: false
        operatorDomain:
          type: string
          maxLength: 253
          pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$
        operatorDisplayName:
          nullable: true
          type: string
          minLength: 1
        brandDomain:
          type: string
          maxLength: 253
          pattern: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+$
      required:
        - rosterEntryId
        - advertiserId
        - displayName
        - relationshipClass
        - operatorRelationship
        - operatingMode
        - sandbox
        - system
        - binding
        - backing
        - delegation
        - capabilities
        - readiness
      additionalProperties: false
      description: >-
        One canonical advertiser relationship visible to the organization
        caller.
    AdvertiserRosterBacking:
      oneOf:
        - type: object
          properties:
            kind:
              type: string
              enum:
                - compatibility_account
            accountId:
              type: integer
              minimum: 0
              exclusiveMinimum: true
              maximum: 9007199254740991
            advertiserId:
              type: string
              minLength: 1
          required:
            - kind
            - accountId
            - advertiserId
          additionalProperties: false
        - type: object
          properties:
            kind:
              type: string
              enum:
                - authorized_relationship
            relationshipRef:
              type: string
              format: uuid
              pattern: >-
                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            advertiserId:
              type: string
              minLength: 1
          required:
            - kind
            - relationshipRef
            - advertiserId
          additionalProperties: false
      description: >-
        Authorized backing boundary. Foreign tenant identifiers are never
        exposed.
      type: object
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````