> ## 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.

# Select integration external account

> Mark one discovered external provider account as the selected account for a buyer integration connection.



## OpenAPI

````yaml /v2/buyer-api-v2.yaml patch /storefront-connections/{connectionId}/accounts/{accountId}/select
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: Account
    description: Account management, service tokens, and preferences
  - 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: Planning Briefs
    description: >-
      Share prospective briefs with publishers and collect their
      fit/quote/clarify/decline/book responses (gated by the
      demand-supply-signals flag).
  - 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:
  /storefront-connections/{connectionId}/accounts/{accountId}/select:
    patch:
      tags:
        - Storefronts
      summary: Select integration external account
      description: >-
        Mark one discovered external provider account as the selected account
        for a buyer integration connection.
      operationId: selectStorefrontConnectionAccount
      parameters:
        - in: path
          name: connectionId
          schema:
            description: Storefront connection ID
            type: integer
            format: int64
          required: true
          description: Storefront connection ID
        - in: path
          name: accountId
          schema:
            description: Storefront connection account ID
            type: integer
            format: int64
          required: true
          description: Storefront connection account ID
      responses:
        '200':
          description: Select integration external account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontConnectionAccount'
        '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'
      security:
        - bearerAuth: []
components:
  schemas:
    StorefrontConnectionAccount:
      description: Provider account discovered for a buyer storefront connection.
      type: object
      properties:
        id:
          type: string
        connectionId:
          type: string
        credentialId:
          nullable: true
          type: string
        externalAccountId:
          type: string
        name:
          nullable: true
          type: string
        advertiser:
          description: Provider-reported advertiser identity after safe normalization.
          nullable: true
          type: string
        currency:
          description: Authoritative provider account currency when the adapter reports it.
          nullable: true
          type: string
          pattern: ^[A-Z]{3}$
        status:
          type: string
          enum:
            - PENDING
            - ACTIVE
            - DISABLED
            - ERROR
        providerStatus:
          description: Normalized AdCP account status reported by the provider adapter.
          nullable: true
          type: string
          enum:
            - active
            - pending_approval
            - payment_required
            - rejected
            - suspended
            - closed
        providerRawStatus:
          description: >-
            Safe provider-native status value retained for diagnosis, when
            reported.
          nullable: true
          anyOf:
            - type: string
            - type: number
        accountType:
          description: >-
            Account hierarchy classification from the platform adapter:
            'advertiser' (buyable leaf), 'organization' (manager container —
            never mappable or buyable), or a platform subtype such as
            'sponsored_ads', 'dsp', or 'publisher_identity'. Null for legacy
            rows, treated as a leaf account.
          default: null
          nullable: true
          type: string
        parentExternalId:
          description: >-
            External id of the parent account, when known: a manager container
            (Meta Business Manager, Google MCC, Snap Organization, …), or where
            the platform has no manager surface, the owning entity (LinkedIn
            organization; the owning advertiser account for TikTok channel
            identities). Id format is platform-native and may differ from the
            account's own id format.
          default: null
          nullable: true
          type: string
        parentName:
          description: Display name of the parent account, when known.
          default: null
          nullable: true
          type: string
        isDefault:
          type: boolean
        isSelected:
          type: boolean
        archivedAt:
          nullable: true
          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))$
        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))$
        mappedAdvertisers:
          description: Advertisers this external account is mapped to for buyer workflows.
          default: []
          type: array
          items:
            $ref: '#/components/schemas/StorefrontConnectionAccountAdvertiserMapping'
        campaignRollup:
          description: >-
            Directed-campaign rollup for this account. Present only when the
            account has live campaign mirrors and a resolvable currency; omitted
            otherwise.
          allOf:
            - $ref: '#/components/schemas/StorefrontConnectionAccountCampaignRollup'
      required:
        - id
        - connectionId
        - credentialId
        - externalAccountId
        - name
        - advertiser
        - currency
        - status
        - providerStatus
        - providerRawStatus
        - accountType
        - parentExternalId
        - parentName
        - isDefault
        - isSelected
        - archivedAt
        - createdAt
        - updatedAt
        - mappedAdvertisers
      additionalProperties: false
    ErrorResponse:
      description: Standard error response
      type: object
      properties:
        data:
          type: string
          nullable: true
          enum:
            - null
        error:
          $ref: '#/components/schemas/ApiError'
      required:
        - data
        - error
      additionalProperties: false
    StorefrontConnectionAccountAdvertiserMapping:
      description: >-
        Advertiser mapping for an external account discovered through an
        integration.
      type: object
      properties:
        linkId:
          description: >-
            Identifier of the advertiser-account link row. Pass to DELETE
            /advertisers/{advertiserId}/accounts/{linkId} to unmap.
          type: string
        sourceId:
          description: >-
            Canonical provider ID for an official adapter, or the inventory
            source ID for an external AdCP connection.
          type: string
        sourceName:
          description: Display name for the inventory source.
          type: string
        agentId:
          description: Partner agent ID that receives this mapping.
          type: string
        advertiserId:
          description: Advertiser linked to this discovered provider account.
          type: string
        advertiserName:
          description: Display name for the linked advertiser.
          type: string
        unreachableAt:
          description: >-
            When set, this mapping is preserved but its platform account is no
            longer reachable through any active connection — relink the platform
            (or re-map the account) to restore it. Unreachable mappings never
            resolve at buy time.
          default: null
          nullable: true
          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))$
        linkedAt:
          description: When the provider account was first linked.
          nullable: true
          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:
          description: When the provider account mapping was last updated.
          nullable: true
          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:
        - linkId
        - sourceId
        - sourceName
        - agentId
        - advertiserId
        - advertiserName
        - unreachableAt
        - linkedAt
        - updatedAt
      additionalProperties: false
    StorefrontConnectionAccountCampaignRollup:
      description: >-
        Directed-campaign rollup for one connected account: tracked = mirrored
        read-only from the connected seller account; managed = authored through
        the platform. Spend is seller-reported net in the account currency; sums
        cover delivery denominated in (or reported without) that currency.
      type: object
      properties:
        campaignsTracked:
          description: >-
            Non-retired tracked campaigns on this account. A tracked campaign is
            a campaign the platform did not set up, mirrored read-only from the
            connected seller account.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        campaignsActive:
          description: >-
            Subset of campaignsTracked whose campaign status is currently
            ACTIVE.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        trackedSpend:
          description: >-
            Delivered spend across tracked campaigns over the trailing window,
            in the account currency. Seller-reported net — directed buys
            dispatch the full media budget zero-fee, so net equals the buyer's
            budget.
          type: number
          minimum: 0
        managedSpend:
          description: >-
            Delivered spend across managed campaigns (authored through the
            platform) over the trailing window, in the account currency.
            Seller-reported net, same denomination as trackedSpend.
          type: number
          minimum: 0
        managedShare:
          description: >-
            The adoption metric for this relationship: managedSpend /
            (trackedSpend + managedSpend). Null when no spend was accounted in
            the window.
          nullable: true
          type: number
          minimum: 0
          maximum: 1
        currency:
          description: >-
            ISO 4217 currency all spend values in this rollup are denominated in
            — always the account currency. Rollups are never summed across
            currencies.
          type: string
          pattern: ^[A-Z]{3}$
        windowDays:
          description: >-
            Trailing window, in days, the spend aggregates cover (currently
            365).
          type: integer
          maximum: 9007199254740991
          minimum: 1
      required:
        - campaignsTracked
        - campaignsActive
        - trackedSpend
        - managedSpend
        - managedShare
        - currency
        - windowDays
      additionalProperties: false
    ApiError:
      description: Structured error object
      type: object
      properties:
        code:
          description: Machine-readable error code
          type: string
        message:
          description: Human-readable error message
          type: string
        field:
          description: Field path associated with the error
          type: string
        details:
          description: Additional error context
          type: object
          additionalProperties: {}
      required:
        - code
        - message
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````