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",
"createdAt": "2025-01-15T10:30:00Z",
"updatedAt": "2025-01-20T14:45:00Z",
"revision": 1,
"directed": {
"provenance": "connected_account",
"connectionId": "conn_abc123",
"accountId": "act_998877",
"provider": "tiktok",
"upstreamMediaBuyId": "tt_campaign_44521",
"subscribed": true,
"storefrontId": 42,
"mediaBuyId": "<string>",
"lastSyncedAt": "2023-11-07T05:31:56Z"
},
"mediaBuyRefs": [
{
"mediaBuyId": "mb_ETBn4gJ9Wu",
"status": "ACTIVE",
"pendingChange": {
"status": "PENDING_APPROVAL"
}
}
],
"brief": "<string>",
"flightDates": {
"startDate": "2025-01-15T00:00:00Z",
"endDate": "2025-03-31T23:59:59Z"
},
"budget": {
"total": 1,
"currency": "USD",
"dailyCap": 1
},
"allocatedBudget": 7500,
"unallocatedBudget": 2500,
"pacingPeriods": {
"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": "<string>",
"system": "postal_code",
"values": [
"<string>"
]
}
],
"geo_postal_areas_exclude": [
{
"country": "<string>",
"system": "postal_code",
"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",
"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
}
]
},
"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>",
"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",
"revision": 4503599627370495,
"validActions": [
"<string>"
],
"pendingSince": "2023-11-07T05:31:56Z",
"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>",
"budget": 123,
"budgetCurrency": "<string>",
"formatOptions": [
{
"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": {
"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": "<string>",
"system": "postal_code",
"values": [
"<string>"
]
}
],
"geo_postal_areas_exclude": [
{
"country": "<string>",
"system": "postal_code",
"values": [
"<string>"
]
}
],
"daypart_targets": [
{
"days": [
"monday"
],
"start_hour": 11.5,
"end_hour": 12.5,
"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": {
"type": "segment_id",
"segment_id": "<string>"
}
}
]
}
]
},
"signal_targeting": [
{
"value_type": "binary",
"value": true,
"signal_ref": {
"scope": "product",
"signal_id": "<string>"
},
"signal_id": {
"source": "catalog",
"data_provider_domain": "<string>",
"id": "<string>"
}
}
],
"frequency_cap": {
"suppress": {
"interval": 2,
"unit": "seconds"
},
"suppress_minutes": 1,
"max_impressions": 2,
"per": "individuals",
"window": {
"interval": 2,
"unit": "seconds"
}
},
"property_list": {
"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>"
},
"age_restriction": {
"min": 56,
"verification_required": true,
"accepted_methods": [
"facial_age_estimation"
]
},
"device_platform": [
"ios"
],
"device_type": [
"desktop"
],
"device_type_exclude": [
"desktop"
],
"store_catchments": [
{
"catalog_id": "<string>",
"store_ids": [
"<string>"
],
"catchment_ids": [
"<string>"
]
}
],
"geo_proximity": [
{
"lat": 0,
"lng": 0,
"travel_time": {
"value": 2,
"unit": "min"
},
"transport_mode": "walking",
"label": "<string>",
"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": [],
"publisher_platforms": [],
"facebook_positions": [],
"instagram_positions": [],
"threads_positions": [
"threads_stream"
],
"instream_video_skippable_excluded": true
},
"providerPlacementControls": {
"placement_soft_opt_out": {}
},
"requestedTargeting": {
"countries": [
"<string>"
],
"regions": [
"<string>"
],
"cities": [
"<string>"
],
"zips": [
"<string>"
],
"age_min": 39,
"age_max": 39,
"genders": [],
"publisher_platforms": [],
"facebook_positions": [],
"instagram_positions": [],
"threads_positions": [
"threads_stream"
],
"instream_video_skippable_excluded": true
},
"targetingMatchesRequest": true,
"geoRegionMappings": [
{
"iso_code": "<string>",
"provider_key": "<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>"
}
]
}
]
}
],
"optimizationGoals": [
{
"kind": "metric",
"metric": "clicks",
"reach_unit": "individuals",
"target_frequency": {
"window": {
"interval": 2,
"unit": "seconds"
},
"min": 2,
"max": 2
},
"view_duration_seconds": 123,
"target": {
"kind": "cost_per",
"value": 123
},
"priority": 2
}
],
"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>"
}
]
}
]
}
],
"dataDelivery": {
"outputs": [
{
"outputConfigId": "<string>",
"enabled": true,
"credentialId": "<string>",
"credentialName": "<string>",
"deliveryConfig": {
"type": "GCS",
"pathPrefix": "",
"format": "JSONL"
},
"createdAt": "<string>",
"updatedAt": "<string>",
"syncWeeklyDay": 3
}
]
},
"frequencyCaps": [
{
"max_impressions": 3,
"window": {
"interval": 2,
"unit": "seconds"
},
"id": "12345",
"targetId": "camp_abc123",
"createdAt": "<string>",
"updatedAt": "<string>",
"archivedAt": "<string>"
}
]
},
"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": {}
}
}{
"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",
"createdAt": "2025-01-15T10:30:00Z",
"updatedAt": "2025-01-20T14:45:00Z",
"revision": 1,
"directed": {
"provenance": "connected_account",
"connectionId": "conn_abc123",
"accountId": "act_998877",
"provider": "tiktok",
"upstreamMediaBuyId": "tt_campaign_44521",
"subscribed": true,
"storefrontId": 42,
"mediaBuyId": "<string>",
"lastSyncedAt": "2023-11-07T05:31:56Z"
},
"mediaBuyRefs": [
{
"mediaBuyId": "mb_ETBn4gJ9Wu",
"status": "ACTIVE",
"pendingChange": {
"status": "PENDING_APPROVAL"
}
}
],
"brief": "<string>",
"flightDates": {
"startDate": "2025-01-15T00:00:00Z",
"endDate": "2025-03-31T23:59:59Z"
},
"budget": {
"total": 1,
"currency": "USD",
"dailyCap": 1
},
"allocatedBudget": 7500,
"unallocatedBudget": 2500,
"pacingPeriods": {
"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": "<string>",
"system": "postal_code",
"values": [
"<string>"
]
}
],
"geo_postal_areas_exclude": [
{
"country": "<string>",
"system": "postal_code",
"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",
"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
}
]
},
"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>",
"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",
"revision": 4503599627370495,
"validActions": [
"<string>"
],
"pendingSince": "2023-11-07T05:31:56Z",
"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>",
"budget": 123,
"budgetCurrency": "<string>",
"formatOptions": [
{
"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": {
"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": "<string>",
"system": "postal_code",
"values": [
"<string>"
]
}
],
"geo_postal_areas_exclude": [
{
"country": "<string>",
"system": "postal_code",
"values": [
"<string>"
]
}
],
"daypart_targets": [
{
"days": [
"monday"
],
"start_hour": 11.5,
"end_hour": 12.5,
"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": {
"type": "segment_id",
"segment_id": "<string>"
}
}
]
}
]
},
"signal_targeting": [
{
"value_type": "binary",
"value": true,
"signal_ref": {
"scope": "product",
"signal_id": "<string>"
},
"signal_id": {
"source": "catalog",
"data_provider_domain": "<string>",
"id": "<string>"
}
}
],
"frequency_cap": {
"suppress": {
"interval": 2,
"unit": "seconds"
},
"suppress_minutes": 1,
"max_impressions": 2,
"per": "individuals",
"window": {
"interval": 2,
"unit": "seconds"
}
},
"property_list": {
"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>"
},
"age_restriction": {
"min": 56,
"verification_required": true,
"accepted_methods": [
"facial_age_estimation"
]
},
"device_platform": [
"ios"
],
"device_type": [
"desktop"
],
"device_type_exclude": [
"desktop"
],
"store_catchments": [
{
"catalog_id": "<string>",
"store_ids": [
"<string>"
],
"catchment_ids": [
"<string>"
]
}
],
"geo_proximity": [
{
"lat": 0,
"lng": 0,
"travel_time": {
"value": 2,
"unit": "min"
},
"transport_mode": "walking",
"label": "<string>",
"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": [],
"publisher_platforms": [],
"facebook_positions": [],
"instagram_positions": [],
"threads_positions": [
"threads_stream"
],
"instream_video_skippable_excluded": true
},
"providerPlacementControls": {
"placement_soft_opt_out": {}
},
"requestedTargeting": {
"countries": [
"<string>"
],
"regions": [
"<string>"
],
"cities": [
"<string>"
],
"zips": [
"<string>"
],
"age_min": 39,
"age_max": 39,
"genders": [],
"publisher_platforms": [],
"facebook_positions": [],
"instagram_positions": [],
"threads_positions": [
"threads_stream"
],
"instream_video_skippable_excluded": true
},
"targetingMatchesRequest": true,
"geoRegionMappings": [
{
"iso_code": "<string>",
"provider_key": "<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>"
}
]
}
]
}
],
"optimizationGoals": [
{
"kind": "metric",
"metric": "clicks",
"reach_unit": "individuals",
"target_frequency": {
"window": {
"interval": 2,
"unit": "seconds"
},
"min": 2,
"max": 2
},
"view_duration_seconds": 123,
"target": {
"kind": "cost_per",
"value": 123
},
"priority": 2
}
],
"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>"
}
]
}
]
}
],
"dataDelivery": {
"outputs": [
{
"outputConfigId": "<string>",
"enabled": true,
"credentialId": "<string>",
"credentialName": "<string>",
"deliveryConfig": {
"type": "GCS",
"pathPrefix": "",
"format": "JSONL"
},
"createdAt": "<string>",
"updatedAt": "<string>",
"syncWeeklyDay": 3
}
]
},
"frequencyCaps": [
{
"max_impressions": 3,
"window": {
"interval": 2,
"unit": "seconds"
},
"id": "12345",
"targetId": "camp_abc123",
"createdAt": "<string>",
"updatedAt": "<string>",
"archivedAt": "<string>"
}
]
},
"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": {}
}
}{
"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:
1 <= 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.
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
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:
1 <= 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:
1 <= 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 by Scope3 across all publishers.
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).
⌘I