Skip to main content
GET /api/v2/organization/advertisers Returns one advertiser roster across the Buyer Accounts authorized for the authenticated organization context, plus exact advertisers from accepted, unexpired organization grants. Use this endpoint when an organization needs a stable, account-spanning view; use List advertisers for the paginated Buyer Account list. The roster is a projection over existing advertiser records, durable lifecycle state, and authenticated relationships. It does not copy advertisers or campaigns, and matching names, domains, email domains, CRM records, signup paths, providers, or Partner status never merge records or grant access. Advertiser-scoped credentials cannot call this organization endpoint.

​
Request

curl

​
Response

The endpoint always emits owned relationships. operatingMode comes from explicit advertiser or admission state; it is never inferred from a name, domain, CRM record, signup path, provider, or operator. operatorRelationship is separate: an active confined seller-buyer sponsorship projects client, even if presentation changes to managed. The shared contract reserves delegated and counterparty relationships, and emits delegated entries only from an explicit authorized grant binding. Owned advertisers otherwise behave as before: a plain owned advertiser is managed by the organization, and an advertiser backed by the confined seller-buyer sponsorship is self_serve, with operatorRelationship: "client". An advertiser with an explicit self-service admission projects binding.provenance: "advertiser_admission", operatingMode: "self_serve", and operatorRelationship: "client", including while admission is pending. Its backing uses kind: "authorized_relationship" with the opaque admission reference and exact advertiser ID. It does not expose a Buyer Account to switch into. Client access in the advertiser’s settings shows this same state. For these entries, ready means admission is approved and claimed, and the membership and exact advertiser assignment are current. Pending admission is pending; suspension is suspended; rejected or revoked access is revoked. Inactive sellers, advertisers, or archived Storefronts cannot be ready. Missing, stale, expired, or mismatched grant evidence is incomplete. An agency’s grant for one advertiser cannot make another advertiser ready, including one created later. Admission-backed rows keep advertiser and Campaign management unavailable. For a directly authenticated organization administrator acting in the Seller Account, relationship management is available and the admission object returns the current state, claim state, revision, reviewed role and capabilities, currently effective role and capabilities, whether capability changes are available, and the lifecycle actions that are valid now. Other callers receive no available admission actions. For a targeted invitation, only that same direct Seller administrator sees selfServiceInvitation with the exact recipient and separate requested/sent/failed/cancelled delivery state. These fields never establish billing readiness, select who pays, grant payment authority, or authorize another or future advertiser. The response includes neither private conversations nor membership identity details.

​
Invite and manage client access

This endpoint only reads. Inviting a client, approving, suspending, reactivating or revoking a client, and changing a client’s role are done in Client access on the advertiser’s settings. An agent does not make these changes: save_advertiser_access is a page-only tool that the page uses, so it is not in an agent’s tool list. There are no REST routes for those changes. Read the same state with get and kind: "advertiser_access". The email an invited person receives carries a one-time link. The recipient opens the emailed fragment-bearing link, signs in as a directly authenticated WorkOS user with the exact invited email, and submits the one-time bearer to POST /api/v2/advertiser-invitations/claim. The browser removes the fragment before telemetry starts, and the email always links to the configured application origin rather than the Seller’s Discovery hostname. Claiming records the recipient through the canonical external self-service membership binding, which carries no Account role or baseline permissions. It does not approve admission, create a Buyer Account, choose a payer, or grant access to any advertiser. The Seller must still approve the pending admission from the advertiser’s Client access.

​
Delegated advertisers

An accepted, unexpired organization advertiser grant adds only its exact advertiser IDs as relationshipClass: "delegated". The entry’s delegation object names the opaque grant reference, owner organization, reviewed capabilities, and expiry. Its backing object uses kind: "authorized_relationship" and never returns the owner’s account ID. Revoked and expired entries disappear from the roster. Delegated entries are part of the limited beta for organization advertiser grants. They appear only while the Organization has an active beta entitlement and server-side beta exposure enabled by Apostra. Each delegated roster read rechecks an accepted, unexpired grant for the exact advertiser and advertiser.read capability. Disabling beta exposure or removing the entitlement hides delegated entries without deleting grant history. Counterparty AdCP relationship reconciliation is dark prerequisite infrastructure. No customer or internal account is enrolled by this slice, and the public API does not make counterparty entries available until later activation work separately enables both the fail-closed customer flag and runtime entitlement. Once that activation exists, only the complete authenticated tuple—BrandRef domain, optional brand ID, explicit country scope, operator domain, optional operator unit, fixed currency, and sandbox—can resolve one of those entries. The seller-local account_id and arrival path remain provenance only. Different operators, operator units, currencies, sandbox dispositions, or explicit operating modes stay distinct even when every other identity field is identical. Incomplete, conflicting, stale, or revoked counterparty evidence remains visible in unresolvedCounterpartyRelationships with operatorRelationship: "unresolved" and no advertiser or campaign management capability. Resolved entries always keep their existing non-null advertiserId contract. self_serve is stored only when an administrator explicitly chooses it; it is never inferred from the account’s arrival path or operator. Each entry also carries settings.available. It is true only for an advertiser your organization owns and Scope3 does not operate (House and Self-serve), and a client shows an advertiser-settings action only when it is true. Management capability is relative to the caller and backing account. It is available, account_switch_required, or unavailable. Readiness is ready, pending, suspended, revoked, disabled, or incomplete; incomplete and conflicting bindings remain visible but cannot be managed. Pending and suspended self-service entries backed by a legacy sponsorship are also read-only for advertiser and Campaign management until their sponsorship becomes active, while authorized administrators can still manage the relationship. Counterparty advertiser and Campaign management remains unavailable; a roster relationship never widens the buyer’s field-level grant. The legacy Storefront api_call wrapper may dispatch the read-only list_organization_advertisers operation as V2 persona plumbing. It is not the typed /mcp/v3 API, and while this capability is dark it cannot make counterparty entries appear without the same flag and entitlement gates. The response contains at most 500 resolved entries and at most 500 unresolved counterparty relationships. If data.page.truncated is true, at least one authorized roster collection has more rows than this response can return.

​
Use in Apostra

In Apostra, a seller’s Advertisers workspace in the left rail lists the same authorized roster without switching between account-scoped advertiser lists. Self-serve clients’ campaigns open from their row when the row permits Campaign management. Each row reflects relationship class, operator relationship, managed/self-serve mode, binding and readiness state, and the Campaigns action currently allowed for that relationship. Open an advertiser’s settings from the pencil beside it to see its status and Client access. There is no separate Advertisers page in Settings; an older /advertisers link opens the Advertisers workspace. system is true only when Apostra operates that advertiser through an active reviewer sandbox grant or active protected compliance-canary registration. A System advertiser is visible for context and its marker takes precedence over the other seller classes in the UI, which exposes no row mutation affordance. The roster capability fields state which API actions are currently available. The marker is provisioning provenance, not a display-name convention. Rows backed by delegated grants or counterparty relationships stay capability-limited. Apostra does not expose another organization’s accounts, members, billing, unrelated advertisers, future advertisers, or compatibility topology; grant changes use the APIs documented in Manage organization advertiser grants and recheck authority at execution. Apostra does not render or expose reusable signup links. Entitled direct Seller administrators can send the one-time, exact-recipient invitation described above only from an eligible Advertiser row. Lifecycle state is invited, provisioning, ready, failed, or revoked. A failed self-service lifecycle includes a stable recovery code for support and operator diagnostics, but this page does not document a customer retry flow. Each lifecycle carries a managementCapability field (available or unavailable) that reflects whether the authenticated organization context can act on that specific lifecycle. It is available when the caller is a human administrator and the organization has Distribution, which means it holds an active seller-distribution entitlement: a manual, plan or contract grant, or a beta grant that has not expired or been revoked. A Seller source profile does not grant Distribution on its own. Use this field - rather than the linked roster entry’s relationshipManagement - to gate revocation actions in Client access, including historical unclaimed self-serve lifecycles whose advertiserId is null (such lifecycles remain administratively revocable even after their join link is retired).

​
Errors

  • 401 UNAUTHORIZED — authentication is missing or invalid.
  • 403 ACCESS_DENIED — an advertiser-scoped credential requested the roster, or the authenticated Buyer Account could not be resolved.
See Errors for the full error contract.

List advertisers

Read the paginated Buyer Account list

Advertiser overview

Roster semantics, fields, and lifecycle

Manage organization advertiser grants

Invite, accept, reject, or revoke exact access