> ## 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.
# Search a source account roster
> Page or search the full observed-account roster for one inventory source, to pick a match for an approved buyer relationship
`GET /api/v2/storefront/account-mappings/sources/{inventorySourceId}/roster`
Returns the full observed-account roster for one active inventory source —
every native account Apostra has seen through that source's last-complete
listing, independent of any buyer relationship. It backs the inline account
picker in [Buyer Account Mapping](/v2/storefront/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
```bash curl theme={null}
curl "https://api.apostra.com/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`:
```json theme={null}
{
"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](/v2/reference/errors) for the full error contract.
## Related
All operations
Coverage states, suggested candidates, and how a decision is recorded
Shared error contract
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.