Create advertiser

Deprecated. This page documents the v2 buyer API, which is closed to new API clients and switches off on 1 December 2026. Use V3 instead: see Move a v2 buyer REST integration to V3. The conversion endpoint, Log event, stays open.

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. To change an advertiser after you create it, open Advertiser settings from Settings on its row on the Advertisers Page. See Update advertiser.

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. Stored as the lowercase domain, without `www.`
`brandCountries`	array	No	ISO 3166-1 alpha-2 countries for this advertiser’s BrandKey scope (for example, Nike Italy uses `IT`). Omitting the field or passing an empty list means the advertiser works in all countries; it is not an advertiser with zero markets. 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. When omitted, the time zone `brandCountries` share (`["GB"]` gives `Europe/London`; Spain uses its main zone, `Europe/Madrid`), or `UTC` when there are no countries or they don’t share one. A seller may use a different fixed or assigned time zone
`channels`	array	No	The AdCP media channels this advertiser plans to buy, such as `display`, `olv`, or `ctv`. Send `[]` for All channels. Omit the field only if you have not decided yet: the advertiser is created with `channelsKnown: false`, and no seller account is set up ahead of time until you answer. Channel overlap affects automatic seller qualification but does not create advertiser-owned selection edges 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 20). Each: `paramKey`, `paramValue`. Omit for none. At advertiser level the array is the whole set; campaign `utmConfig` is additive instead. See How v2 `utmConfig` writes differ by layer
`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"],
  "channelsKnown": true,
  "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. The same code, on field brandCountries, means another active advertiser in your account already holds this brand in an overlapping country. The message names that advertiser and suggests countries outside the overlap; an advertiser with no countries overlaps every country, and currency does not separate the two. See One brand, one market.
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