Advertiser

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

Field	Type	Notes
`id`	string	Stable advertiser identifier
`name`	string	Human-readable name (max 255 chars)
`description`	string	Optional description (max 1000 chars)
`status`	`ACTIVE` \| `ARCHIVED`	Soft-delete state
`brand`	string	Brand domain (e.g. `nike.com`) or full manifest URL
`linkedBrand`	object	Resolved brand identity — name, domain, logos, colors, fonts, manifest
`sandbox`	boolean	When true, all ADCP calls route to sandbox accounts. Immutable after creation.
`optimizationApplyMode`	`AUTO` \| `MANUAL`	Default for child campaigns. `MANUAL` requires approval before applying optimizations.
`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
`createdAt` / `updatedAt`	datetime	ISO 8601 timestamps

Brand resolution

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

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

Pass brand: "nike.com" and Scope3 fetches the manifest, surfacing logos, colors, fonts, tone, and product catalog under linkedBrand. If the brand isn’t registered, set saveBrand: true after reviewing the enriched preview to register an enriched manifest in the registry.

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

Sub-resources

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

Collection	Endpoint root	Purpose
Campaigns	`/api/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/buyer/advertisers/:id archives the advertiser (soft delete). Use POST /api/buyer/advertisers/:id/restore to bring it back.

Common operations

Create an advertiser

curl -X POST https://api.agentic.scope3.com/api/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, include resolved brand and linked accounts
curl "https://api.agentic.scope3.com/api/buyer/advertisers?status=ACTIVE&includeBrand=true&includeAccounts=true&limit=50" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

# Get a single advertiser
curl https://api.agentic.scope3.com/api/buyer/advertisers/12345 \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

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

Update an advertiser

curl -X PUT https://api.agentic.scope3.com/api/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.agentic.scope3.com/api/buyer/advertisers/12345 \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

curl -X POST https://api.agentic.scope3.com/api/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 three fields:

Field	Type	Notes
`partnerId`	string	The partner agent identifier (e.g. `snap_6e2d13705a26`). Identifies which upstream platform the account lives on.
`accountId`	string	The pre-existing account ID on the partner platform (e.g. `acc_67890`). Comes from the partner — Scope3 does not mint it.
`billingType`	string (optional)	The billing arrangement for this link. Defaults to the partner’s default billing type when omitted.

billingType is a partner-defined string. The supported values per partner agent are reported on the discovery endpoint (GET /api/buyer/advertisers/:advertiserId/accounts/available?partnerId=... 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/buyer/advertisers/:advertiserId/accounts`	List linked accounts on the advertiser
`GET`	`/api/buyer/advertisers/:advertiserId/accounts/available`	List accounts the partner agent has discovered but not yet linked
`GET`	`/api/buyer/advertisers/:advertiserId/accounts/:accountId`	Get a single linked account
`POST`	`/api/buyer/advertisers/:advertiserId/accounts`	Link a partner account to the advertiser

List linked accounts

curl "https://api.agentic.scope3.com/api/buyer/advertisers/12345/accounts?partnerId=snap_6e2d13705a26&status=active&take=50" \
  -H "Authorization: Bearer $SCOPE3_API_KEY"

Filters: partnerId, status (active, pending_approval, payment_required, suspended, closed). Pagination: take, skip.

Response

{
  "data": {
    "accounts": [
      {
        "linkId": "42",
        "accountId": "acc_67890",
        "name": "Acme c/o Pinnacle",
        "partnerId": "snap_6e2d13705a26",
        "partnerName": "Snap Ads",
        "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.agentic.scope3.com/api/buyer/advertisers/12345/accounts \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "partnerId": "snap_6e2d13705a26",
    "accountId": "acc_67890",
    "billingType": "brand"
  }'

The response carries the full AccountOutput with the server-assigned linkId. To pre-fill the request body from a partner-side discovery, call GET /accounts/available?partnerId=snap_6e2d13705a26 first — it returns every discovered account with its supported billingOptions.

Get a single linked account

curl https://api.agentic.scope3.com/api/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 partner state change (e.g. moving from pending_approval to active).

Linked accounts surface external account IDs (e.g. Snap 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 partner-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

Setup

Object Guides

Workflows

Connections

Reference

Release Notes

Overview

Why advertisers matter

Key fields

Brand resolution

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

Campaign

Brand

Frequency caps

Creatives

Overview

Setup

Object Guides

Workflows

Connections

Reference

Release Notes

​Overview

​Why advertisers matter

​Key fields

​Brand resolution

​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

Brand resolution

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