> ## 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 organization advertisers > Read and manage owned advertiser lifecycles plus explicitly delegated advertisers `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](/v2/buyer/advertisers/tasks/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 ```bash curl theme={null} curl "https://api.apostra.com/api/v2/organization/advertisers" \ -H "Authorization: Bearer $SCOPE3_API_KEY" ``` ## Response ```json theme={null} { "data": { "entries": [ { "rosterEntryId": "owned:advertiser:12345", "advertiserId": "12345", "displayName": "Acme Corp", "relationshipClass": "owned", "operatorRelationship": "organization", "operatingMode": "managed", "sandbox": false, "system": false, "binding": { "provenance": "compatibility_account", "state": "resolved", "reason": null }, "backing": { "kind": "compatibility_account", "accountId": 101, "advertiserId": "12345" }, "delegation": null, "capabilities": { "read": true, "advertiserManagement": "available", "campaignManagement": "available", "relationshipManagement": "available" }, "readiness": { "state": "ready" } } ], "unresolvedCounterpartyRelationships": [], "lifecycles": [ { "lifecycleId": "901", "displayName": "Acme Corp", "provisioningMode": "managed", "state": "ready", "advertiserId": "12345", "targetAccountId": 101, "managementCapability": "available", "joinLink": null, "failure": null, "createdAt": "2026-08-27T05:30:00.000Z", "updatedAt": "2026-08-27T05:30:00.000Z" } ], "page": { "limit": 500, "truncated": false }, "deliveredRelationshipClasses": ["owned"] }, "error": null } ``` 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. The seller's Advertisers page 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. ## Send an exact-recipient invitation When an eligible managed Advertiser row returns `selfServiceInvitation.actionAvailable: true`, a directly authenticated Seller administrator can send one invitation from that exact row. The request uses the row's opaque `eligibilityRevision`; it does not accept advertiser identity, billing, payer, account membership, or a reusable URL: ```json theme={null} { "recipientEmail": "operator@example.com", "operatorDomain": "agency.example", "requestedRoleSlug": "advertiser-viewer", "expectedEligibilityRevision": "4f9e8f0d9a41c7f4b36b8b7cf53b44e31810eae558a9f4b426f29b0bb6c140fa", "idempotencyKey": "22222222-2222-4222-8222-222222222222" } ``` Send it to `POST /api/v2/organization/advertisers/{advertiserId}/self-service-invitations`. The service rechecks the exact Advertiser, its canonical settings, the active published Seller Storefront, the direct Seller administrator, and the entitlement while creating the existing advertiser-admission lifecycle. A stale row, changed Storefront or settings, cross-advertiser reference, or changed idempotency replay fails closed. The response reports the recipient and delivery state but never the one-time claim bearer. `sent` means the email provider accepted the message; it does not assert inbox delivery. `failed` means the durable invitation exists but the email request failed. While that exact invitation remains unclaimed, pending, and unexpired, the same Advertiser row offers the send action again. A retry is revision-bound and can resend only the same recipient, operator, role, and one-time claim; it cannot create another admission or broaden authority. Claim and admission remain separate states on the same roster row. 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 exact Advertiser row. ## Manage an exact advertiser admission A directly authenticated organization administrator acting in the Seller Account can decide only the exact admission shown on the roster row. Use the Advertisers page while signed in with the administrator's browser session. API keys and service tokens are rejected because they do not prove the current human administrator seat. The page submits the exact row's current values: ```json theme={null} { "action": "suspend", "expectedRevision": "7", "reason": "Access paused after seller review.", "idempotencyKey": "22222222-2222-4222-8222-222222222222" } ``` Use only an action returned in `admission.availableActions`: `approve` for a claimed pending admission, `suspend` for an approved admission, `reactivate` for a suspended admission, and `revoke` for an approved, suspended, or rejected admission. The service rechecks the seller, advertiser, admission, current administrator seat, state, claim, grant, and revision. A stale revision, cross-advertiser reference, reused idempotency key with different input, or invalid transition fails without changing authority. Refetch the roster after a successful decision for the canonical relationship state. Approve and reactivate grant only the explicit role and capabilities already reviewed on the admission. This endpoint does not edit capabilities. Suspend and revoke immediately fence the exact grant and assignment; they do not erase advertiser, Campaign, audit, or billing history. Targeted invitation delivery and capability changes are separate flows. ## Change reviewed advertiser access A directly authenticated organization administrator acting in the Seller Account can replace the supported role for one exact approved, claimed admission. Use the Advertisers page to compare the currently reviewed access, the currently effective assignment, and the proposed access before saving. The page offers only these complete bundles: * Viewer: `read` * Editor: `read`, `write` * Administrator: `admin`, `read`, `write` The page sends the exact advertiser and admission references from the roster row to `PUT /api/v2/organization/advertisers/{advertiserId}/admissions/{admissionId}/capabilities`: ```json theme={null} { "expectedRevision": "7", "expectedRoleSlug": "advertiser-editor", "requestedRoleSlug": "advertiser-admin", "requestedCapabilities": ["admin", "read", "write"], "reason": "Seller reviewed administrator access.", "idempotencyKey": "22222222-2222-4222-8222-222222222222" } ``` The service confirms that the signed-in person is a direct organization administrator in the Seller Account and that the self-service advertiser relationship feature is active. It also checks the exact advertiser, admission, member, current role, and current revision. It rejects inherited organization access, API, service, or agent credentials, removed members, stale input, changed replays, and suspended, revoked, rejected, or pending admissions. A successful change removes the old effective access before adding the replacement role. Refetch the roster to read the current requested and effective state. Billing, payment, payer, card, invoice, and Campaign execution capabilities are not role options and cannot be added to the request. Changing advertiser access does not select billing posture, add Organization membership, or grant access to another advertiser. An accepted, unexpired [organization advertiser grant](/v2/buyer/advertisers/tasks/manage-organization-advertiser-grants) 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 or repair 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. 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, it does not expose repair, and while this capability is dark it cannot make counterparty entries appear without the same flag and entitlement gates. ## Repair an incoming relationship After the later activation package authorizes counterparty reconciliation, an entitled, directly authenticated Seller-admin can append an identity repair revision through direct REST with `PUT /api/v2/organization/advertisers/{relationshipRef}/reconciliation`. The repair operation is not exposed through MCP or the legacy Storefront `api_call` wrapper. The `relationshipRef` comes from `unresolvedCounterpartyRelationships[].backing.relationshipRef`. ```json theme={null} { "advertiserId": "12345", "identity": { "brand": { "domain": "acme.example", "id": null, "countries": ["GB", "US"] }, "operator": { "domain": "agency.example", "unitId": "uk-buying" }, "fixedCurrency": "GBP", "sandbox": false }, "operatingMode": "managed" } ``` Countries must be unique and sorted. Repair succeeds only when the current active grant, buyer operator identity, advertiser BrandRef, fixed currency, and sandbox disposition all match exactly. It appends a revision without changing advertiser-owned fields. The active runtime entitlement is locked and rechecked in the same transaction as the binding write, so a concurrent revocation serializes before or after repair instead of interleaving with it. Changed, revoked, ambiguous, or cross-tenant evidence returns an error and leaves the prior rows intact. 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 Organization members can open the Advertisers page in Apostra to review the same authorized roster without switching between account-scoped advertiser lists. Self-serve clients' campaigns open from their Advertisers tab row when the row permits Campaign management. Each row shows relationship class, operator relationship, managed/self-serve mode, binding and readiness state, safe provenance, grant state when present, lifecycle status, and the Campaigns action currently allowed for that relationship. `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. The page does not expose another organization's accounts, members, billing, unrelated advertisers, future advertisers, or compatibility topology; lifecycle changes, grant state, and counterparty reconciliation still use the same APIs documented here 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 documented 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 with either an active organization-advertiser-lifecycle entitlement or an active, unexpired beta feature profile that includes that capability. Use this field - rather than the linked roster entry's `relationshipManagement` - to gate revocation actions, including historical unclaimed self-serve lifecycles whose `advertiserId` is null (such lifecycles remain administratively revocable even after their join link is retired). ## Change presentation `PATCH /api/v2/organization/advertisers/{advertiserId}/operating-mode` changes only the explicit `operatingMode`. It never reparents a backing Buyer Account, creates a sponsorship, or grants cross-organization access. A `self_serve` advertiser without an explicit admission or valid legacy sponsorship remains incomplete and unavailable. Admission-backed entries do not support this compatibility presentation action. ```json theme={null} { "operatingMode": "self_serve" } ``` ## Revoke self-serve access `POST /api/v2/organization/advertisers/lifecycles/{lifecycleId}/revoke` terminally revokes the invitation and suspends the confined sponsorship. The advertiser, Campaigns, and billing history remain stored. ```json theme={null} { "reason": "Client relationship ended" } ``` ## Errors * `401 UNAUTHORIZED` — authentication is missing or invalid. * `403 ACCESS_DENIED` — an advertiser-scoped credential requested the roster, the authenticated Buyer Account could not be resolved, a mode or revoke mutation lacks administrator authority, a mode or revoke mutation lacks an active organization-advertiser-lifecycle entitlement or beta profile (the `relationshipManagement` capability is `unavailable` or has expired), or a repair caller lacks Media Company type, dark-gate access, entitlement, direct-human Seller-admin authority, or exact-resource authority. * `409 CONFLICT` — lifecycle capacity is exhausted, lifecycle access is already revoked, or repair evidence is incomplete, stale, revoked, ambiguous, or does not match the complete tuple. See [Errors](/v2/reference/errors) for the full error contract. ## Related Read the paginated Buyer Account list Roster semantics, fields, and lifecycle Invite, accept, reject, or revoke exact access This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.