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

# List integration external accounts

> List external provider accounts discovered for a buyer integration connection, including advertiser mappings.



## OpenAPI

````yaml /v2/buyer-api-v2.yaml get /storefront-connections/{connectionId}/accounts
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:
  /storefront-connections/{connectionId}/accounts:
    get:
      tags:
        - Storefronts
      summary: List integration external accounts
      description: >-
        List external provider accounts discovered for a buyer integration
        connection, including advertiser mappings.
      operationId: listStorefrontConnectionAccounts
      parameters:
        - in: path
          name: connectionId
          schema:
            description: Storefront connection ID
            type: integer
            format: int64
          required: true
          description: Storefront connection ID
      responses:
        '200':
          description: List integration external accounts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StorefrontConnectionAccountsResponse'
        '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:
    StorefrontConnectionAccountsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/StorefrontConnectionAccount'
      required:
        - items
      additionalProperties: false
      description: >-
        External accounts discovered for an integration, including advertiser
        mappings.
    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
    StorefrontConnectionAccount:
      type: object
      properties:
        id:
          type: string
        connectionId:
          type: string
        credentialId:
          nullable: true
          type: string
        externalAccountId:
          type: string
        name:
          nullable: true
          type: string
        advertiser:
          nullable: true
          description: Provider-reported advertiser identity after safe normalization.
          type: string
        currency:
          nullable: true
          description: Authoritative provider account currency when the adapter reports it.
          type: string
          pattern: ^[A-Z]{3}$
        effectiveTimezone:
          nullable: true
          description: >-
            Seller-effective IANA reporting timezone for this account. Reporting
            calendar boundaries for this account use this value; null when the
            provider has not reported one.
          type: string
        status:
          type: string
          enum:
            - PENDING
            - ACTIVE
            - DISABLED
            - ERROR
        providerStatus:
          nullable: true
          description: Normalized AdCP account status reported by the provider adapter.
          type: string
          enum:
            - active
            - pending_approval
            - payment_required
            - rejected
            - suspended
            - closed
        providerRawStatus:
          nullable: true
          description: >-
            Safe provider-native status value retained for diagnosis, when
            reported.
          anyOf:
            - type: string
            - type: number
        accountType:
          default: null
          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.
          nullable: true
          type: string
        amazonSponsoredAds:
          nullable: true
          description: >-
            Strict, allowlisted Amazon Ads profile projection. Present only for
            a sponsored_ads account with a valid marketplace ID and
            payment-method signal; null for every other account or malformed
            provider metadata.
          type: object
          properties:
            marketplaceId:
              type: string
              pattern: ^[A-Z0-9]{1,64}$
            countryCode:
              type: string
              pattern: ^[A-Z]{2}$
            validPaymentMethod:
              type: boolean
          required:
            - marketplaceId
            - validPaymentMethod
          additionalProperties: false
        parentExternalId:
          default: null
          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.
          nullable: true
          type: string
        parentName:
          default: null
          description: Display name of the parent account, when known.
          nullable: true
          type: string
        isDefault:
          type: boolean
        isSelected:
          type: boolean
        enhancedReporting:
          description: >-
            Account-scoped Enhanced Reporting control for any connected account.
            It is billed at the published per-account rate.
          allOf:
            - $ref: '#/components/schemas/EnhancedReportingAccountControl'
        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:
          default: []
          description: Advertisers this external account is mapped to for buyer workflows.
          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
        - effectiveTimezone
        - status
        - providerStatus
        - providerRawStatus
        - accountType
        - amazonSponsoredAds
        - parentExternalId
        - parentName
        - isDefault
        - isSelected
        - enhancedReporting
        - archivedAt
        - createdAt
        - updatedAt
        - mappedAdvertisers
      additionalProperties: false
      description: Provider account discovered for a buyer storefront connection.
    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
    EnhancedReportingAccountControl:
      type: object
      properties:
        eligible:
          type: boolean
        canEnable:
          description: >-
            Whether this currently disabled account can be enabled under the
            active accepted IU Rate Card. An enabled account remains disableable
            if billing authority changes.
          type: boolean
        enabled:
          type: boolean
        activatedAt:
          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))$
        disabledAt:
          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))$
        billingCustomerId:
          nullable: true
          type: integer
          minimum: 0
          exclusiveMinimum: true
          maximum: 9007199254740991
      required:
        - eligible
        - enabled
        - activatedAt
        - disabledAt
        - billingCustomerId
      additionalProperties: false
      description: Account-scoped Enhanced Reporting state and durable activation boundary.
    StorefrontConnectionAccountAdvertiserMapping:
      type: object
      properties:
        linkId:
          type: string
          description: >-
            Identifier of the advertiser-account link row. Pass to DELETE
            /advertisers/{advertiserId}/accounts/{linkId} to unmap.
        sourceId:
          type: string
          description: >-
            Canonical provider ID for an official adapter, or the inventory
            source ID for an external AdCP connection.
        sourceName:
          type: string
          description: Display name for the inventory source.
        agentId:
          type: string
          description: Partner agent ID that receives this mapping.
        advertiserId:
          type: string
          description: Advertiser linked to this discovered provider account.
        advertiserName:
          type: string
          description: Display name for the linked advertiser.
        advertiserPreferredTimezone:
          nullable: true
          description: >-
            The linked advertiser reporting time-zone preference, or null when
            no valid IANA time zone is configured.
          type: string
        unreachableAt:
          default: null
          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.
          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:
          nullable: true
          description: When the provider account was first linked.
          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:
          nullable: true
          description: When the provider account mapping was last updated.
          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
        - advertiserPreferredTimezone
        - unreachableAt
        - linkedAt
        - updatedAt
      additionalProperties: false
      description: >-
        Advertiser mapping for an external account discovered through an
        integration.
    StorefrontConnectionAccountCampaignRollup:
      type: object
      properties:
        campaignsTracked:
          type: integer
          minimum: 0
          maximum: 9007199254740991
          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 provider account.
        campaignsActive:
          description: >-
            Subset of campaignsTracked whose campaign status is currently
            ACTIVE.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        trackedSpend:
          type: number
          minimum: 0
          description: >-
            Delivered spend across tracked campaigns over the trailing window,
            in the account currency. Provider-reported net — directed buys
            dispatch the full media budget zero-fee, so net equals the buyer's
            budget.
        managedSpend:
          type: number
          minimum: 0
          description: >-
            Delivered spend across managed campaigns (authored through the
            platform) over the trailing window, in the account currency.
            Provider-reported net, same denomination as trackedSpend.
        managedShare:
          nullable: true
          description: >-
            The adoption metric for this relationship: managedSpend /
            (trackedSpend + managedSpend). Null when no spend was accounted in
            the window.
          type: number
          minimum: 0
          maximum: 1
        currency:
          type: string
          pattern: ^[A-Z]{3}$
          description: >-
            ISO 4217 currency all spend values in this rollup are denominated in
            — always the account currency. Rollups are never summed across
            currencies.
        windowDays:
          type: integer
          minimum: 0
          exclusiveMinimum: true
          maximum: 9007199254740991
          description: >-
            Trailing window, in days, the spend aggregates cover (currently
            365).
      required:
        - campaignsTracked
        - campaignsActive
        - trackedSpend
        - managedSpend
        - managedShare
        - currency
        - windowDays
      additionalProperties: false
      description: >-
        Directed-campaign rollup for one connected provider account: tracked =
        mirrored read-only from that account; managed = authored through the
        platform. Spend is provider-reported net in the account currency; sums
        cover delivery denominated in (or reported without) that currency.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````