Create campaign
curl --request POST \
--url https://api.interchange.io/api/v2/buyer/campaigns \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"advertiserId": 12345,
"name": "Q1 2025 Campaign",
"flightDates": {
"startDate": "2025-01-15T00:00:00Z",
"endDate": "2025-03-31T23:59:59Z"
},
"budget": {
"total": 1,
"currency": "<string>",
"dailyCap": 1
},
"mode": "discovery"
}
'import requests
url = "https://api.interchange.io/api/v2/buyer/campaigns"
payload = {
"advertiserId": 12345,
"name": "Q1 2025 Campaign",
"flightDates": {
"startDate": "2025-01-15T00:00:00Z",
"endDate": "2025-03-31T23:59:59Z"
},
"budget": {
"total": 1,
"currency": "<string>",
"dailyCap": 1
},
"mode": "discovery"
}
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({
advertiserId: 12345,
name: 'Q1 2025 Campaign',
flightDates: {startDate: '2025-01-15T00:00:00Z', endDate: '2025-03-31T23:59:59Z'},
budget: {total: 1, currency: '<string>', dailyCap: 1},
mode: 'discovery'
})
};
fetch('https://api.interchange.io/api/v2/buyer/campaigns', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"campaign": {
"campaignId": "cmp_987654321",
"advertiserId": "12345",
"name": "Summer 2025 Campaign",
"status": "DRAFT",
"mode": "discovery",
"management": "tracked",
"optimizationApplyMode": "AUTO",
"createdAt": "2025-01-15T10:30:00Z",
"updatedAt": "2025-01-20T14:45:00Z",
"revision": 1,
"archivedAt": "2023-11-07T05:31:56Z",
"directed": {
"provenance": "connected_account",
"connectionId": "conn_abc123",
"accountId": "act_998877",
"provider": "tiktok",
"upstreamMediaBuyId": "tt_campaign_44521",
"subscribed": true,
"mirrorState": "live",
"storefrontId": 42,
"mediaBuyId": "<string>",
"lastSyncedAt": "2023-11-07T05:31:56Z"
},
"mediaBuyRefs": [
{
"mediaBuyId": "mb_ETBn4gJ9Wu",
"status": "ACTIVE",
"channelGroup": {
"channelGroupId": "<string>",
"name": "<string>"
},
"pendingAt": "storefront",
"pendingChange": {
"status": "PENDING_APPROVAL",
"pendingAt": "storefront"
}
}
],
"brief": "<string>",
"flightDates": {
"startDate": "2025-01-15T00:00:00Z",
"endDate": "2025-03-31T23:59:59Z"
},
"budget": {
"total": 1,
"currency": "USD",
"dailyCap": 1,
"pacing": "EVEN"
},
"allocatedBudget": 7500,
"unallocatedBudget": 2500,
"pacingPeriods": {
"mode": "weight",
"periods": [
{
"label": "<string>",
"start": "<string>",
"end": "<string>",
"weight": 5,
"budget": 1
}
]
},
"constraints": {
"geo_countries": [
"<string>"
],
"geo_countries_exclude": [
"<string>"
],
"geo_regions": [
"<string>"
],
"geo_regions_exclude": [
"<string>"
],
"geo_metros": [
{
"system": "nielsen_dma",
"values": [
"<string>"
]
}
],
"geo_metros_exclude": [
{
"system": "nielsen_dma",
"values": [
"<string>"
]
}
],
"geo_postal_areas": [
{
"country": "US",
"system": "zip",
"values": [
"<string>"
]
}
],
"geo_postal_areas_exclude": [
{
"country": "US",
"system": "zip",
"values": [
"<string>"
]
}
],
"language": [
"<string>"
],
"device_platform": [
"ios"
],
"device_type": [
"desktop"
],
"device_type_exclude": [
"desktop"
],
"channels": [
"<string>"
],
"countries": [
"<string>"
],
"geo_metro_names": [
{
"system": "<string>",
"values": [
{
"code": "<string>",
"name": "<string>"
}
]
}
],
"geo_metro_names_exclude": [
{
"system": "<string>",
"values": [
{
"code": "<string>",
"name": "<string>"
}
]
}
]
},
"storefronts": [
{
"id": 42,
"platformId": "acme-media",
"name": "Acme Media"
}
],
"performanceConfig": {
"optimizationGoals": [
{
"kind": "event",
"eventSources": [
{
"eventSourceId": "website_pixel",
"eventType": "page_view",
"customEventName": "<string>",
"valueField": "value",
"valueFactor": 1
}
],
"target": {
"kind": "cost_per",
"value": 25
},
"attributionWindow": {
"postClick": {
"interval": 7,
"unit": "days"
},
"postView": {
"interval": 1,
"unit": "days"
}
},
"priority": 1
}
]
},
"autonomy": {
"inventorySelection": "manual",
"rebriefing": "manual"
},
"catalogId": 42,
"discoveryId": "session_abc123",
"productCount": 15,
"products": [
{
"productId": "prod_123"
}
],
"audiences": [
{
"audienceId": "aud_123",
"name": "Tech Enthusiasts 25-34",
"status": "READY",
"type": "TARGET",
"enabledAt": "2025-03-01T12:00:00Z"
}
],
"creativeFormats": {
"required": [
{
"format_kind": "<string>"
}
],
"covered": [
{
"format_kind": "<string>"
}
],
"missing": [
{
"format_kind": "<string>"
}
]
},
"propertyLists": {
"propertyLists": [
{
"listId": "<string>",
"name": "<string>",
"purpose": "include",
"propertyCount": 4503599627370495,
"createdAt": "<string>",
"updatedAt": "<string>",
"viaMediaBuys": [
{
"mediaBuyId": "<string>",
"packageIds": [
"<string>"
]
}
]
}
],
"summary": {
"totalLists": 4503599627370495,
"includeCount": 4503599627370495,
"excludeCount": 4503599627370495
}
},
"mediaBuys": [
{
"mediaBuyId": "<string>",
"name": "<string>",
"status": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"channelGroup": {
"channelGroupId": "<string>",
"name": "<string>"
},
"revision": 4503599627370495,
"validActions": [
"<string>"
],
"pendingAt": "storefront",
"pendingReason": "forward_failed_needs_correction",
"pendingSince": "2023-11-07T05:31:56Z",
"errorCode": "product_no_longer_available",
"errorOwner": "buyer_input",
"sourceMessage": "<string>",
"forwardedAt": "2023-11-07T05:31:56Z",
"buyerReference": "sf:42:sf_mb_1783031864469_8pbc8mmr",
"startTime": "2025-04-14T00:00:00Z",
"endTime": "2025-04-30T23:59:59Z",
"budget_denomination": "gross",
"budget_breakdown": {
"media_budget": 123,
"fee_amount": 123,
"fee_rate_percent": 123,
"effective_gross_cpm": 123
},
"products": [
{
"productId": "<string>",
"productName": "<string>",
"publisherName": "<string>",
"salesAgentName": "<string>",
"buyerRef": "<string>",
"budget": 123,
"budgetCurrency": "<string>",
"formatOptions": [
{
"format_kind": "image",
"params": {
"width": 4503599627370496,
"height": 4503599627370496,
"sizes": [
{
"width": 4503599627370496,
"height": 4503599627370496
}
],
"min_width": 4503599627370496,
"max_width": 4503599627370496,
"min_height": 4503599627370496,
"max_height": 4503599627370496,
"duration_ms_exact": 4503599627370496,
"duration_ms_range": [
123
]
},
"format_option_id": "<string>"
}
]
}
],
"pacingPeriods": {
"mode": "weight",
"periods": [
{
"label": "<string>",
"start": "<string>",
"end": "<string>",
"weight": 5,
"budget": 1
}
]
},
"packages": [
{
"packageId": "<string>",
"status": "<string>",
"productIds": [
"<string>"
],
"budget": 123,
"budgetCurrency": "<string>",
"pacing": "<string>",
"bidPrice": 123,
"startTime": "<string>",
"endTime": "<string>",
"targetingOverlay": {
"geo_countries": [
"<string>"
],
"geo_countries_exclude": [
"<string>"
],
"geo_regions": [
"<string>"
],
"geo_regions_exclude": [
"<string>"
],
"geo_metros": [
{
"system": "nielsen_dma",
"values": [
"<string>"
]
}
],
"geo_metros_exclude": [
{
"system": "nielsen_dma",
"values": [
"<string>"
]
}
],
"geo_postal_areas": [
{
"country": "US",
"system": "zip",
"values": [
"<string>"
]
}
],
"geo_postal_areas_exclude": [
{
"country": "US",
"system": "zip",
"values": [
"<string>"
]
}
],
"daypart_targets": [
{
"days": [
"monday"
],
"start_hour": 11,
"end_hour": 12,
"timezone": "inventory_local",
"label": "<string>"
}
],
"axe_include_segment": "<string>",
"axe_exclude_segment": "<string>",
"audience_include": [
"<string>"
],
"audience_exclude": [
"<string>"
],
"signal_targeting_groups": {
"operator": "all",
"groups": [
{
"operator": "any",
"signals": [
{
"pricing_option_id": "<string>",
"signal_agent_segment_id": "<string>",
"activation_key": {}
}
]
}
]
},
"signal_targeting": [
"<unknown>"
],
"demographics": {
"age": {
"min": 75,
"include_unknown": true,
"max": 75,
"accepted_bases": [
"verified"
],
"accepted_verification_methods": [
"facial_age_estimation"
]
}
},
"frequency_cap": {
"suppress": {
"interval": 4503599627370496,
"unit": "seconds"
},
"suppress_minutes": 1,
"max_impressions": 4503599627370496,
"per": "individuals",
"window": {
"interval": 4503599627370496,
"unit": "seconds"
}
},
"property_list": {
"agent_url": "<string>",
"list_id": "<string>",
"auth_token": "<string>"
},
"property_list_exclude": {
"agent_url": "<string>",
"list_id": "<string>",
"auth_token": "<string>"
},
"collection_list": {
"agent_url": "<string>",
"list_id": "<string>",
"auth_token": "<string>"
},
"collection_list_exclude": {
"agent_url": "<string>",
"list_id": "<string>",
"auth_token": "<string>"
},
"placement_selection": {},
"collection_selection": {},
"age_restriction": {
"min": 56,
"verification_required": false,
"accepted_methods": [
"facial_age_estimation"
]
},
"device_platform": [
"ios"
],
"device_platform_exclude": [
"ios"
],
"device_type": [
"desktop"
],
"device_type_exclude": [
"desktop"
],
"browser": [
"chrome"
],
"browser_exclude": [
"chrome"
],
"store_catchments": [
{
"catalog_id": "<string>",
"store_ids": [
"<string>"
],
"catchment_ids": [
"<string>"
]
}
],
"geo_proximity": [
{
"lat": 0,
"lng": 0,
"label": "<string>",
"travel_time": {
"value": 2,
"unit": "min"
},
"transport_mode": "walking",
"radius": {
"value": 1,
"unit": "km"
},
"geometry": {
"type": "Polygon",
"coordinates": [
"<unknown>"
]
},
"ext": {}
}
],
"language": [
"<string>"
],
"keyword_targets": [
{
"keyword": "<string>",
"match_type": "broad",
"bid_price": 1
}
],
"negative_keywords": [
{
"keyword": "<string>",
"match_type": "broad"
}
]
},
"providerTargeting": {
"countries": [
"<string>"
],
"regions": [
"<string>"
],
"cities": [
"<string>"
],
"zips": [
"<string>"
],
"age_min": 39,
"age_max": 39,
"genders": [
"FEMALE"
],
"audience_include": [
"<string>"
],
"audience_exclude": [
"<string>"
],
"audience_expansion_enabled": true,
"publisher_platforms": [
"facebook"
],
"facebook_positions": [
"facebook_reels"
],
"instagram_positions": [
"reels"
],
"messenger_positions": [
"<unknown>"
],
"threads_positions": [
"<unknown>"
],
"device_platforms": [
"mobile"
],
"instream_video_skippable_excluded": false
},
"providerPlacementControls": {
"placement_soft_opt_out": {}
},
"requestedTargeting": {
"countries": [
"<string>"
],
"regions": [
"<string>"
],
"cities": [
"<string>"
],
"zips": [
"<string>"
],
"age_min": 39,
"age_max": 39,
"genders": [
"FEMALE"
],
"audience_include": [
"<string>"
],
"audience_exclude": [
"<string>"
],
"audience_expansion_enabled": true,
"publisher_platforms": [
"facebook"
],
"facebook_positions": [
"facebook_reels"
],
"instagram_positions": [
"reels"
],
"messenger_positions": [
"<unknown>"
],
"threads_positions": [
"<unknown>"
],
"device_platforms": [
"mobile"
],
"instream_video_skippable_excluded": false
},
"targetingMatchesRequest": true,
"geoRegionMappings": [
{
"iso_code": "<string>",
"provider_key": "<string>"
}
],
"geoCityMappings": [
{
"country": "<string>",
"name": "<string>",
"provider_key": "<string>",
"canonical_id": "<string>",
"system": "<string>",
"system_version": "<string>",
"provider_country": "<string>",
"provider_name": "<string>",
"provider_canonical_id": "<string>"
}
],
"delivery": {
"impressions": 123,
"spend": 123,
"clicks": 123
},
"creatives": [
{
"creativeId": "<string>",
"name": "<string>",
"formatId": {
"id": "<string>",
"agent_url": "<string>"
},
"status": "<string>",
"sourceSyncStatus": [
{
"agentId": "<string>",
"sourceId": "<string>",
"approvalStatus": "<string>",
"rejectionReason": "<string>"
}
],
"storefrontReviewStatus": "pending"
}
]
}
],
"optimizationGoals": [
{
"kind": "metric",
"metric": "clicks",
"reach_unit": "individuals",
"target_frequency": {},
"view_duration_seconds": 123,
"target": {
"kind": "cost_per",
"value": 123
},
"priority": 123
}
],
"performance": {
"impressions": 123,
"spend": 123,
"clicks": 123,
"views": 123,
"completedViews": 123,
"conversions": 123,
"leads": 123,
"lastUpdated": "2023-11-07T05:31:56Z",
"windowStart": "2023-12-25",
"windowEnd": "2023-12-25"
},
"creatives": [
{
"creativeId": "<string>",
"name": "<string>",
"formatId": {
"id": "<string>",
"agent_url": "<string>"
},
"status": "<string>",
"sourceSyncStatus": [
{
"agentId": "<string>",
"sourceId": "<string>",
"approvalStatus": "<string>",
"rejectionReason": "<string>"
}
],
"storefrontReviewStatus": "pending"
}
]
}
],
"dataDelivery": {
"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>"
}
],
"utmConfig": [
{
"paramKey": "utm_campaign",
"paramValue": "{CAMPAIGN_ID}",
"source": "advertiser"
}
]
},
"warnings": [
"<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": {}
}
}Campaigns
Create campaign
Create a new campaign. Optional fields like discoveryId and performanceConfig can be provided at creation or set later via update. The brief and name fields are screened by the content-moderation engine and rejected with 422 CONTENT_MODERATION_BLOCKED on policy violation.
POST
/
campaigns
Create campaign
curl --request POST \
--url https://api.interchange.io/api/v2/buyer/campaigns \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"advertiserId": 12345,
"name": "Q1 2025 Campaign",
"flightDates": {
"startDate": "2025-01-15T00:00:00Z",
"endDate": "2025-03-31T23:59:59Z"
},
"budget": {
"total": 1,
"currency": "<string>",
"dailyCap": 1
},
"mode": "discovery"
}
'import requests
url = "https://api.interchange.io/api/v2/buyer/campaigns"
payload = {
"advertiserId": 12345,
"name": "Q1 2025 Campaign",
"flightDates": {
"startDate": "2025-01-15T00:00:00Z",
"endDate": "2025-03-31T23:59:59Z"
},
"budget": {
"total": 1,
"currency": "<string>",
"dailyCap": 1
},
"mode": "discovery"
}
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({
advertiserId: 12345,
name: 'Q1 2025 Campaign',
flightDates: {startDate: '2025-01-15T00:00:00Z', endDate: '2025-03-31T23:59:59Z'},
budget: {total: 1, currency: '<string>', dailyCap: 1},
mode: 'discovery'
})
};
fetch('https://api.interchange.io/api/v2/buyer/campaigns', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));{
"campaign": {
"campaignId": "cmp_987654321",
"advertiserId": "12345",
"name": "Summer 2025 Campaign",
"status": "DRAFT",
"mode": "discovery",
"management": "tracked",
"optimizationApplyMode": "AUTO",
"createdAt": "2025-01-15T10:30:00Z",
"updatedAt": "2025-01-20T14:45:00Z",
"revision": 1,
"archivedAt": "2023-11-07T05:31:56Z",
"directed": {
"provenance": "connected_account",
"connectionId": "conn_abc123",
"accountId": "act_998877",
"provider": "tiktok",
"upstreamMediaBuyId": "tt_campaign_44521",
"subscribed": true,
"mirrorState": "live",
"storefrontId": 42,
"mediaBuyId": "<string>",
"lastSyncedAt": "2023-11-07T05:31:56Z"
},
"mediaBuyRefs": [
{
"mediaBuyId": "mb_ETBn4gJ9Wu",
"status": "ACTIVE",
"channelGroup": {
"channelGroupId": "<string>",
"name": "<string>"
},
"pendingAt": "storefront",
"pendingChange": {
"status": "PENDING_APPROVAL",
"pendingAt": "storefront"
}
}
],
"brief": "<string>",
"flightDates": {
"startDate": "2025-01-15T00:00:00Z",
"endDate": "2025-03-31T23:59:59Z"
},
"budget": {
"total": 1,
"currency": "USD",
"dailyCap": 1,
"pacing": "EVEN"
},
"allocatedBudget": 7500,
"unallocatedBudget": 2500,
"pacingPeriods": {
"mode": "weight",
"periods": [
{
"label": "<string>",
"start": "<string>",
"end": "<string>",
"weight": 5,
"budget": 1
}
]
},
"constraints": {
"geo_countries": [
"<string>"
],
"geo_countries_exclude": [
"<string>"
],
"geo_regions": [
"<string>"
],
"geo_regions_exclude": [
"<string>"
],
"geo_metros": [
{
"system": "nielsen_dma",
"values": [
"<string>"
]
}
],
"geo_metros_exclude": [
{
"system": "nielsen_dma",
"values": [
"<string>"
]
}
],
"geo_postal_areas": [
{
"country": "US",
"system": "zip",
"values": [
"<string>"
]
}
],
"geo_postal_areas_exclude": [
{
"country": "US",
"system": "zip",
"values": [
"<string>"
]
}
],
"language": [
"<string>"
],
"device_platform": [
"ios"
],
"device_type": [
"desktop"
],
"device_type_exclude": [
"desktop"
],
"channels": [
"<string>"
],
"countries": [
"<string>"
],
"geo_metro_names": [
{
"system": "<string>",
"values": [
{
"code": "<string>",
"name": "<string>"
}
]
}
],
"geo_metro_names_exclude": [
{
"system": "<string>",
"values": [
{
"code": "<string>",
"name": "<string>"
}
]
}
]
},
"storefronts": [
{
"id": 42,
"platformId": "acme-media",
"name": "Acme Media"
}
],
"performanceConfig": {
"optimizationGoals": [
{
"kind": "event",
"eventSources": [
{
"eventSourceId": "website_pixel",
"eventType": "page_view",
"customEventName": "<string>",
"valueField": "value",
"valueFactor": 1
}
],
"target": {
"kind": "cost_per",
"value": 25
},
"attributionWindow": {
"postClick": {
"interval": 7,
"unit": "days"
},
"postView": {
"interval": 1,
"unit": "days"
}
},
"priority": 1
}
]
},
"autonomy": {
"inventorySelection": "manual",
"rebriefing": "manual"
},
"catalogId": 42,
"discoveryId": "session_abc123",
"productCount": 15,
"products": [
{
"productId": "prod_123"
}
],
"audiences": [
{
"audienceId": "aud_123",
"name": "Tech Enthusiasts 25-34",
"status": "READY",
"type": "TARGET",
"enabledAt": "2025-03-01T12:00:00Z"
}
],
"creativeFormats": {
"required": [
{
"format_kind": "<string>"
}
],
"covered": [
{
"format_kind": "<string>"
}
],
"missing": [
{
"format_kind": "<string>"
}
]
},
"propertyLists": {
"propertyLists": [
{
"listId": "<string>",
"name": "<string>",
"purpose": "include",
"propertyCount": 4503599627370495,
"createdAt": "<string>",
"updatedAt": "<string>",
"viaMediaBuys": [
{
"mediaBuyId": "<string>",
"packageIds": [
"<string>"
]
}
]
}
],
"summary": {
"totalLists": 4503599627370495,
"includeCount": 4503599627370495,
"excludeCount": 4503599627370495
}
},
"mediaBuys": [
{
"mediaBuyId": "<string>",
"name": "<string>",
"status": "<string>",
"createdAt": "2023-11-07T05:31:56Z",
"updatedAt": "2023-11-07T05:31:56Z",
"channelGroup": {
"channelGroupId": "<string>",
"name": "<string>"
},
"revision": 4503599627370495,
"validActions": [
"<string>"
],
"pendingAt": "storefront",
"pendingReason": "forward_failed_needs_correction",
"pendingSince": "2023-11-07T05:31:56Z",
"errorCode": "product_no_longer_available",
"errorOwner": "buyer_input",
"sourceMessage": "<string>",
"forwardedAt": "2023-11-07T05:31:56Z",
"buyerReference": "sf:42:sf_mb_1783031864469_8pbc8mmr",
"startTime": "2025-04-14T00:00:00Z",
"endTime": "2025-04-30T23:59:59Z",
"budget_denomination": "gross",
"budget_breakdown": {
"media_budget": 123,
"fee_amount": 123,
"fee_rate_percent": 123,
"effective_gross_cpm": 123
},
"products": [
{
"productId": "<string>",
"productName": "<string>",
"publisherName": "<string>",
"salesAgentName": "<string>",
"buyerRef": "<string>",
"budget": 123,
"budgetCurrency": "<string>",
"formatOptions": [
{
"format_kind": "image",
"params": {
"width": 4503599627370496,
"height": 4503599627370496,
"sizes": [
{
"width": 4503599627370496,
"height": 4503599627370496
}
],
"min_width": 4503599627370496,
"max_width": 4503599627370496,
"min_height": 4503599627370496,
"max_height": 4503599627370496,
"duration_ms_exact": 4503599627370496,
"duration_ms_range": [
123
]
},
"format_option_id": "<string>"
}
]
}
],
"pacingPeriods": {
"mode": "weight",
"periods": [
{
"label": "<string>",
"start": "<string>",
"end": "<string>",
"weight": 5,
"budget": 1
}
]
},
"packages": [
{
"packageId": "<string>",
"status": "<string>",
"productIds": [
"<string>"
],
"budget": 123,
"budgetCurrency": "<string>",
"pacing": "<string>",
"bidPrice": 123,
"startTime": "<string>",
"endTime": "<string>",
"targetingOverlay": {
"geo_countries": [
"<string>"
],
"geo_countries_exclude": [
"<string>"
],
"geo_regions": [
"<string>"
],
"geo_regions_exclude": [
"<string>"
],
"geo_metros": [
{
"system": "nielsen_dma",
"values": [
"<string>"
]
}
],
"geo_metros_exclude": [
{
"system": "nielsen_dma",
"values": [
"<string>"
]
}
],
"geo_postal_areas": [
{
"country": "US",
"system": "zip",
"values": [
"<string>"
]
}
],
"geo_postal_areas_exclude": [
{
"country": "US",
"system": "zip",
"values": [
"<string>"
]
}
],
"daypart_targets": [
{
"days": [
"monday"
],
"start_hour": 11,
"end_hour": 12,
"timezone": "inventory_local",
"label": "<string>"
}
],
"axe_include_segment": "<string>",
"axe_exclude_segment": "<string>",
"audience_include": [
"<string>"
],
"audience_exclude": [
"<string>"
],
"signal_targeting_groups": {
"operator": "all",
"groups": [
{
"operator": "any",
"signals": [
{
"pricing_option_id": "<string>",
"signal_agent_segment_id": "<string>",
"activation_key": {}
}
]
}
]
},
"signal_targeting": [
"<unknown>"
],
"demographics": {
"age": {
"min": 75,
"include_unknown": true,
"max": 75,
"accepted_bases": [
"verified"
],
"accepted_verification_methods": [
"facial_age_estimation"
]
}
},
"frequency_cap": {
"suppress": {
"interval": 4503599627370496,
"unit": "seconds"
},
"suppress_minutes": 1,
"max_impressions": 4503599627370496,
"per": "individuals",
"window": {
"interval": 4503599627370496,
"unit": "seconds"
}
},
"property_list": {
"agent_url": "<string>",
"list_id": "<string>",
"auth_token": "<string>"
},
"property_list_exclude": {
"agent_url": "<string>",
"list_id": "<string>",
"auth_token": "<string>"
},
"collection_list": {
"agent_url": "<string>",
"list_id": "<string>",
"auth_token": "<string>"
},
"collection_list_exclude": {
"agent_url": "<string>",
"list_id": "<string>",
"auth_token": "<string>"
},
"placement_selection": {},
"collection_selection": {},
"age_restriction": {
"min": 56,
"verification_required": false,
"accepted_methods": [
"facial_age_estimation"
]
},
"device_platform": [
"ios"
],
"device_platform_exclude": [
"ios"
],
"device_type": [
"desktop"
],
"device_type_exclude": [
"desktop"
],
"browser": [
"chrome"
],
"browser_exclude": [
"chrome"
],
"store_catchments": [
{
"catalog_id": "<string>",
"store_ids": [
"<string>"
],
"catchment_ids": [
"<string>"
]
}
],
"geo_proximity": [
{
"lat": 0,
"lng": 0,
"label": "<string>",
"travel_time": {
"value": 2,
"unit": "min"
},
"transport_mode": "walking",
"radius": {
"value": 1,
"unit": "km"
},
"geometry": {
"type": "Polygon",
"coordinates": [
"<unknown>"
]
},
"ext": {}
}
],
"language": [
"<string>"
],
"keyword_targets": [
{
"keyword": "<string>",
"match_type": "broad",
"bid_price": 1
}
],
"negative_keywords": [
{
"keyword": "<string>",
"match_type": "broad"
}
]
},
"providerTargeting": {
"countries": [
"<string>"
],
"regions": [
"<string>"
],
"cities": [
"<string>"
],
"zips": [
"<string>"
],
"age_min": 39,
"age_max": 39,
"genders": [
"FEMALE"
],
"audience_include": [
"<string>"
],
"audience_exclude": [
"<string>"
],
"audience_expansion_enabled": true,
"publisher_platforms": [
"facebook"
],
"facebook_positions": [
"facebook_reels"
],
"instagram_positions": [
"reels"
],
"messenger_positions": [
"<unknown>"
],
"threads_positions": [
"<unknown>"
],
"device_platforms": [
"mobile"
],
"instream_video_skippable_excluded": false
},
"providerPlacementControls": {
"placement_soft_opt_out": {}
},
"requestedTargeting": {
"countries": [
"<string>"
],
"regions": [
"<string>"
],
"cities": [
"<string>"
],
"zips": [
"<string>"
],
"age_min": 39,
"age_max": 39,
"genders": [
"FEMALE"
],
"audience_include": [
"<string>"
],
"audience_exclude": [
"<string>"
],
"audience_expansion_enabled": true,
"publisher_platforms": [
"facebook"
],
"facebook_positions": [
"facebook_reels"
],
"instagram_positions": [
"reels"
],
"messenger_positions": [
"<unknown>"
],
"threads_positions": [
"<unknown>"
],
"device_platforms": [
"mobile"
],
"instream_video_skippable_excluded": false
},
"targetingMatchesRequest": true,
"geoRegionMappings": [
{
"iso_code": "<string>",
"provider_key": "<string>"
}
],
"geoCityMappings": [
{
"country": "<string>",
"name": "<string>",
"provider_key": "<string>",
"canonical_id": "<string>",
"system": "<string>",
"system_version": "<string>",
"provider_country": "<string>",
"provider_name": "<string>",
"provider_canonical_id": "<string>"
}
],
"delivery": {
"impressions": 123,
"spend": 123,
"clicks": 123
},
"creatives": [
{
"creativeId": "<string>",
"name": "<string>",
"formatId": {
"id": "<string>",
"agent_url": "<string>"
},
"status": "<string>",
"sourceSyncStatus": [
{
"agentId": "<string>",
"sourceId": "<string>",
"approvalStatus": "<string>",
"rejectionReason": "<string>"
}
],
"storefrontReviewStatus": "pending"
}
]
}
],
"optimizationGoals": [
{
"kind": "metric",
"metric": "clicks",
"reach_unit": "individuals",
"target_frequency": {},
"view_duration_seconds": 123,
"target": {
"kind": "cost_per",
"value": 123
},
"priority": 123
}
],
"performance": {
"impressions": 123,
"spend": 123,
"clicks": 123,
"views": 123,
"completedViews": 123,
"conversions": 123,
"leads": 123,
"lastUpdated": "2023-11-07T05:31:56Z",
"windowStart": "2023-12-25",
"windowEnd": "2023-12-25"
},
"creatives": [
{
"creativeId": "<string>",
"name": "<string>",
"formatId": {
"id": "<string>",
"agent_url": "<string>"
},
"status": "<string>",
"sourceSyncStatus": [
{
"agentId": "<string>",
"sourceId": "<string>",
"approvalStatus": "<string>",
"rejectionReason": "<string>"
}
],
"storefrontReviewStatus": "pending"
}
]
}
],
"dataDelivery": {
"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>"
}
],
"utmConfig": [
{
"paramKey": "utm_campaign",
"paramValue": "{CAMPAIGN_ID}",
"source": "advertiser"
}
]
},
"warnings": [
"<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": {}
}
}Authorizations
API key or access token
Body
application/json
- Option 1
- Option 2
Request body for creating a discovery-mode campaign
Advertiser ID that will own this campaign
Required range:
0 < x <= 9007199254740991Example:
12345
Name of the campaign
Required string length:
1 - 255Example:
"Q1 2025 Campaign"
Campaign flight dates
Show child attributes
Show child attributes
Campaign budget configuration
Show child attributes
Show child attributes
"I have a brief; find it for me" — platform-managed. Optimization goals (performanceConfig) are allowed on any mode; they are hints, not a composition-ownership declaration.
Available options:
discovery Natural language brief for product search context
Maximum string length:
5000Example:
"Looking for premium video inventory targeting tech enthusiasts"
Campaign targeting constraints
Show child attributes
Show child attributes
Canonical buyer-declared inventory execution and reporting boundaries. REST clients send the fully expanded saved shape; /mcp/v3 save_campaign also accepts preset shorthand.
Required array length:
1 - 25 elementsShow child attributes
Show child attributes
Storefront IDs the campaign is limited to. When set, every discover_products run for this campaign auto-applies this filter — buyers do not need to resend it. Pass the IDs returned by list_storefronts. Highly encouraged so the campaign only sources inventory from sellers the buyer has chosen.
Maximum array length:
50Required range:
0 < x <= 9007199254740991Example:
[42, 57]
Attach an existing discovery session to the campaign
Minimum string length:
1Example:
"abc123-def456-ghi789"
Product IDs to pre-select from the discovery session (requires discoveryId)
Example:
["prod_123", "prod_456"]
Audience targeting and suppression configuration. On create, listed audiences are attached to the campaign.
Show child attributes
Show child attributes
Performance optimization configuration
Show child attributes
Show child attributes
Controls whether Scope3 AI model optimizations to media buys are applied automatically or require manual approval. If omitted, inherits the advertiser-level setting.
Available options:
AUTO, MANUAL ID of a catalog (from the advertiser catalogs list) to attach to this campaign. Only one catalog may be attached per campaign.
Required range:
0 < x <= 9007199254740991Example:
42
Pacing schedule for the campaign. Defines time-based spend periods with varying intensity. In weight mode, budget is distributed proportionally by weighted days. In budget mode, explicit dollar amounts are set per period. Gaps between periods are treated as pauses (no spend). On execution, each product is split into one package per period with proportional budget.
Show child attributes
Show child attributes
UTM (Urchin Tracking Module) parameter configuration for this campaign. Overrides advertiser-level defaults for matching param keys.
Show child attributes
Show child attributes
Campaign-scoped data-delivery configuration. Groups Data Delivery Outputs that override advertiser-scoped delivery for the same dataDeliveryType. 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 campaign, enforced via Scope3's cross-publisher exposure tracking on TMP-connected inventory. Closed-platform integrations (e.g. TikTok, Meta, Snap, and other adapter-based publishers) cannot honor this at their own request time — to cap frequency on one of those platforms' own native ad-serving, set targetingOverlay.frequency_cap on the product instead (see add_discovery_products / create_media_buys).
Show child attributes
Show child attributes
Autonomy settings for this campaign. Controls who owns composition and brief updates. Set inventorySelection: "automatic" to let the platform optimizer pick inventory; the default is "manual".
Show child attributes
Show child attributes
Response
Create campaign
Response containing a single campaign
Campaign resource representation
Show child attributes
Show child attributes
Non-blocking advisories about the campaign. On create, includes a soft credit-limit warning when the budget already exceeds the org’s available Scope3 credit (the campaign is still created; the hard 402 gate fires at execute).