Advertiser - Interchange API

Overview

An Advertiser is the top-level account in the Scope3 v2 API. Every campaign, creative, audience, frequency cap, and linked partner account belongs to an advertiser. Think of it as the buyer’s brand container that anchors all programmatic activity for a single product line, brand, or business unit.

Renamed from Brand Agent: In v1 this concept was called a “Brand Agent”. In v2 it has been renamed to Advertiser to align with industry terminology used by Google Ads, The Trade Desk, DV360, and Amazon DSP.

Why advertisers matter

Resource ownership — campaigns, creatives, audiences, and frequency caps all roll up to a single advertiser
Brand identity — every advertiser links to a brand resolved from the AdCP brand registry (or a /.well-known/brand.json manifest on the brand’s domain)
Default policies — optimizationApplyMode, campaignBudgetType, UTM parameters, and frequency caps set on the advertiser flow down to its campaigns
Sandbox isolation — sandbox advertisers route every ADCP call to test accounts, so you can rehearse end-to-end flows without real spend
Linked accounts — connect the advertiser to existing accounts on upstream platforms (e.g. Snap, programmatic DSPs) for cross-platform reporting and execution

Key fields

The advertiser resource has two response shapes:

Summary — returned by GET /api/v2/buyer/advertisers (list). A small, fixed set of row-level fields.
Full — returned by GET /api/v2/buyer/advertisers/:id (get). The complete resource with nested brand, linked accounts, UTM config, and frequency caps.

Summary shape (list rows)

Field	Type	Notes
`id`	string	Stable advertiser identifier
`name`	string	Human-readable name (max 255 chars)
`status`	`ACTIVE` \| `ARCHIVED`	Soft-delete state
`sandbox`	boolean	When true, all ADCP calls route to sandbox accounts. Immutable after creation.
`brand`	string	Brand domain (e.g. `northwind.example`) or brand website URL
`linkedAccountCount`	integer	Number of partner accounts linked to this advertiser. Use `get_advertiser` for the full list.
`createdAt` / `updatedAt`	datetime	ISO 8601 timestamps

Full shape (single advertiser)

The single-advertiser endpoint returns every field above plus:

Field	Type	Notes
`description`	string	Optional description (max 1000 chars)
`linkedBrand`	object	Resolved brand identity — name, domain, logos, colors, fonts, manifest
`optimizationApplyMode`	`AUTO` \| `MANUAL`	Default for child campaigns. `MANUAL` requires approval before applying optimizations.
`primaryCurrency`	string	ISO 4217 code. The single currency for every campaign under this advertiser. Changeable until the first campaign exists, then locked.
`currencyLocked`	boolean	`true` once the advertiser has at least one campaign; while `false`, `primaryCurrency` can still be changed.
`campaignBudgetType`	`total_budget`	Whether campaign budgets cover media + fees (today only `total_budget` is supported)
`linkedAccounts`	array	Partner accounts linked to this advertiser (e.g. Snap account, agency seats)
`utmConfig`	array	Default UTM parameters appended to landing page URLs
`frequencyCaps`	array	Buyer-side caps enforced by Scope3 across all publishers
`brandWarning`	string	Warning about brand resolution (e.g. manifest not found)

Brand resolution

Advertisers do not store brand identity directly. Instead, they reference a brand domain or website URL, and Scope3 resolves the brand identity from one of three sources:

The advertiser’s /.well-known/brand.json (per the AdCP spec)
The AdCP brand registry
Brandfetch enrichment

Pass brand: "northwind.example" and Scope3 fetches the resolved brand identity, surfacing logos, colors, fonts, tone, and product catalog under linkedBrand when available. If the advertiser is created or updated from enrichment rather than an official registry entry, the response includes brandWarning; do not retry create for that case. After reviewing the enriched details, set saveBrand: true on an update if you want to persist the brand in the registry. If no enrichment data is available, retry create with saveBrand: true only after confirming the advertiser name and brand domain.

See the Brand object guide for the brand resolution model in detail.

Uniqueness

An advertiser is unique within a customer by the pair of its brand domain and its primaryCurrency. The same brand domain can back more than one advertiser as long as each uses a different currency — for example one advertiser on northwind.example in USD and another on northwind.example in EUR. Creating a second advertiser with both the same brand domain and the same currency returns a conflict, as does changing an existing advertiser’s brand or currency onto a pair already taken by a sibling. Sandbox and non-sandbox advertisers are tracked separately, so each (brand domain, currency) pair has its own slot in each mode.

Sub-resources

The advertiser is the hub for many sub-resource collections. Each lives under /api/v2/buyer/advertisers/:advertiserId/... and inherits the advertiser’s auth, brand, and sandbox context.

Collection	Endpoint root	Purpose
Campaigns	`/api/v2/buyer/campaigns?advertiserId=…`	Marketing initiatives — flight dates, budget, products, creatives (guide)
Linked accounts	`/advertisers/:id/accounts`	Existing accounts on upstream platforms (Snap, programmatic DSPs, agency seats) — see below
Catalogs	`/advertisers/:id/catalogs`	Product / offering / inventory feeds pushed via ADCP `sync_catalogs` and reused by discovery and creative generation
Audiences	`/advertisers/:id/audiences`	First-party audiences synced via ADCP for targeting and incrementality test cohorts
Property lists	`/advertisers/:id/property-lists`	Domain/email allow-and-block lists (up to 100k entries) (guide)
Event sources	`/advertisers/:id/event-sources`	Conversion event source registration (measurement guide)
Measurement config	`/advertisers/:id/measurement-config`	MMM, incrementality, and brand-lift configuration (measurement guide)
Test cohorts / plans	`/advertisers/:id/test-cohorts`, `/advertisers/:id/test-plans/:id`	Incrementality test scaffolding (measurement guide)
Hypotheses	`/advertisers/:id/hypotheses`	A/B test hypotheses
Belief state	`/advertisers/:id/belief-state`	Bayesian belief state from the measurement engine (measurement guide)
Tracking config	`/advertisers/:id/tracking-config`	Tracking macro and pixel template configuration
UTM config	inline on the advertiser	Default UTM parameters appended to landing-page URLs (set via `utmConfig` on create/update)
Frequency caps	inline on the advertiser	Buyer-side caps that flow down to all child campaigns (guide)
Allocations	`/advertisers/:id/allocations`	Budget allocation entries used by the optimizer
Event summary	`/advertisers/:id/events/summary`	Aggregated conversion event metrics
Syndication	`/advertisers/:id/syndicate`	Syndicate first-party audiences to partner platforms
Log event	`/advertisers/:id/log-event`	Custom event ingestion (guide)

See the Buyer API Reference for the full request and response shape of each.

Lifecycle

Create the advertiser

Provide a name and a brand domain. Optionally link partner accounts, set sandbox mode, configure UTM params, and add buyer-side frequency caps. Sandbox flag is locked after creation.

Configure defaults

Update optimizationApplyMode, UTM params, and frequency caps as your operational policy evolves. Child campaigns inherit these defaults unless overridden.

Run campaigns

Create campaigns under the advertiser. Discovery, audiences, and creatives are scoped to this advertiser.

Archive when done

DELETE /api/v2/buyer/advertisers/:id archives the advertiser (soft delete). Use POST /api/v2/buyer/advertisers/:id/restore to bring it back.

Common operations

Create an advertiser

curl -X POST https://api.interchange.io/api/v2/buyer/advertisers \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "description": "Acme global advertiser account",
    "brand": "acme.com",
    "optimizationApplyMode": "MANUAL",
    "campaignBudgetType": "total_budget",
    "sandbox": false
  }'

Get / list advertisers

# List active advertisers (summary rows)
curl "https://api.interchange.io/api/v2/buyer/advertisers?status=ACTIVE&limit=50" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

# Get a single advertiser (full resource — linkedBrand, linkedAccounts, utmConfig, frequencyCaps)
curl https://api.interchange.io/api/v2/buyer/advertisers/12345 \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

List rows return the summary shape — id, name, status, sandbox, brand, linkedAccountCount, createdAt, updatedAt. Call GET /api/v2/buyer/advertisers/:id for the full resource (resolved brand object, full linked-account list, UTM config, frequency caps).

List response

{
  "items": [
    {
      "id": "12345",
      "name": "Acme Corp",
      "status": "ACTIVE",
      "sandbox": false,
      "brand": "acme.com",
      "linkedAccountCount": 3,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-01-20T14:45:00Z"
    }
  ],
  "total": 1,
  "hasMore": false,
  "nextOffset": null
}

List supports filtering: status, name (partial match), sandbox (true/false), plus limit and offset pagination.

Update an advertiser

curl -X PUT https://api.interchange.io/api/v2/buyer/advertisers/12345 \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corporation",
    "optimizationApplyMode": "AUTO",
    "frequencyCaps": [
      { "max_impressions": 5, "window": { "interval": 7, "unit": "days" } }
    ]
  }'

sandbox is immutable after creation. To convert sandbox work to production, create a new production advertiser. When frequencyCaps is provided on update, it replaces all existing non-archived caps. Pass an empty array to clear; omit the field to leave caps untouched.

Archive / restore

curl -X DELETE https://api.interchange.io/api/v2/buyer/advertisers/12345 \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

curl -X POST https://api.interchange.io/api/v2/buyer/advertisers/12345/restore \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Linked accounts

The linkedAccounts field connects the advertiser to existing accounts on upstream platforms — Snap, programmatic DSPs, agency seats. Each linked account is the pre-existing seat ID a partner already has for this brand or buyer; the link makes that ID addressable to Scope3 for cross-platform reporting and ROUTED campaign execution.

Use linkedAccounts whenever the buyer already has a relationship with the upstream platform — an existing Snap seat, a DV360/Trade Desk account, an agency-managed seat. Linked accounts let Scope3 reuse the seat ID for unified reporting and pass through to ROUTED campaigns without re-provisioning credentials per call. For DECISIONED campaigns where Scope3 transacts on the buyer’s behalf, linked accounts are optional but unlock cross-platform reporting joins.

Fields

Each link binds these fields:

Field	Type	Notes
`storefrontId`	integer	Storefront the source lives on. Get from `GET /api/v2/buyer/storefronts`.
`sourceId`	string	Inventory source within `storefrontId` whose account is being linked.
`accountId`	string	The pre-existing account ID at the source (e.g. `acc_67890`). Must come from `GET /accounts/available` — Scope3 does not mint it.
`credentialId`	string \| null	The connected provider credential that owns this linked account. Include it when creating or updating links if multiple credentials can expose the same `accountId`.
`billingType`	string (optional)	The billing arrangement for this link. Defaults to the source’s default billing type when omitted.

billingType is a source-defined string. The supported values per source are reported on the discovery endpoint (GET /api/v2/buyer/advertisers/:advertiserId/accounts/available?storefrontId=...&sourceId=... returns billingOptions.supported and billingOptions.default). Common values:

Value	Meaning
`brand`	The advertiser is billed directly by the partner
`agency`	An agency is the billing entity acting on behalf of the brand

Other values may be supported by individual partners — always check billingOptions.supported before sending.

Endpoints

Method	Path	Purpose
`GET`	`/api/v2/buyer/advertisers/:advertiserId/accounts`	List linked accounts on the advertiser
`GET`	`/api/v2/buyer/advertisers/:advertiserId/accounts/available`	List accounts the source has discovered but not yet linked
`GET`	`/api/v2/buyer/advertisers/:advertiserId/accounts/:accountId`	Get a single linked account
`POST`	`/api/v2/buyer/advertisers/:advertiserId/accounts`	Link a source account to the advertiser

List linked accounts

curl "https://api.interchange.io/api/v2/buyer/advertisers/12345/accounts?storefrontId=1&sourceId=src_main&status=active&take=50" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Filters: storefrontId + sourceId (must be paired), status (active, pending_approval, payment_required, suspended, closed). Pagination: take, skip.

Response

{
  "data": {
    "accounts": [
      {
        "linkId": "42",
        "accountId": "acc_67890",
        "credentialId": "cred_snap_coke",
        "name": "Acme c/o Pinnacle",
        "sources": [
          {
            "storefrontId": 1,
            "storefrontName": "Retail Media Network",
            "sourceId": "src_main",
            "sourceName": "Retail Network Agent"
          }
        ],
        "advertiserId": "12345",
        "billing": "brand",
        "status": "active",
        "createdAt": "2025-01-15T10:30:00Z",
        "updatedAt": "2025-01-20T14:45:00Z"
      }
    ],
    "total": 1
  }
}

Link an account

curl -X POST https://api.interchange.io/api/v2/buyer/advertisers/12345/accounts \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "storefrontId": 1,
    "sourceId": "src_main",
    "accountId": "acc_67890",
    "billingType": "brand"
  }'

The response carries the full AccountOutput with the server-assigned linkId. To pre-fill the request body, call GET /accounts/available?storefrontId=1&sourceId=src_main first — it returns every discovered account with its supported billingOptions.

Get a single linked account

curl https://api.interchange.io/api/v2/buyer/advertisers/12345/accounts/acc_67890 \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Returns the same AccountOutput shape as list. Use this to confirm a link’s current status after a source-side state change (e.g. moving from pending_approval to active).

Linked accounts surface external account IDs (e.g. acc_67890) so cross-platform reporting and ROUTED campaigns can target them without re-discovering credentials. The linkId is the Scope3-side primary key for the link itself; the accountId is the source-side account.

Sandbox advertisers

Set sandbox: true at creation to mark the advertiser as test-only. All ADCP operations under sandbox advertisers — discovery, media buy creation, execution — route to sandbox-flagged sales agent accounts. No real platform calls are made and no real spend occurs. Use sandbox advertisers to:

Rehearse the discovery → execute → report flow end-to-end
Validate creative manifests without notifying publishers
Train AI agents against the API without billing implications

Optimization apply mode

optimizationApplyMode controls whether Scope3’s RL optimizer applies suggestions to media buys automatically.

MANUAL (default) — suggestions appear in the suggestion feed; a human or agent must approve before they hit media buys
AUTO — suggestions are applied immediately

The advertiser-level setting is the default for child campaigns. Each campaign can override it.

Campaign

Marketing initiatives owned by the advertiser

Brand

Brand identity resolved from AdCP registry or /.well-known/brand.json

Frequency caps

Buyer-side caps enforced by Scope3 across publishers

Creatives

Manifest-based creatives nested under campaigns

​Overview

​Why advertisers matter

​Key fields

​Summary shape (list rows)

​Full shape (single advertiser)

​Brand resolution

​Uniqueness

​Sub-resources

​Lifecycle

​Common operations

​Create an advertiser

​Get / list advertisers

​Update an advertiser

​Archive / restore

​Linked accounts

​Fields

​Endpoints

​List linked accounts

​Link an account

​Get a single linked account

​Sandbox advertisers

​Optimization apply mode

​Related concepts

Campaign

Brand

Frequency caps

Creatives

Overview

Why advertisers matter

Key fields

Summary shape (list rows)

Full shape (single advertiser)

Brand resolution

Uniqueness

Sub-resources

Lifecycle

Common operations

Create an advertiser

Get / list advertisers

Update an advertiser

Archive / restore

Linked accounts

Fields

Endpoints

List linked accounts

Link an account

Get a single linked account

Sandbox advertisers

Optimization apply mode

Related concepts