curl --request POST \
--url https://api.interchange.io/api/v2/buyer/advertisers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Acme Corp",
"brand": "nike.com",
"primaryCurrency": "USD"
}
'import requests
url = "https://api.interchange.io/api/v2/buyer/advertisers"
payload = {
"name": "Acme Corp",
"brand": "nike.com",
"primaryCurrency": "USD"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: 'Acme Corp', brand: 'nike.com', primaryCurrency: 'USD'})
};
fetch('https://api.interchange.io/api/v2/buyer/advertisers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "12345",
"name": "Acme Corp",
"status": "ACTIVE",
"createdAt": "2025-01-15T10:30:00Z",
"updatedAt": "2025-01-20T14:45:00Z",
"brandCountries": [
"AD"
],
"brandCountriesKnown": true,
"sandbox": true,
"optimizationApplyMode": "AUTO",
"primaryCurrency": "USD",
"preferredTimezone": "Europe/Amsterdam",
"currencyLocked": true,
"reportingTimezoneLocked": true,
"channels": [
"display"
],
"description": "Global advertising account for Acme Corporation",
"linkedBrand": {
"id": "brand_123",
"name": "Acme Brand",
"domain": "acme.com",
"manifest": {
"name": "Acme Corporation",
"url": "https://www.acme.com",
"logos": [
{
"url": "<string>",
"tags": [
"<string>"
],
"background": "dark-bg",
"width": 4503599627370495,
"height": 4503599627370495
}
],
"colors": {
"primary": "#FF5733",
"secondary": "<string>",
"accent": "<string>",
"background": "<string>",
"text": "<string>"
},
"fonts": {
"primary": "Roboto",
"secondary": "<string>",
"fontUrls": [
"<string>"
]
},
"tone": "Professional, friendly, and innovative",
"tagline": "Innovation for Everyone",
"assets": [
{
"assetId": "<string>",
"assetType": "<string>",
"url": "<string>",
"name": "<string>",
"description": "<string>",
"tags": [
"<string>"
],
"width": 4503599627370495,
"height": 4503599627370495,
"durationSeconds": 1,
"fileSizeBytes": 4503599627370495,
"format": "<string>",
"metadata": {}
}
],
"productCatalog": {
"feedUrl": "<string>",
"feedFormat": "google_merchant_center",
"categories": [
"<string>"
],
"lastUpdated": "2023-11-07T05:31:56Z",
"updateFrequency": "realtime"
},
"disclaimers": [
{
"text": "<string>",
"required": true,
"context": "<string>"
}
],
"industry": "Technology",
"advertiserIndustry": "food_beverage.restaurants",
"targetAudience": "Small business owners aged 25-45",
"contact": {
"email": "jsmith@example.com",
"phone": "<string>",
"website": "<string>"
},
"metadata": {
"createdDate": "2023-11-07T05:31:56Z",
"updatedDate": "2023-11-07T05:31:56Z",
"version": "1.0.0"
}
},
"logoUrl": "https://acme.com/logo.png",
"industry": "Technology",
"colors": {
"primary": "#FF5733"
},
"tagline": "Innovation for Everyone",
"tone": "Professional, friendly, and innovative"
},
"brand": "nike.com",
"brandWarning": "<string>",
"linkedAccounts": [
{
"linkId": "<string>",
"accountId": "<string>",
"name": "<string>",
"sources": [
{
"storefrontId": 0,
"storefrontName": "<string>",
"sourceId": "<string>",
"sourceName": "<string>"
}
],
"status": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"credentialId": "42"
}
],
"utmConfig": [
{
"paramKey": "utm_campaign",
"paramValue": "{CAMPAIGN_ID}",
"source": "advertiser"
}
],
"dataDelivery": {
"credentials": [
{
"credentialId": "<string>",
"name": "<string>",
"destinationType": "GCS",
"config": {
"type": "GCS",
"bucket": "<string>"
},
"status": "PENDING",
"createdAt": "<string>",
"updatedAt": "<string>",
"statusError": "<string>",
"validatedAt": "<string>",
"expiresAt": "<string>"
}
],
"outputs": [
{
"outputConfigId": "<string>",
"dataDeliveryType": "MB_DELIVERY",
"cadence": "HOURLY",
"enabled": true,
"credentialId": "<string>",
"credentialName": "<string>",
"deliveryConfig": {
"type": "GCS",
"pathPrefix": "",
"format": "JSONL"
},
"source": "advertiser",
"createdAt": "<string>",
"updatedAt": "<string>",
"syncWeeklyDay": 3
}
]
},
"frequencyCaps": [
{
"max_impressions": 3,
"window": {
"interval": 4503599627370496,
"unit": "seconds"
},
"id": "12345",
"targetLevel": "ADVERTISER",
"targetId": "camp_abc123",
"createdAt": "<string>",
"updatedAt": "<string>",
"archivedAt": "<string>"
}
]
}{
"data": null,
"error": {
"code": "<string>",
"message": "<string>",
"field": "<string>",
"details": {}
}
}{
"data": null,
"error": {
"code": "<string>",
"message": "<string>",
"field": "<string>",
"details": {}
}
}{
"data": null,
"error": {
"code": "<string>",
"message": "<string>",
"field": "<string>",
"details": {}
}
}{
"data": null,
"error": {
"code": "<string>",
"message": "<string>",
"field": "<string>",
"details": {}
}
}Create advertiser
Create a new advertiser. Advertisers are the top-level entity for campaigns.
curl --request POST \
--url https://api.interchange.io/api/v2/buyer/advertisers \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Acme Corp",
"brand": "nike.com",
"primaryCurrency": "USD"
}
'import requests
url = "https://api.interchange.io/api/v2/buyer/advertisers"
payload = {
"name": "Acme Corp",
"brand": "nike.com",
"primaryCurrency": "USD"
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({name: 'Acme Corp', brand: 'nike.com', primaryCurrency: 'USD'})
};
fetch('https://api.interchange.io/api/v2/buyer/advertisers', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"id": "12345",
"name": "Acme Corp",
"status": "ACTIVE",
"createdAt": "2025-01-15T10:30:00Z",
"updatedAt": "2025-01-20T14:45:00Z",
"brandCountries": [
"AD"
],
"brandCountriesKnown": true,
"sandbox": true,
"optimizationApplyMode": "AUTO",
"primaryCurrency": "USD",
"preferredTimezone": "Europe/Amsterdam",
"currencyLocked": true,
"reportingTimezoneLocked": true,
"channels": [
"display"
],
"description": "Global advertising account for Acme Corporation",
"linkedBrand": {
"id": "brand_123",
"name": "Acme Brand",
"domain": "acme.com",
"manifest": {
"name": "Acme Corporation",
"url": "https://www.acme.com",
"logos": [
{
"url": "<string>",
"tags": [
"<string>"
],
"background": "dark-bg",
"width": 4503599627370495,
"height": 4503599627370495
}
],
"colors": {
"primary": "#FF5733",
"secondary": "<string>",
"accent": "<string>",
"background": "<string>",
"text": "<string>"
},
"fonts": {
"primary": "Roboto",
"secondary": "<string>",
"fontUrls": [
"<string>"
]
},
"tone": "Professional, friendly, and innovative",
"tagline": "Innovation for Everyone",
"assets": [
{
"assetId": "<string>",
"assetType": "<string>",
"url": "<string>",
"name": "<string>",
"description": "<string>",
"tags": [
"<string>"
],
"width": 4503599627370495,
"height": 4503599627370495,
"durationSeconds": 1,
"fileSizeBytes": 4503599627370495,
"format": "<string>",
"metadata": {}
}
],
"productCatalog": {
"feedUrl": "<string>",
"feedFormat": "google_merchant_center",
"categories": [
"<string>"
],
"lastUpdated": "2023-11-07T05:31:56Z",
"updateFrequency": "realtime"
},
"disclaimers": [
{
"text": "<string>",
"required": true,
"context": "<string>"
}
],
"industry": "Technology",
"advertiserIndustry": "food_beverage.restaurants",
"targetAudience": "Small business owners aged 25-45",
"contact": {
"email": "jsmith@example.com",
"phone": "<string>",
"website": "<string>"
},
"metadata": {
"createdDate": "2023-11-07T05:31:56Z",
"updatedDate": "2023-11-07T05:31:56Z",
"version": "1.0.0"
}
},
"logoUrl": "https://acme.com/logo.png",
"industry": "Technology",
"colors": {
"primary": "#FF5733"
},
"tagline": "Innovation for Everyone",
"tone": "Professional, friendly, and innovative"
},
"brand": "nike.com",
"brandWarning": "<string>",
"linkedAccounts": [
{
"linkId": "<string>",
"accountId": "<string>",
"name": "<string>",
"sources": [
{
"storefrontId": 0,
"storefrontName": "<string>",
"sourceId": "<string>",
"sourceName": "<string>"
}
],
"status": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"credentialId": "42"
}
],
"utmConfig": [
{
"paramKey": "utm_campaign",
"paramValue": "{CAMPAIGN_ID}",
"source": "advertiser"
}
],
"dataDelivery": {
"credentials": [
{
"credentialId": "<string>",
"name": "<string>",
"destinationType": "GCS",
"config": {
"type": "GCS",
"bucket": "<string>"
},
"status": "PENDING",
"createdAt": "<string>",
"updatedAt": "<string>",
"statusError": "<string>",
"validatedAt": "<string>",
"expiresAt": "<string>"
}
],
"outputs": [
{
"outputConfigId": "<string>",
"dataDeliveryType": "MB_DELIVERY",
"cadence": "HOURLY",
"enabled": true,
"credentialId": "<string>",
"credentialName": "<string>",
"deliveryConfig": {
"type": "GCS",
"pathPrefix": "",
"format": "JSONL"
},
"source": "advertiser",
"createdAt": "<string>",
"updatedAt": "<string>",
"syncWeeklyDay": 3
}
]
},
"frequencyCaps": [
{
"max_impressions": 3,
"window": {
"interval": 4503599627370496,
"unit": "seconds"
},
"id": "12345",
"targetLevel": "ADVERTISER",
"targetId": "camp_abc123",
"createdAt": "<string>",
"updatedAt": "<string>",
"archivedAt": "<string>"
}
]
}{
"data": null,
"error": {
"code": "<string>",
"message": "<string>",
"field": "<string>",
"details": {}
}
}{
"data": null,
"error": {
"code": "<string>",
"message": "<string>",
"field": "<string>",
"details": {}
}
}{
"data": null,
"error": {
"code": "<string>",
"message": "<string>",
"field": "<string>",
"details": {}
}
}{
"data": null,
"error": {
"code": "<string>",
"message": "<string>",
"field": "<string>",
"details": {}
}
}Authorizations
API key or access token
Headers
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.
16 - 255^[A-Za-z0-9_.:-]+$"advertiser-create-20260821-001"
Body
Request body for creating a new advertiser
Name of the advertiser
1 - 255"Acme Corp"
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.
1"nike.com"
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.
3^[A-Za-z]{3}$"USD"
Optional description of the advertiser
1000"Global advertising account for Acme Corporation"
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.
Accounts to link to this advertiser at creation time. Each entry references a discovered account from a partner.
Show child attributes
Show child attributes
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".
AUTO, MANUAL 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.
249Preferred IANA timezone for seller account calendar and reporting boundaries. Each seller may use a different fixed or assigned timezone.
1 - 64"Europe/Amsterdam"
AdCP media channels this advertiser expects to use. These are editable planning preferences, not seller qualification or proof that supply is available.
25display 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.
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.
20Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
Response
Create advertiser
Advertiser resource representation
Unique identifier for the advertiser
"12345"
Name of the advertiser
"Acme Corp"
Current status of the advertiser
ACTIVE, ARCHIVED When the advertiser was created (ISO 8601)
^(?:(?:\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))$"2025-01-15T10:30:00Z"
When the advertiser was last updated (ISO 8601)
^(?:(?:\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))$"2025-01-20T14:45:00Z"
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.
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 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.
When true, this advertiser is in sandbox mode. All ADCP operations use sandbox-flagged accounts. Cannot be changed after creation.
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.
AUTO, MANUAL ISO 4217 currency for this advertiser. Every campaign under this advertiser is created in this currency, and selected product pricing must match it.
3^[A-Z]{3}$"USD"
Preferred IANA timezone. A connected seller may use a different fixed or assigned timezone.
"Europe/Amsterdam"
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.
True once the advertiser has at least one campaign or linked seller account. While false, the reporting time-zone preference can still be changed.
Editable AdCP media-channel preferences for this advertiser. These do not represent seller qualification or guaranteed supply.
display Description of the advertiser
"Global advertising account for Acme Corporation"
The brand linked to this advertiser. Only present when includeBrand=true is passed to the list endpoint.
Show child attributes
Show child attributes
The brand domain associated with this advertiser
"nike.com"
Warning about brand resolution (e.g., manifest not found)
Linked partner accounts for this advertiser. Only present when includeAccounts=true is passed to the list endpoint.
Show child attributes
Show child attributes
Advertiser-level UTM parameter configuration. Only present when UTM params are configured for this advertiser.
Show child attributes
Show child attributes
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.
Show child attributes
Show child attributes
Buyer-side frequency cap configs for this advertiser. Always present on single-GET; on LIST only when includeFrequencyCaps=true.
Show child attributes
Show child attributes