> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apostra.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create advertiser
> Open a new advertiser account
`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](/v2/object-guides/dimension).
## Request
```bash curl theme={null}
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
}'
```
```json No country qualifier theme={null}
{
"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](/v2/object-guides/advertiser#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
```json theme={null}
{
"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](/v2/reference/errors) for the full error contract.
## Related
All advertiser operations
Fields, lifecycle, and concepts
Find accounts to link
Change defaults later