Skip to main content
POST
Create advertiser

Authorizations

Authorization
string
header
required

API key or access token

Headers

Idempotency-Key
string

Optional replay key. Reusing the same key and validated request within 24 hours returns the original advertiser; changing the request under the same key returns a conflict.

Required string length: 16 - 255
Pattern: ^[A-Za-z0-9_.:-]+$
Example:

"advertiser-create-20260821-001"

Body

application/json

Request body for creating a new advertiser

name
string
required

Name of the advertiser

Required string length: 1 - 255
Example:

"Acme Corp"

brand
string
required

Brand domain (e.g., "nike.com") or brand website URL. Brand identity is resolved from /.well-known/brand.json, the AdCP registry, or Brandfetch enrichment.

Minimum string length: 1
Example:

"nike.com"

primaryCurrency
string
required

ISO 4217 currency for this advertiser. Required and fixed at creation. Every campaign under this advertiser is created in this currency, and media-buy product pricing must match it.

Required string length: 3
Pattern: ^[A-Za-z]{3}$
Example:

"USD"

description
string

Optional description of the advertiser

Maximum string length: 1000
Example:

"Global advertising account for Acme Corporation"

saveBrand
boolean
default:false

When true, auto-saves the resolved brand identity to the AdCP registry if the brand is not yet registered. Normally not required for advertiser creation when enrichment succeeds; set this only after reviewing enrichment or when the user confirms registry persistence is desired.

linkedAccounts
object[]

Accounts to link to this advertiser at creation time. Each entry references a discovered account from a partner.

optimizationApplyMode
enum<string>

Default mode for applying Scope3 AI model optimizations to media buys for campaigns under this advertiser. When set to "AUTO", optimizations are applied automatically; when "MANUAL", they require approval. Defaults to "MANUAL".

Available options:
AUTO,
MANUAL
brandCountries
string[]

Canonical ISO 3166-1 alpha-2 countries that qualify this advertiser's AdCP 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.

Maximum array length: 249
preferredTimezone
string
default:UTC

Preferred IANA timezone for seller account calendar and reporting boundaries. Each seller may use a different fixed or assigned timezone.

Required string length: 1 - 64
Example:

"Europe/Amsterdam"

channels
enum<string>[]

AdCP media channels this advertiser expects to use. These are editable planning preferences, not seller qualification or proof that supply is available.

Maximum array length: 25
Available options:
display
sandbox
boolean
default:false

When true, this advertiser operates in sandbox mode. All ADCP operations will use sandbox-flagged accounts — no real platform calls, no real spend. Cannot be changed after creation.

utmConfig
object[]

Default UTM (Urchin Tracking Module) parameters for this advertiser. These are appended to landing page URLs during clickthrough redirection. Campaign-level UTM config can override these per param key.

Maximum array length: 20
dataDelivery
object

Data-delivery configuration for this advertiser. Groups standing Data Delivery Outputs and the credentials they reference. Distinct from media-buy reporting fields elsewhere in the API.

frequencyCaps
object[]

Buyer-side frequency cap configs to apply to this advertiser. Enforced by Scope3 across all publishers; distinct from publisher-side caps in package target_overlay.

Response

Create advertiser

Advertiser resource representation

id
string
required

Unique identifier for the advertiser

Example:

"12345"

name
string
required

Name of the advertiser

Example:

"Acme Corp"

status
enum<string>
required

Current status of the advertiser

Available options:
ACTIVE,
ARCHIVED
createdAt
string<date-time>
required

When the advertiser was created (ISO 8601)

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Example:

"2025-01-15T10:30:00Z"

updatedAt
string<date-time>
required

When the advertiser was last updated (ISO 8601)

Pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d(?::[0-5]\d(?:\.\d+)?)?(?:Z))$
Example:

"2025-01-20T14:45:00Z"

brandCountries
enum<string>[]
required

Canonical country qualifiers for this advertiser's BrandKey scope. Empty means no country qualifier when brandCountriesKnown is true. Campaigns may inherit this market scope and refine it with delivery targeting.

Available options:
AD,
AE,
AF,
AG,
AI,
AL,
AM,
AO,
AQ,
AR,
AS,
AT,
AU,
AW,
AX,
AZ,
BA,
BB,
BD,
BE,
BF,
BG,
BH,
BI,
BJ,
BL,
BM,
BN,
BO,
BQ,
BR,
BS,
BT,
BV,
BW,
BY,
BZ,
CA,
CC,
CD,
CF,
CG,
CH,
CI,
CK,
CL,
CM,
CN,
CO,
CR,
CU,
CV,
CW,
CX,
CY,
CZ,
DE,
DJ,
DK,
DM,
DO,
DZ,
EC,
EE,
EG,
EH,
ER,
ES,
ET,
FI,
FJ,
FK,
FM,
FO,
FR,
GA,
GB,
GD,
GE,
GF,
GG,
GH,
GI,
GL,
GM,
GN,
GP,
GQ,
GR,
GS,
GT,
GU,
GW,
GY,
HK,
HM,
HN,
HR,
HT,
HU,
ID,
IE,
IL,
IM,
IN,
IO,
IQ,
IR,
IS,
IT,
JE,
JM,
JO,
JP,
KE,
KG,
KH,
KI,
KM,
KN,
KP,
KR,
KW,
KY,
KZ,
LA,
LB,
LC,
LI,
LK,
LR,
LS,
LT,
LU,
LV,
LY,
MA,
MC,
MD,
ME,
MF,
MG,
MH,
MK,
ML,
MM,
MN,
MO,
MP,
MQ,
MR,
MS,
MT,
MU,
MV,
MW,
MX,
MY,
MZ,
NA,
NC,
NE,
NF,
NG,
NI,
NL,
NO,
NP,
NR,
NU,
NZ,
OM,
PA,
PE,
PF,
PG,
PH,
PK,
PL,
PM,
PN,
PR,
PS,
PT,
PW,
PY,
QA,
RE,
RO,
RS,
RU,
RW,
SA,
SB,
SC,
SD,
SE,
SG,
SH,
SI,
SJ,
SK,
SL,
SM,
SN,
SO,
SR,
SS,
ST,
SV,
SX,
SY,
SZ,
TC,
TD,
TF,
TG,
TH,
TJ,
TK,
TL,
TM,
TN,
TO,
TR,
TT,
TV,
TW,
TZ,
UA,
UG,
UM,
US,
UY,
UZ,
VA,
VC,
VE,
VG,
VI,
VN,
VU,
WF,
WS,
YE,
YT,
ZA,
ZM,
ZW
brandCountriesKnown
boolean
required

False only for a legacy advertiser whose BrandKey country scope has not been classified. When false, an empty brandCountries array means unknown rather than a confirmed global scope.

sandbox
boolean
required

When true, this advertiser is in sandbox mode. All ADCP operations use sandbox-flagged accounts. Cannot be changed after creation.

optimizationApplyMode
enum<string>
required

Default mode for applying Scope3 AI model optimizations to media buys for campaigns under this advertiser. When set to "AUTO", optimizations are applied automatically; when "MANUAL", they require approval.

Available options:
AUTO,
MANUAL
primaryCurrency
string
required

ISO 4217 currency for this advertiser. Every campaign under this advertiser is created in this currency, and selected product pricing must match it.

Required string length: 3
Pattern: ^[A-Z]{3}$
Example:

"USD"

preferredTimezone
string | null
required

Preferred IANA timezone. A connected seller may use a different fixed or assigned timezone.

Example:

"Europe/Amsterdam"

currencyLocked
boolean
required

True once the advertiser has at least one campaign or seller-account binding. Direct v2 API clients may change currency only while this is false; the canonical UI keeps Currency read-only after creation.

reportingTimezoneLocked
boolean
required

True once the advertiser has at least one campaign or linked seller account. While false, the reporting time-zone preference can still be changed.

channels
enum<string>[]
required

Editable AdCP media-channel preferences for this advertiser. These do not represent seller qualification or guaranteed supply.

Available options:
display
description
string

Description of the advertiser

Example:

"Global advertising account for Acme Corporation"

linkedBrand
object

The brand linked to this advertiser. Only present when includeBrand=true is passed to the list endpoint.

brand
string

The brand domain associated with this advertiser

Example:

"nike.com"

brandWarning
string

Warning about brand resolution (e.g., manifest not found)

linkedAccounts
object[]

Linked partner accounts for this advertiser. Only present when includeAccounts=true is passed to the list endpoint.

utmConfig
object[]

Advertiser-level UTM parameter configuration. Only present when UTM params are configured for this advertiser.

dataDelivery
object

Data-delivery configuration for this advertiser. Groups standing Data Delivery Outputs and the credentials they reference. Distinct from media-buy reporting fields elsewhere in the API.

frequencyCaps
object[]

Buyer-side frequency cap configs for this advertiser. Always present on single-GET; on LIST only when includeFrequencyCaps=true.