List advertisers

Deprecated. This page documents the v2 buyer API, which is closed to new API clients and switches off on 1 December 2026. Use V3 instead: see Move a v2 buyer REST integration to V3. The conversion endpoint, Log event, stays open.

GET /api/v2/buyer/advertisers Returns a paginated list of advertiser summary rows. Each row is the compact shape — call Get advertiser for the full resource with brand, linked accounts, UTM config, and frequency caps. This endpoint normally requires a Buyer Account. A Seller Account in the Media Company V3 preview may use this list endpoint to populate its native Campaigns workspace. For that Seller-only compatibility read, an omitted sandbox parameter or sandbox=true returns only sandbox Advertisers with an active organization-owned binding to that Seller Account’s Storefront — available to every Seller Account on every plan. sandbox=false returns the same Seller Account’s live own-supply Advertisers instead, and requires live managed campaigns, which come with Merchandising; a Seller Account without them gets 403 OWN_SUPPLY_SCOPE_REQUIRED for that request. Unbound Advertisers in either environment are not part of this roster. The Campaigns workspace also uses two narrowly scoped compatibility reads: List campaigns for a bound Advertiser and that Advertiser’s promoted Creative list. Advertiser detail, Campaign and Creative detail, mutations, and reporting remain unavailable through Buyer REST to the Seller Account.

Request

curl

curl "https://api.apostra.com/api/v2/buyer/advertisers?search=acme&limit=50" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Parameters

Field	Type	Required	Notes
`status`	enum	No	`ACTIVE`, `ARCHIVED`, or `ALL`. Defaults to `ACTIVE`
`name`	string	No	Case-insensitive partial match on advertiser name
`search`	string	No	Case-insensitive partial match on advertiser name or ID. Exact ID matches appear first
`sandbox`	boolean	No	`true` returns only sandbox advertisers, `false` only production. Omit for all
`linkedAccountPartnerId`	string	No	Exact partner / sales-agent ID. Returns only advertisers with a currently linked account for that partner
`limit`	integer	No	Max rows per page. Default `100`, max `100`
`offset`	integer	No	Rows to skip for pagination. Default `0`

search is applied to the full authorized roster before limit and offset, so matching advertisers remain discoverable beyond the first page. Use name when only advertiser names should match.

Response

{
  "items": [
    {
      "id": "12345",
      "name": "Acme Corp",
      "status": "ACTIVE",
      "sandbox": false,
      "brand": "acme.com",
      "brandCountries": ["DE", "NL"],
      "brandCountriesKnown": true,
      "primaryCurrency": "USD",
      "preferredTimezone": "Europe/Amsterdam",
      "reportingTimezoneLocked": false,
      "channels": ["display", "ctv"],
      "channelsKnown": true,
      "currencyLocked": false,
      "linkedAccountCount": 3,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-20T14:45:00Z"
    }
  ],
  "total": 42,
  "hasMore": false,
  "nextOffset": null
}

Summary rows also carry brandCountries, brandCountriesKnown, primaryCurrency, preferredTimezone, reportingTimezoneLocked, channels, channelsKnown, and currencyLocked, so account setup can render without fetching every full advertiser. When channelsKnown is true, an empty channels list is the All channels answer; when it is false, the advertiser has not chosen its channels yet. When brandCountriesKnown is true, an empty brandCountries list means the country scope does not block automatic matching in any seller country. When it is false, the empty list is an unknown legacy scope that must be classified before seller activation. Country scope and channel overlap influence automatic qualification, but they do not create advertiser-owned seller selection edges; selection remains account-wide. linkedAccountCount replaces the embedded account list. When hasMore is true, pass nextOffset as the next offset.

Errors

400 VALIDATION_ERROR — invalid status value or out-of-range limit.
403 CUSTOMER_ROLE_DENIED — the account is neither a Buyer Account nor a Seller Account using this advertiser roster.
403 OWN_SUPPLY_SCOPE_REQUIRED — the Seller Account has no active Storefront scope for the requested environment’s roster, or requested sandbox=false without live managed campaigns (Merchandising).

The Seller sandbox roster is available by account role; it does not require a separate entitlement. The Seller live roster additionally requires live managed campaigns, which come with Merchandising. All mutations remain outside this compatibility read. See Errors for the full error contract.

Advertiser tasks

All advertiser operations

Advertiser overview

Fields, lifecycle, and concepts

List organization advertisers

Read the authorized account-spanning roster

Get advertiser

Fetch the full resource

Create advertiser

Open a new advertiser

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

List advertisers

Request

Parameters

Response

Errors

Advertiser tasks

Advertiser overview

List organization advertisers

Get advertiser

Create advertiser

​Request

​Parameters

​Response

​Errors

​Related

Advertiser tasks

Advertiser overview

List organization advertisers

Get advertiser

Create advertiser

Request

Parameters

Response

Errors

Related