Search a source account roster

GET /api/v2/storefront/account-mappings/sources/{inventorySourceId}/roster Returns the full observed-account roster for one active inventory source — every native account Scope3 has seen through that source’s last-complete listing, independent of any buyer relationship. It backs the inline account picker in Buyer Account Mapping: once a relationship’s source coverage is Needs account selection (ambiguous) or Not set up (missing), search this roster to find the account to map. The suggested candidates shown alongside a relationship’s coverage — up to 5 accounts that share that relationship’s exact operator, brand, and sandbox — come from list_seller_account_relationships / GET /api/v2/storefront/account-mappings instead, as a candidates array on each source-coverage entry. This roster endpoint is the “see everything” search, not the suggestion list; a relationship’s true candidate count is always in candidateCount on that same entry, uncapped.

Request

curl "https://api.interchange.io/api/v2/storefront/account-mappings/sources/1284/roster?search=nike&limit=20" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Parameters

Field	Type	Required	Notes
`inventorySourceId`	string (path)	Yes	The inventory source’s internal id, from `sources[].inventorySourceId` on `GET /api/v2/storefront/account-mappings`.
`search`	string (query)	No	Case-insensitive substring match over the account’s display label, native account id, and observed operator/brand domain. Omit to page the full roster.
`offset`	integer (query)	No	Default `0`.
`limit`	integer (query)	No	Default `50`, max `100`.

Response

200 OK with a SellerAccountSourceRoster:

{
  "items": [
    {
      "sourceExternalAccountId": "44210",
      "displayLabel": "Ford US",
      "nativeStatus": "active",
      "generation": 3,
      "listingVersion": "gam-9",
      "observedOperatorDomain": "wpp.com",
      "observedBrandDomain": "ford.com",
      "observedSandbox": false,
      "lastSeenAt": "2026-08-23T00:00:00.000Z"
    },
    {
      "sourceExternalAccountId": "44398",
      "displayLabel": "Ford US",
      "nativeStatus": "active",
      "generation": 3,
      "listingVersion": "gam-9",
      "observedOperatorDomain": "wpp.com",
      "observedBrandDomain": "ford.com",
      "observedSandbox": false,
      "lastSeenAt": "2026-08-20T00:00:00.000Z"
    }
  ],
  "page": { "offset": 0, "limit": 20, "total": 2, "hasMore": false },
  "source": {
    "inventorySourceKey": "gam-primary",
    "name": "GAM — US",
    "reconciliation": {
      "state": "complete",
      "lastCompleteAt": "2026-08-24T06:00:00.000Z",
      "diagnosticCode": null,
      "diagnosticMessage": null
    }
  }
}

Two accounts can share the same displayLabel — this response never collapses them into one row. Always distinguish accounts by sourceExternalAccountId, the value a mapping decision actually binds.

Response fields

Field	Type	Notes
`items[].sourceExternalAccountId`	string	The source-native account id. Pass this as `sourceExternalAccountId` on `decide_seller_account_source_mapping` to bind it.
`items[].displayLabel`	string \| null	The account’s name as observed from the source; not unique.
`items[].nativeStatus`	string	Native account status as last observed (only `active` accounts are returned).
`items[].generation`	integer	The listing attempt that last observed this account.
`items[].listingVersion`	string \| null	Source-reported listing/catalog version at that generation, if the source provides one.
`items[].observedOperatorDomain`	string \| null	Operator domain the source reported for this account, if any.
`items[].observedBrandDomain`	string \| null	Brand domain the source reported for this account, if any.
`items[].observedSandbox`	boolean	Whether the source reported this as a sandbox/test account.
`items[].lastSeenAt`	string \| null	ISO-8601 timestamp of the account’s last-observed listing.
`page.total`	integer	The full match count for the given `search`, independent of `offset`/`limit` — always accurate, including on a page past the last row.
`page.hasMore`	boolean	Whether more matching rows exist beyond this page.
`source.inventorySourceKey`	string	The source’s stable key (used in mapping decisions and exports).
`source.name`	string	The source’s display name.
`source.reconciliation.state`	enum	`never`, `running`, `complete`, `incomplete`, or `failed` — the source’s last listing-refresh outcome.
`source.reconciliation.lastCompleteAt`	string \| null	ISO-8601 timestamp of the last complete listing — the roster’s effective age.
`source.reconciliation.diagnosticCode` \| `diagnosticMessage`	string \| null	Present when the last refresh attempt reported a problem.

Errors

401 UNAUTHORIZED — missing or invalid API key.
403 CUSTOMER_ROLE_DENIED — the API key is not a seller account.
404 NOT_FOUND — no active inventory source with this id under your storefront.

See Errors for the full error contract.

Buyer account mapping tasks

All operations

Buyer Account Mapping

Coverage states, suggested candidates, and how a decision is recorded

Errors

Shared error contract

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Search a source account roster

Request

Parameters

Response

Response fields

Errors

Buyer account mapping tasks

Buyer Account Mapping

Errors

​Request

​Parameters

​Response

​Response fields

​Errors

​Related

Buyer account mapping tasks

Buyer Account Mapping

Errors

Request

Parameters

Response

Response fields

Errors

Related