Skip to main content
POST /api/v2/buyer/advertisers Creates an advertiser — the top-level account that owns campaigns, creatives, audiences, and linked partner accounts. Provide a name and a brand domain; Scope3 resolves brand identity from /.well-known/brand.json, the AdCP registry, or Brandfetch enrichment.

​
Request

curl -X POST https://api.interchange.io/api/v2/buyer/advertisers \
  -H "Authorization: Bearer $SCOPE3_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Corp",
    "description": "Global advertising account for Acme Corporation",
    "brand": "acme.com",
    "primaryCurrency": "USD",
    "optimizationApplyMode": "MANUAL",
    "campaignBudgetType": "total_budget",
    "sandbox": false
  }'

​
Parameters

FieldTypeRequiredNotes
namestringYesAdvertiser name (1–255 chars)
brandstringYesBrand domain (e.g. acme.com) or brand website URL
descriptionstringNoOptional description (max 1000 chars)
saveBrandbooleanNoWhen 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
primaryCurrencystringNoISO 4217 code (3 letters). Defaults to USD. Campaigns under this advertiser must use it
optimizationApplyModeenumNoAUTO or MANUAL. Default MANUAL
campaignBudgetTypeenumNototal_budget (default) — budget covers media plus fees
sandboxbooleanNoWhen true, all ADCP calls route to sandbox accounts. Immutable after creation. Default false
linkedAccountsarrayNoPartner 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
utmConfigarrayNoDefault UTM params (max 20). Each: paramKey, paramValue
frequencyCapsarrayNoBuyer-side caps. Each: max_impressions plus window ({ interval, unit }); unit is seconds, minutes, hours, days, or campaign
dataDeliveryobjectNoOffline data delivery destination config

​
Response

{
  "id": "12345",
  "name": "Acme Corp",
  "description": null,
  "status": "ACTIVE",
  "sandbox": false,
  "brand": "acme.com",
  "primaryCurrency": "USD",
  "optimizationApplyMode": "MANUAL",
  "campaignBudgetType": "total_budget",
  "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": "scope3", "source": "seat" },
    { "paramKey": "utm_medium", "paramValue": "agentic", "source": "seat" },
    { "paramKey": "utm_campaign", "paramValue": "{CAMPAIGN_ID}", "source": "seat" },
    { "paramKey": "utm_content", "paramValue": "{CREATIVE_ID}", "source": "seat" },
    { "paramKey": "utm_media_buy", "paramValue": "{MEDIA_BUY_ID}", "source": "seat" },
    { "paramKey": "utm_package", "paramValue": "{PACKAGE_ID}", "source": "seat" }
  ]
}
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.
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