> ## 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 buyer account relationships

> List the seller-owned operator-and-brand relationships and their private coverage across active inventory sources.



## OpenAPI

````yaml /v2/storefront-api-v2.yaml get /account-mappings
openapi: 3.0.0
info:
  title: Scope3 Storefront API
  version: 2.0.0
  description: >-
    REST API for partners to manage Seller Accounts, inventory sources, and
    billing.


    ## Authentication


    All endpoints require a Bearer token in the Authorization header:

    ```

    Authorization: Bearer your-api-key

    ```


    ## Base URL


    `https://api.apostra.com/api/v2/storefront`


    ## For AI Agents


    AI agents can use the MCP endpoint at `/mcp/v2/storefront` 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.apostra.com/api/v2/storefront
    description: Production server
security: []
tags:
  - 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: Storefront
    description: Manage storefront and inventory sources
  - name: Storefront Agents
    description: List and manage registered sales, signals, and outcomes agents
  - name: Storefront Activity
    description: Audit log of configuration and inventory changes on the storefront
  - name: Storefront Billing
    description: Payout bank details and billing configuration for Seller Accounts
  - name: AI Usage
    description: Seller Account AI token usage visibility by model
  - name: MCP
    description: Model Context Protocol endpoints
paths:
  /account-mappings:
    get:
      tags:
        - Storefront
      summary: List buyer account relationships
      description: >-
        List the seller-owned operator-and-brand relationships and their private
        coverage across active inventory sources.
      operationId: listSellerAccountRelationships
      parameters:
        - in: query
          name: offset
          schema:
            default: 0
            type: integer
            minimum: 0
            maximum: 9007199254740991
        - in: query
          name: limit
          schema:
            default: 50
            type: integer
            minimum: 1
            maximum: 100
        - in: query
          name: search
          schema:
            type: string
            maxLength: 200
        - in: query
          name: relationshipId
          schema:
            type: string
            minLength: 1
            maxLength: 255
        - in: query
          name: relationshipBackedOnly
          schema:
            description: >-
              Return only complete seller accounts that also carry a verified
              legacy relationship navigation id. Navigation never authorizes
              approval or binding.
            type: boolean
          description: >-
            Return only complete seller accounts that also carry a verified
            legacy relationship navigation id. Navigation never authorizes
            approval or binding.
      responses:
        '200':
          description: List buyer account relationships
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SellerAccountMappingList'
        '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:
    SellerAccountMappingList:
      anyOf:
        - type: object
          properties:
            sources:
              type: array
              items:
                $ref: '#/components/schemas/SellerAccountMappingSource'
            page:
              type: object
              properties:
                offset:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                limit:
                  type: integer
                  minimum: 1
                  maximum: 100
                total:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                hasMore:
                  type: boolean
              required:
                - offset
                - limit
                - total
                - hasMore
              additionalProperties: false
            dsEnabled:
              default: true
              description: >-
                Deprecated: always true. The design-system view is now the only
                view (the ds-widgets flag was retired). Retained as a required
                response field so released clients and cached widget bundles
                that read it keep deserializing; removed in a future major
                version.
              type: boolean
            identityMode:
              type: string
              enum:
                - complete_key
            items:
              type: array
              items:
                $ref: '#/components/schemas/CompleteKeySellerAccountMappingItem'
            totals:
              $ref: '#/components/schemas/SellerAccountMappingTotals'
          required:
            - sources
            - page
            - dsEnabled
            - identityMode
            - items
            - totals
          additionalProperties: false
        - type: object
          properties:
            sources:
              type: array
              items:
                $ref: '#/components/schemas/SellerAccountMappingSource'
            page:
              type: object
              properties:
                offset:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                limit:
                  type: integer
                  minimum: 1
                  maximum: 100
                total:
                  type: integer
                  minimum: 0
                  maximum: 9007199254740991
                hasMore:
                  type: boolean
              required:
                - offset
                - limit
                - total
                - hasMore
              additionalProperties: false
            dsEnabled:
              default: true
              description: >-
                Deprecated: always true. The design-system view is now the only
                view (the ds-widgets flag was retired). Retained as a required
                response field so released clients and cached widget bundles
                that read it keep deserializing; removed in a future major
                version.
              type: boolean
            items:
              type: array
              items:
                $ref: '#/components/schemas/LegacySellerAccountMappingItem'
            totals:
              $ref: '#/components/schemas/LegacySellerMappingTotals'
          required:
            - sources
            - page
            - dsEnabled
            - items
            - totals
          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
    SellerAccountMappingSource:
      type: object
      properties:
        inventorySourceId:
          type: string
        inventorySourceKey:
          type: string
        name:
          type: string
        executionType:
          type: string
        supportsNativeAccounts:
          type: boolean
        lifecycleAuthority:
          type: string
          enum:
            - seller
            - upstream_agent
        controls:
          type: object
          properties:
            observe:
              type: boolean
            map:
              type: boolean
            approve:
              type: boolean
            create:
              type: boolean
          required:
            - observe
            - map
            - approve
            - create
          additionalProperties: false
        reconciliation:
          type: object
          properties:
            state:
              type: string
              enum:
                - never
                - running
                - complete
                - incomplete
                - failed
            attemptGeneration:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            lastAttemptAt:
              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))$
            lastCompleteAt:
              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))$
            observedCount:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            archivedCount:
              type: integer
              minimum: 0
              maximum: 9007199254740991
            diagnosticCode:
              nullable: true
              type: string
            diagnosticMessage:
              nullable: true
              type: string
          required:
            - state
            - attemptGeneration
            - lastAttemptAt
            - lastCompleteAt
            - observedCount
            - archivedCount
            - diagnosticCode
            - diagnosticMessage
          additionalProperties: false
      required:
        - inventorySourceId
        - inventorySourceKey
        - name
        - executionType
        - supportsNativeAccounts
        - lifecycleAuthority
        - controls
        - reconciliation
      additionalProperties: false
    CompleteKeySellerAccountMappingItem:
      type: object
      properties:
        accountId:
          type: string
        accountKey:
          $ref: '#/components/schemas/SellerAccountKey'
        verifiedBuyerOwner:
          type: object
          properties:
            buyerCustomerId:
              type: string
            organizationName:
              type: string
            lifecycleGeneration:
              type: string
            workosOrganizationId:
              type: string
          required:
            - buyerCustomerId
            - organizationName
            - lifecycleGeneration
            - workosOrganizationId
          additionalProperties: false
        sellerDecision:
          nullable: true
          type: object
          properties:
            status:
              type: string
              enum:
                - active
                - rejected
                - suspended
                - closed
            disposition:
              type: string
              enum:
                - link_existing
                - route_to_interchange
                - reject
            billing:
              nullable: true
              type: string
              enum:
                - operator
                - agent
                - advertiser
            version:
              type: integer
              minimum: 0
              exclusiveMinimum: true
              maximum: 9007199254740991
          required:
            - status
            - disposition
            - billing
            - version
          additionalProperties: false
        sellerAccountId:
          type: string
        relationshipId:
          nullable: true
          type: string
        operatorDomain:
          type: string
        brandDomain:
          type: string
        displayName:
          type: string
        sandbox:
          type: boolean
        billingGate:
          $ref: '#/components/schemas/ReadyToInvoiceGate'
        grants:
          type: array
          items:
            type: object
            properties:
              status:
                type: string
              billing:
                nullable: true
                type: string
              count:
                type: integer
                minimum: 0
                maximum: 9007199254740991
            required:
              - status
              - billing
              - count
            additionalProperties: false
        pendingIntakeCount:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        pendingReviewCount:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        pendingExternalCount:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        pendingRequests:
          type: array
          items:
            type: object
            properties:
              requestId:
                type: string
              authority:
                type: string
                enum:
                  - seller
                  - external_agent
                  - account_input
              authorityRef:
                nullable: true
                type: string
              requestedBilling:
                type: string
                enum:
                  - operator
                  - agent
                  - advertiser
              requestedPaymentTerms:
                nullable: true
                description: >-
                  Payment terms the buyer asked for. Accepting the request
                  accepts these terms; null means the request named none.
                type: string
                enum:
                  - net_15
                  - net_30
                  - net_45
                  - net_60
                  - net_90
                  - prepay
              billingReady:
                type: boolean
              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))$
              allowedActions:
                type: object
                properties:
                  accept:
                    type: boolean
                  linkExisting:
                    type: boolean
                  reject:
                    type: boolean
                required:
                  - accept
                  - linkExisting
                  - reject
                additionalProperties: false
            required:
              - requestId
              - authority
              - authorityRef
              - requestedBilling
              - requestedPaymentTerms
              - billingReady
              - createdAt
              - updatedAt
              - allowedActions
            additionalProperties: false
        sourceCoverage:
          type: array
          items:
            $ref: '#/components/schemas/SellerAccountMappingCoverage'
        openProposalCount:
          nullable: true
          description: >-
            Currently null for complete AccountKey mappings. Proposal counts
            remain unavailable here until proposals can be attributed through an
            exact account route; use Demand Inbox for current proposal activity.
            The API never falls back to an operator-and-brand relationship join.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        mtdSpend:
          $ref: '#/components/schemas/SellerAccountMoneyAmount'
          description: >-
            Currently null for complete AccountKey mappings. Spend remains
            unavailable here until delivery can be attributed through an exact
            account route; use Reporting for current commercial activity. The
            API never falls back to an operator-and-brand relationship join.
      required:
        - accountId
        - accountKey
        - verifiedBuyerOwner
        - sellerDecision
        - sellerAccountId
        - relationshipId
        - operatorDomain
        - brandDomain
        - displayName
        - sandbox
        - billingGate
        - grants
        - pendingIntakeCount
        - pendingReviewCount
        - pendingExternalCount
        - pendingRequests
        - sourceCoverage
        - openProposalCount
        - mtdSpend
      additionalProperties: false
    SellerAccountMappingTotals:
      type: object
      properties:
        buyersCount:
          nullable: true
          description: >-
            Storefront-wide count of distinct verified buyer organisations
            represented by currently eligible exact seller accounts. Search,
            relationship filters, pagination, and decision status do not change
            this ownership total, so rejected accounts remain included. Null
            when currently unavailable.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        openProposals:
          nullable: true
          description: >-
            Currently null because proposal activity is not attributed from
            complete AccountKeys to exact account routes in this endpoint. Use
            Demand Inbox for the storefront proposal total; the API never sums
            legacy operator-and-brand relationship values.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        activeThisMonth:
          $ref: '#/components/schemas/SellerAccountMoneyAmount'
          description: >-
            Currently null because delivered spend is not attributed from
            complete AccountKeys to exact account routes in this endpoint. Use
            Reporting for storefront spend; the API never sums legacy
            operator-and-brand relationship values.
      required:
        - buyersCount
        - openProposals
        - activeThisMonth
      additionalProperties: false
    LegacySellerAccountMappingItem:
      type: object
      properties:
        accountId:
          type: string
        relationshipId:
          type: string
        operatorDomain:
          type: string
        brandDomain:
          type: string
        displayName:
          type: string
        sandbox:
          type: boolean
        billingGate:
          $ref: '#/components/schemas/ReadyToInvoiceGate'
        grants:
          type: array
          items:
            type: object
            properties:
              status:
                type: string
              billing:
                nullable: true
                type: string
              count:
                type: integer
                minimum: 0
                maximum: 9007199254740991
            required:
              - status
              - billing
              - count
            additionalProperties: false
        pendingIntakeCount:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        pendingReviewCount:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        pendingExternalCount:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        pendingRequests:
          type: array
          items:
            type: object
            properties:
              requestId:
                type: string
              authority:
                type: string
                enum:
                  - seller
                  - external_agent
                  - account_input
              authorityRef:
                nullable: true
                type: string
              requestedBilling:
                type: string
                enum:
                  - operator
                  - agent
                  - advertiser
              requestedPaymentTerms:
                nullable: true
                description: >-
                  Payment terms the buyer asked for. Accepting the request
                  accepts these terms; null means the request named none.
                type: string
                enum:
                  - net_15
                  - net_30
                  - net_45
                  - net_60
                  - net_90
                  - prepay
              billingReady:
                type: boolean
              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))$
              allowedActions:
                type: object
                properties:
                  accept:
                    type: boolean
                  linkExisting:
                    type: boolean
                  reject:
                    type: boolean
                required:
                  - accept
                  - linkExisting
                  - reject
                additionalProperties: false
            required:
              - requestId
              - authority
              - authorityRef
              - requestedBilling
              - requestedPaymentTerms
              - billingReady
              - createdAt
              - updatedAt
              - allowedActions
            additionalProperties: false
        sourceCoverage:
          type: array
          items:
            $ref: '#/components/schemas/SellerAccountMappingCoverage'
        openProposalCount:
          nullable: true
          type: integer
          minimum: 0
          maximum: 9007199254740991
        mtdSpend:
          $ref: '#/components/schemas/SellerAccountMoneyAmount'
      required:
        - accountId
        - relationshipId
        - operatorDomain
        - brandDomain
        - displayName
        - sandbox
        - billingGate
        - grants
        - pendingIntakeCount
        - pendingReviewCount
        - pendingExternalCount
        - pendingRequests
        - sourceCoverage
        - openProposalCount
        - mtdSpend
      additionalProperties: false
      description: >-
        Released relationship-based mapping row returned while the complete
        AccountKey cutover is disabled. It is legacy navigation and mapping
        state, never complete-key approval authority.
    LegacySellerMappingTotals:
      type: object
      properties:
        buyersCount:
          nullable: true
          description: >-
            Count of distinct operator domains across non-rejected
            relationship-based mappings. Null when the legacy money view is
            unavailable.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        openProposals:
          nullable: true
          description: >-
            Sum of open proposals attributed through the released
            operator-and-brand relationship view. Null when the legacy money
            view is unavailable.
          type: integer
          minimum: 0
          maximum: 9007199254740991
        activeThisMonth:
          $ref: '#/components/schemas/SellerAccountMoneyAmount'
          description: >-
            Month-to-date spend attributed through the released
            operator-and-brand relationship view. Null when unavailable,
            unattributed, or denominated in multiple currencies.
      required:
        - buyersCount
        - openProposals
        - activeThisMonth
      additionalProperties: false
    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
    SellerAccountKey:
      type: object
      properties:
        version:
          type: number
          enum:
            - 1
        brand:
          type: object
          properties:
            domain:
              type: string
            brandId:
              nullable: true
              type: string
            countries:
              nullable: true
              minItems: 1
              type: array
              items:
                type: string
          required:
            - domain
            - brandId
            - countries
          additionalProperties: false
        operatorDomain:
          type: string
        operatorUnitId:
          nullable: true
          type: string
        currency:
          nullable: true
          type: string
        timezone:
          nullable: true
          type: string
        sandbox:
          type: boolean
      required:
        - version
        - brand
        - operatorDomain
        - operatorUnitId
        - currency
        - timezone
        - sandbox
      additionalProperties: false
      description: >-
        The complete immutable AdCP AccountKey. Every field participates in
        seller account identity; null means the optional field is absent, not a
        wildcard.
    ReadyToInvoiceGate:
      type: object
      properties:
        required:
          type: boolean
        status:
          type: string
          enum:
            - not_required
            - pending
            - ready
            - revoked
        assertionId:
          nullable: true
          type: string
        billingEntity:
          nullable: true
          allOf:
            - $ref: '#/components/schemas/ReadyToInvoiceGateBillingEntity'
      required:
        - required
        - status
        - assertionId
        - billingEntity
      additionalProperties: false
    SellerAccountMappingCoverage:
      type: object
      properties:
        inventorySourceKey:
          type: string
        coverage:
          type: string
          enum:
            - bound
            - not_required
            - missing
            - ambiguous
            - stale
        sourceExternalAccountId:
          nullable: true
          type: string
        bindingVersion:
          nullable: true
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        nativeAccountGeneration:
          nullable: true
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
        nativeAccountStatus:
          nullable: true
          type: string
        listingVersion:
          nullable: true
          type: string
        lastSeenAt:
          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))$
        candidateCount:
          type: integer
          minimum: 0
          maximum: 9007199254740991
        candidates:
          maxItems: 5
          type: array
          items:
            $ref: '#/components/schemas/SellerAccountMappingCandidate'
      required:
        - inventorySourceKey
        - coverage
        - sourceExternalAccountId
        - bindingVersion
        - nativeAccountGeneration
        - nativeAccountStatus
        - listingVersion
        - lastSeenAt
        - candidateCount
        - candidates
      additionalProperties: false
    SellerAccountMoneyAmount:
      nullable: true
      type: object
      properties:
        amount:
          type: number
        currency:
          type: string
      required:
        - amount
        - currency
      additionalProperties: false
    ReadyToInvoiceGateBillingEntity:
      type: object
      properties:
        legalName:
          type: string
        vatId:
          nullable: true
          type: string
        taxId:
          nullable: true
          type: string
        registrationNumber:
          nullable: true
          type: string
      required:
        - legalName
        - vatId
        - taxId
        - registrationNumber
      additionalProperties: false
    SellerAccountMappingCandidate:
      type: object
      properties:
        sourceExternalAccountId:
          type: string
        displayLabel:
          nullable: true
          type: string
        lastSeenAt:
          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))$
        reason:
          type: string
          enum:
            - operator_brand_sandbox_match
      required:
        - sourceExternalAccountId
        - displayLabel
        - lastSeenAt
        - reason
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key or access token

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.