Create advertiser

POST /api/v2/buyer/advertisers Creates an advertiser — the top-level account that owns campaigns, creatives, audiences, and linked partner accounts. Confirm the account-level operator in Buyer Setup first. Provide a name and brand domain; Apostra resolves brand identity from /.well-known/brand.json, the AdCP registry, or Brandfetch enrichment. Media partner connections are managed separately in Media Partners. To classify an advertiser with buyer-owned labels, use the V3 MCP save_advertiser tool after this REST create. Labels are not a REST field; see Dimensions and labels.

Request

curl -X POST https://api.apostra.com/api/v2/buyer/advertisers \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Idempotency-Key: advertiser-create-20260821-001" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "brand": "acme.com",
    "brandCountries": ["DE", "NL"],
    "primaryCurrency": "USD",
    "preferredTimezone": "Europe/Amsterdam",
    "channels": ["display", "ctv"],
    "optimizationApplyMode": "MANUAL",
    "sandbox": false
  }'

{
  "name": "Acme International",
  "brand": "acme.com",
  "brandCountries": [],
  "primaryCurrency": "USD",
  "preferredTimezone": "UTC",
  "channels": ["display"],
  "sandbox": false
}

Set Idempotency-Key (16–255 letters, numbers, underscores, periods, colons, or hyphens) when a create may be retried. Repeating the same validated request and key within 24 hours returns the original advertiser with 201 and Idempotency-Replayed: true; it does not create a duplicate. Reusing the key with a different request returns 409 CONFLICT. Keys are isolated to your customer account.

Parameters

Field	Type	Required	Notes
`name`	string	Yes	Advertiser name (1–255 chars)
`brand`	string	Yes	Brand domain (e.g. `acme.com`) or brand website URL
`brandCountries`	array	No	ISO 3166-1 alpha-2 countries for this advertiser’s BrandKey scope (for example, Nike Italy uses `IT`). Empty means no country qualifier. Campaigns may inherit this market scope and refine it with delivery targeting
`description`	string	No	Optional description (max 1000 chars)
`saveBrand`	boolean	No	When `true`, auto-saves the resolved or confirmed brand identity to the AdCP registry if not yet registered. Normally not required when enrichment succeeds; use after review when registry persistence is desired. Default `false`
`primaryCurrency`	string	Yes	API field for Currency: an ISO 4217 code (3 letters). Campaigns under this advertiser must use it. The raw API can change it only before the first campaign or seller-account binding
`preferredTimezone`	string	No	Preferred IANA Reporting time zone. Default `UTC`. A seller may use a different fixed or assigned time zone
`channels`	array	No	Editable AdCP media-channel preferences such as `display`, `olv`, or `ctv`. Preferences do not qualify sellers or guarantee supply
`optimizationApplyMode`	enum	No	`AUTO` or `MANUAL`. Default `MANUAL`
`sandbox`	boolean	No	When `true`, all ADCP calls route to sandbox accounts. Immutable after creation. Default `false`
`linkedAccounts`	array	No	Partner accounts to link at creation. Each: `storefrontId`, `sourceId`, `accountId`, `credentialId?`, `billingType?`. Use `credentialId` from list available accounts when multiple connected credentials expose the same account ID
`utmConfig`	array	No	Click-URL parameters (max 50). Each: `paramKey`, `paramValue`. Omit for none; see Click-URL parameters
`frequencyCaps`	array	No	Buyer-side caps. Each: `max_impressions` plus `window` (`{ interval, unit }`); `unit` is `seconds`, `minutes`, `hours`, `days`, or `campaign`
`dataDelivery`	object	No	Offline data delivery destination config

Response

{
  "id": "12345",
  "name": "Acme Corp",
  "description": null,
  "status": "ACTIVE",
  "sandbox": false,
  "brand": "acme.com",
  "brandCountries": ["DE", "NL"],
  "primaryCurrency": "USD",
  "preferredTimezone": "Europe/Amsterdam",
  "currencyLocked": false,
  "reportingTimezoneLocked": false,
  "channels": ["display", "ctv"],
  "optimizationApplyMode": "MANUAL",
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-01-15T10:30:00Z",
  "linkedBrand": {
    "id": "brand_456",
    "name": "Acme Corp",
    "domain": "acme.com",
    "manifest": { "name": "Acme Corp", "url": "https://www.acme.com" }
  },
  "utmConfig": [
    { "paramKey": "utm_source", "paramValue": "acme", "source": "advertiser" },
    { "paramKey": "utm_campaign", "paramValue": "{CAMPAIGN_ID}", "source": "advertiser" }
  ]
}

utmConfig echoes the parameters the request set. A request without utmConfig returns an advertiser with no click-URL parameters. Returns 201 with the full advertiser resource. id is the stable identifier you pass to every sub-resource operation. If the brand resolves through enrichment rather than an official registry entry, the response carries a brandWarning. If no registry or enrichment data is found, the first create returns 400; after confirming the advertiser name and brand domain, retry with saveBrand: true to register that brand identity.

Errors

400 VALIDATION_ERROR — missing name or brand, or an unsupported primaryCurrency.
409 CONFLICT — the Idempotency-Key was already used with a different request, is outside its replay window, or the original request is still in flight.

See Errors for the full error contract.

Advertiser tasks

All advertiser operations

Advertiser overview

Fields, lifecycle, and concepts

List available accounts

Find accounts to link

Update advertiser

Change defaults later

Start building

Core Concepts

Buyer operations

Seller operations

Cross-Cutting Reference

Buyer API reference

Seller API reference

Release Notes

Create advertiser

Request

Parameters

Response

Errors

Advertiser tasks

Advertiser overview

List available accounts

Update advertiser

​Request

​Parameters

​Response

​Errors

​Related

Advertiser tasks

Advertiser overview

List available accounts

Update advertiser

Request

Parameters

Response

Errors

Related