curl --request POST \
--url https://api.apostra.com/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.apostra.com/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.apostra.com/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"
],
"channelsKnown": true,
"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"
}
],
"creativeResync": {
"creativeCount": 3,
"sellerCount": 2
},
"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.apostra.com/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.apostra.com/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.apostra.com/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"
],
"channelsKnown": true,
"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"
}
],
"creativeResync": {
"creativeCount": 3,
"sellerCount": 2
},
"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": {}
}
}Headers
Body
Request body for creating a new advertiser
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.
Canonical ISO 3166-1 alpha-2 countries that qualify this advertiser's AdCP BrandKey scope (for example, Nike Italy uses IT). An explicitly 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.
249Preferred IANA timezone for seller account calendar and reporting boundaries. Each seller may use a different fixed or assigned timezone. When omitted, the advertiser gets the time zone its brandCountries share (United Kingdom gives Europe/London), or UTC when there are no countries or they don't share one.
1 - 64"Europe/Amsterdam"
AdCP media channels this advertiser plans to buy. Send an empty array for All channels. When omitted, channels stay unanswered (channelsKnown is false): sellers still match the advertiser in every channel when you buy, but no seller account is set up ahead of time until you answer.
25display Click-URL parameters for this advertiser, appended to landing-page URLs when creatives sync to a seller. The array is the whole advertiser set (max 20 entries). Campaign utmConfig overrides it per key, and campaign writes are additive instead. For one model at advertiser, campaign and creative level, and to suppress an inherited key with a null value, use V3 tracking.macroAdditions (save_advertiser, save_campaign) or macroAdditions (save_creative).
20Show child attributes
Show child attributes
Response
Create advertiser
Advertiser resource representation
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. When brandCountriesKnown is true, an empty list is a confirmed global scope whose country dimension does not block automatic matching in any seller country; channel overlap and other seller eligibility rules still apply. 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 Editable AdCP media-channel preferences for this advertiser. When channelsKnown is true, an empty list is the All channels answer. Channel overlap affects automatic seller qualification, but these preferences do not create advertiser-owned selection edges or guarantee supply.
display Present when this write changed the click-URL parameters of creatives that sellers already hold on live media buys. Apostra queued a re-sync of each such creative to each seller that holds it, sent about a minute later with the parameters current at that time (or, if the seller is still reviewing an earlier copy, once that review finishes); edits in that minute join the same re-sync. Each seller decides whether the change needs re-review, and its decision appears on the creative the same way it does after a creative edit. Absent when no seller copy changes.
Show child attributes
Show child attributes