Targeting
The API offers a variety of Targeting options to allow an advertiser to find the right user at the right time.
There are a variety of endpoints offered that expose the available targeting options.
Targeting Spec
The targeting spec should be constructed based on the possible dimensions outlined below.
| Attribute | Description | Required | Note |
|---|---|---|---|
| app_install_states | Defines whether targeted user has App installed or not | O | For usage see App Install states |
| demographics | List of Demographic Targets | O | Required when using Multi-country targeting |
| devices | List of Device Targets | O | |
| geos | List of Geo/Location Targets | R | Multi-country targeting is allowed from 1st April 2020, each country needs to be placed in a geos entry, a targeting spec that uses multi-country targeting needs to also include a demographics entry that incorporates a single languages entry |
| interests | List of Interest Targets | O | |
| locations | List of Location categories/Circles | O | |
| regulated_content | Flag to mark content within the Ad Squad as Regulated Content | O | FALSE (default), TRUE |
| segments | List of Customer List segment targets | O | |
| auto_expansion_options | This option allows Snapchat to expand the targeting based on a number of different factors. | O | For usage see Targeting auto-expansion |
General Guidance
In general, dimensions that are grouped within the same JSON object is in AND relation. JSON objects within a JSON array are in OR relation. The exception to this is EXCLUDE, which is always AND and applied last.
Targeting Inclusion / Exclusion
| Category | Type | Support | Description |
|---|---|---|---|
| app_install_states | app installation state | See App Install states | Defines whether targeted user has App installed or not |
| demographics | gender, languages, age_group, min_age, max_age, DLXD | INCLUDE | Gender, Language, Age Groups, Age Range, Advanced Demographics |
| devices | connection_type, os_type, os_version, carrier, marketing_name | INCLUDE | Connection type, OS Type, OS Version, Carrier, Make |
| geos | country | INCLUDE/EXCLUDE | Multi-country targeting is allowed from 1st April 2020, each country needs to be placed in a geos entry, a targeting spec that uses multi-country targeting needs to also include a demographics entry that incorporates a single languages entry |
| geos | region | INCLUDE/EXCLUDE | Region/State |
| geos | metro | INCLUDE/EXCLUDE | Metro/DMA |
| geos | postal_code | INCLUDE/EXCLUDE | Zipcode/Post code |
| interests | SLC | INCLUDE/EXCLUDE | Snap Lifestyle Categories |
| interests | DLX, DLXS, DLXC, NLN, PLC, VAC | INCLUDE | Oracle Datalogix DLX/DLXS/DLXC Interest Targeting, Nielsen Interest Targeting NLN, Placed Visitation PLC, Snap Visitation VAC |
| locations | categories_loi, circles | INCLUDE | Location Categories, Location Point Radius |
| segments | segment_id | INCLUDE/EXCLUDE | Customer List, Pixel Custom Audiences, Mobile Audiences, Engagement Audiences |
Targeting changes in Snap Ads Manager
Our targeting spec is flexible and allows targeting to be formulated in two different styles, expanded, compact or a mixture of the two.
In an effort to normalize our targeting spec Snap Ads Manager is now going to default to only define targeting in the compact style, in a change that will take place on 23 September 2025.
Both Snap Ads Manager and the Marketing API will continue to support both styles of targeting but on the 23 September 2025 Snap Ads Manager will default to save the targeting of any Ad Squad and Targeting Spec into the compact format.
Timeline - Targeting Changes
| Time | Phase | Description |
|---|---|---|
| March 2025 | Expanded targeting style is used by Snap Ads Manager | Snap Ads Manager returns targeting in the expanded style3rd parties can build to adopt the compact targeting style. Introduction of targeting_v2 parameter |
| 23 September 2025 | Compact targeting style is used by Snap Ads Manager by default | Snap Ads Manager uses the compact targeting style when Creating and Updating Ad Squads.3rd party applications risk breaking unless they are able to read, display and save targeting in the compact targeting style. |
Targeting styles - Expanded and Compact
The below example provides a definition and uses an example of the same targeting spec to explain how the different styles differ.
Targeting - Expanded
Each targeting criteria is defined in an independent node.
Example;
"targeting": {
"geos": [
{
"country_code": "US",
"region_id": ["5"],
"operation": "INCLUDE"
},
{
"country_code": "US",
"region_id": ["8"],
"operation": "INCLUDE"
}
],
"segments": [
{
"segment_id": [
"5052756160240353"
]
},
{
"segment_id": [
"6642356568874716"
]
},
{
"segment_id": [
"5029744549138135"
]
},
{
"segment_id": [
"5893433172550124"
],
"operation": "EXCLUDE"
}
]
}
Targeting - Compact
Each targeting criteria is defined in an array.
The only exception is country_code which should be defined in independent nodes, this is because country_code nodes can have geo specific factors tied to them in sub-nodes such as postal_code, region and metro.
Example;
"targeting": {
"geos": [
{
"country_code": "US",
"region_id": ["5", "8"],
"operation": "INCLUDE"
}
],
"segments": [
{
"segment_id": [
"5052756160240353",
"6642356568874716",
"5029744549138135"
],
"operation": "INCLUDE"
},
{
"segment_id": [
"5893433172550124"
],
"operation": "EXCLUDE"
}
]
}
New parameter - targeting_v2
To aid in the adoption of the compact style of defining targeting we are providing a new parameter named targeting_v2 this parameter allows you to test and develop support for the compact targeting style.
When you add this parameter to an API request for fetching an Ad Squad/Targeting Spec it will format the targeting into the compact style, even if it was saved in the expanded or mixed format.
The targeting_v2 parameter works with the following endpoints
| API Method | URL |
|---|---|
| Get a specific Ad Squad by ID | https://developers.snap.com/marketing-api/Ads-API/ad-squads#get-a-specific-ad-squad |
| Get all Ad Squads under a Campaign | https://developers.snap.com/marketing-api/Ads-API/ad-squads#get-all-ad-squads-under-a-campaign |
| Get a specific Targeting Spec by ID | https://developers.snap.com/marketing-api/Ads-API/targeting#get-a-specific-targeting-spec |
| Get all Targeting Specs under an Ad Squad | https://developers.snap.com/marketing-api/Ads-API/targeting#get-all-targeting-specs-under-an-ad-squad |
Example 1 - Expanded targeting
This request fetches an Ad Squad that uses the expanded style of targeting with interest and regional targeting.
curl "https://adsapi.snapchat.com/v1/adsquads/b145b58d-151e-4e04-b43b-6d9b351f732f?return_placement_v2=true" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "45648fe1-122e-4e34-af1b-76a0b34d80fb",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "b145b58d-151e-4e04-b43b-6d9b351f732f",
"updated_at": "2025-03-24T22:29:27.999Z",
"created_at": "2025-03-24T22:29:27.999Z",
"name": "Targeting - Interest and Region",
"status": "ACTIVE",
"campaign_id": "0f8a976d-531b-49cc-bc2e-0261026f37dc",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"min_age": "18",
"operation": "INCLUDE"
}
],
"interests": [
{
"category_id": ["SLC_1"],
"operation": "INCLUDE"
},
{
"category_id": ["SLC_124"],
"operation": "INCLUDE"
},
{
"category_id": ["SLC_2"],
"operation": "INCLUDE"
},
{
"category_id": ["SLC_155"],
"operation": "INCLUDE"
},
{
"category_id": ["SLC_241"],
"operation": "INCLUDE"
},
{
"category_id": ["SLC_242"],
"operation": "INCLUDE"
},
{
"category_id": ["SLC_243"],
"operation": "INCLUDE"
}
],
"geos": [
{
"country_code": "uk",
"region_id": ["25336"],
"operation": "INCLUDE"
},
{
"country_code": "uk",
"region_id": ["25335"],
"operation": "INCLUDE"
},
{
"country_code": "uk",
"region_id": ["25339"],
"operation": "INCLUDE"
},
{
"country_code": "uk",
"region_id": ["34999"],
"operation": "INCLUDE"
},
{
"country_code": "uk",
"region_id": ["35000"],
"operation": "INCLUDE"
}
],
"devices": [{}],
"product_audiences": [],
"enable_targeting_expansion": true,
"auto_expansion_options": {
"interest_expansion_option": {
"enabled": true
},
"custom_audience_expansion_option": {
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-09-16T11:22:31.894Z",
"optimization_goal": "SWIPES"
}
}
]
}
Example 1 - Compact targeting
This request fetches the same Ad Squad but uses the targeting_v2 parameter which returns the targeting in the compact style
curl "https://adsapi.snapchat.com/v1/adsquads/b145b58d-151e-4e04-b43b-6d9b351f732f?return_placement_v2=true&targeting_v2=ENABLED" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "d19d11ee-3fdb-476e-b9ab-63aeed42da63",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "b145b58d-151e-4e04-b43b-6d9b351f732f",
"updated_at": "2025-03-24T22:29:27.999Z",
"created_at": "2025-03-24T22:29:27.999Z",
"name": "Targeting - Interest and Region",
"status": "ACTIVE",
"campaign_id": "0f8a976d-531b-49cc-bc2e-0261026f37dc",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"min_age": "18",
"operation": "INCLUDE"
}
],
"interests": [
{
"category_id": [
"SLC_1",
"SLC_124",
"SLC_2",
"SLC_155",
"SLC_241",
"SLC_242",
"SLC_243"
],
"operation": "INCLUDE"
}
],
"geos": [
{
"country_code": "uk",
"region_id": [
"25336",
"25335",
"25339",
"34999",
"35000"
],
"operation": "INCLUDE"
}
],
"devices": [
{
"operation": "INCLUDE"
}
],
"product_audiences": [],
"enable_targeting_expansion": true,
"auto_expansion_options": {
"interest_expansion_option": {
"enabled": true
},
"custom_audience_expansion_option": {
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-09-16T11:22:31.894Z",
"optimization_goal": "SWIPES"
}
}
]
}
Example 2 - Expanded targeting
This request fetches an Ad Squad that uses the expanded style of targeting for age groups and post codes.
curl "https://adsapi.snapchat.com/v1/adsquads/7e740766-9ea0-4487-ae4d-acb04cc4246c?return_placement_v2=true" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5c3281c1-f5c7-4e32-9913-37784bfc6d07",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "7e740766-9ea0-4487-ae4d-acb04cc4246c",
"updated_at": "2025-03-24T22:08:25.487Z",
"created_at": "2025-03-24T22:08:25.487Z",
"name": "Targeting - Age Group and Postal Code",
"status": "ACTIVE",
"campaign_id": "0f8a976d-531b-49cc-bc2e-0261026f37dc",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"age_groups": ["18-20"],
"operation": "INCLUDE"
},
{
"age_groups": ["21-24"],
"operation": "INCLUDE"
},
{
"age_groups": ["25-34"],
"operation": "INCLUDE"
}
],
"geos": [
{
"country_code": "us",
"postal_code": ["20622"],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": ["20629"],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": ["20632"],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": ["20639"],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": ["20646"],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": ["20650"],
"operation": "INCLUDE"
}
],
"devices": [{}],
"product_audiences": [],
"enable_targeting_expansion": true,
"auto_expansion_options": {
"interest_expansion_option": {
"enabled": true
},
"custom_audience_expansion_option": {
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-09-16T11:22:31.894Z",
"optimization_goal": "SWIPES"
}
}
]
}
Example 2 - Compact targeting
This request fetches the same Ad Squad but uses the targeting_v2 parameter which returns the targeting in the compact style
curl "https://adsapi.snapchat.com/v1/adsquads/7e740766-9ea0-4487-ae4d-acb04cc4246c?return_placement_v2=true&targeting_v2=ENABLED" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "e2041fdd-2e31-4c5b-9a66-d8d88cf2a946",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "7e740766-9ea0-4487-ae4d-acb04cc4246c",
"updated_at": "2025-03-24T22:08:25.487Z",
"created_at": "2025-03-24T22:08:25.487Z",
"name": "Targeting - Age Group and Postal Code",
"status": "ACTIVE",
"campaign_id": "0f8a976d-531b-49cc-bc2e-0261026f37dc",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"age_groups": ["18-20", "21-24", "25-34"],
"operation": "INCLUDE"
}
],
"geos": [
{
"country_code": "us",
"postal_code": [
"20622",
"20629",
"20632",
"20639",
"20646",
"20650"
],
"operation": "INCLUDE"
}
],
"devices": [
{
"operation": "INCLUDE"
}
],
"product_audiences": [],
"enable_targeting_expansion": true,
"auto_expansion_options": {
"interest_expansion_option": {
"enabled": true
},
"custom_audience_expansion_option": {
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-09-16T11:22:31.894Z",
"optimization_goal": "SWIPES"
}
}
]
}
Example 3 - Expanded targeting
This request fetches an Ad Squad that uses the expanded style of targeting for regional targeting in the UK and Ireland.
curl "https://adsapi.snapchat.com/v1/adsquads/1d1f9dd9-9c21-43b5-a2c4-0de0a01a3e0c?return_placement_v2=true" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "2b903cc2-00fc-4bca-9117-ff54621e974d",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "1d1f9dd9-9c21-43b5-a2c4-0de0a01a3e0c",
"updated_at": "2025-03-07T22:13:26.115Z",
"created_at": "2025-03-07T22:07:34.641Z",
"name": "UK and Ireland - Region targeting",
"status": "ACTIVE",
"campaign_id": "eee90f1e-889a-43aa-84b3-14a5879d864f",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"min_age": "18",
"operation": "INCLUDE"
}
],
"geos": [
{
"country_code": "uk",
"region_id": ["25385"],
"operation": "INCLUDE"
},
{
"country_code": "uk",
"region_id": ["25382"],
"operation": "INCLUDE"
},
{
"country_code": "uk",
"region_id": ["25384"],
"operation": "INCLUDE"
},
{
"country_code": "uk",
"region_id": ["25389"],
"operation": "INCLUDE"
},
{
"country_code": "uk",
"region_id": ["25403"],
"operation": "INCLUDE"
},
{
"country_code": "uk",
"region_id": ["25401"],
"operation": "INCLUDE"
},
{
"country_code": "ie",
"region_id": ["11820"],
"operation": "INCLUDE"
},
{
"country_code": "ie",
"region_id": ["11843"],
"operation": "INCLUDE"
},
{
"country_code": "ie",
"region_id": ["28393"],
"operation": "INCLUDE"
},
{
"country_code": "ie",
"region_id": ["11825"],
"operation": "INCLUDE"
},
{
"country_code": "ie",
"region_id": ["19982"],
"operation": "INCLUDE"
},
{
"country_code": "ie",
"region_id": ["11821"],
"operation": "INCLUDE"
},
{
"country_code": "uk",
"region_id": ["25430"],
"operation": "EXCLUDE"
},
{
"country_code": "uk",
"region_id": ["25429"],
"operation": "EXCLUDE"
},
{
"country_code": "uk",
"region_id": ["25427"],
"operation": "EXCLUDE"
},
{
"country_code": "uk",
"region_id": ["25421"],
"operation": "EXCLUDE"
},
{
"country_code": "ie",
"region_id": ["11842"],
"operation": "EXCLUDE"
},
{
"country_code": "ie",
"region_id": ["11837"],
"operation": "EXCLUDE"
},
{
"country_code": "ie",
"region_id": ["11832"],
"operation": "EXCLUDE"
}
],
"devices": [
{
"os_type": "iOS",
"operation": "INCLUDE"
},
{
"os_type": "ANDROID",
"operation": "INCLUDE"
},
{
"os_type": "WEB",
"operation": "INCLUDE"
}
],
"enable_targeting_expansion": true,
"auto_expansion_options": {
"interest_expansion_option": {
"enabled": true
},
"custom_audience_expansion_option": {
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2025-03-07T22:01:36.873Z",
"optimization_goal": "IMPRESSIONS",
"pixel_id": "d3a12fd0-60a9-4536-89fe-f76ef6f04bf9",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD"
}
}
]
}
Example 3 - Compact targeting
This request fetches the same Ad Squad but uses the targeting_v2 parameter which returns the targeting in the compact style.
curl "https://adsapi.snapchat.com/v1/adsquads/1d1f9dd9-9c21-43b5-a2c4-0de0a01a3e0c?return_placement_v2=true&targeting_v2=ENABLED" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "6141e600-1b22-4090-9dc2-d1159527cf17",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "1d1f9dd9-9c21-43b5-a2c4-0de0a01a3e0c",
"updated_at": "2025-03-07T22:13:26.115Z",
"created_at": "2025-03-07T22:07:34.641Z",
"name": "UK and Ireland - Region targeting",
"status": "ACTIVE",
"campaign_id": "eee90f1e-889a-43aa-84b3-14a5879d864f",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"min_age": "18",
"operation": "INCLUDE"
}
],
"geos": [
{
"country_code": "uk",
"region_id": [
"25385",
"25382",
"25384",
"25389",
"25403",
"25401"
],
"operation": "INCLUDE"
},
{
"country_code": "ie",
"region_id": [
"11820",
"11843",
"28393",
"11825",
"19982",
"11821"
],
"operation": "INCLUDE"
},
{
"country_code": "uk",
"region_id": ["25430", "25429", "25427", "25421"],
"operation": "EXCLUDE"
},
{
"country_code": "ie",
"region_id": ["11842", "11837", "11832"],
"operation": "EXCLUDE"
}
],
"devices": [
{
"os_type": "WEB",
"operation": "INCLUDE"
},
{
"os_type": "iOS",
"operation": "INCLUDE"
},
{
"os_type": "ANDROID",
"operation": "INCLUDE"
}
],
"enable_targeting_expansion": true,
"auto_expansion_options": {
"interest_expansion_option": {
"enabled": true
},
"custom_audience_expansion_option": {
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2025-03-07T22:01:36.873Z",
"optimization_goal": "IMPRESSIONS",
"pixel_id": "d3a12fd0-60a9-4536-89fe-f76ef6f04bf9",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD"
}
}
]
}
Smart Audience auto-expansion
The auto_expansion_options object contains three attributes that can be used to expand the targeting of the Ad Squad based on similar qualities and
characteristics used in the existing targeting. Two of these attributes are both enabled by default on creation of the Ad Squad, the other options are
Ad Squads that form part of a Campaign advertising Housing, Credit or Employment, should always have auto-expansion disabled.
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| interest_expansion_option.enabled | Expands targeting based on interest targeting | R | true (default), false |
| custom_audience_expansion_option.enabled | Expands targeting based on selected custom audiences | R | true (default), false |
| auto_expansion_type | SMART_TARGETING will expand the audience on gender and beyond the maximum age defined in the targeting. This option requires that both interest_expansion_option and custom_audience_expansion_option are enabled. This option will not expand below the minimum age as defined in the demographic section of the targeting. | O | SMART_TARGETING |
| demographic_expansion_option.suggested_min_age | This option sets a suggested minimum age, expansion may take place below this age. | O | Integer between 13 - 55 |
Validation for Smart Audience
The Smart Audience availability is subject to an Ad squads configuration as per the below table. Ad Squads that form part of a Campaign advertising Housing, Credit or Employment, should always have auto-expansion disabled.
| Campaign setting | Ad Squad - optimization_goal | Smart targeting availability |
|---|---|---|
| — | APP_ACHIEVEMENT_UNLOCKED, APP_AD_VIEW, APP_ADD_TO_CART, APP_INSTALLS, APP_LEVEL_COMPLETE, APP_PURCHASE, APP_PURCHASE_VO, APP_REENGAGE_ADD_TO_CART, APP_REENGAGE_OPEN, APP_REENGAGE_PURCHASE, APP_SIGNUP, PIXEL_ADD_TO_CART, PIXEL_PAGE_VIEW, PIXEL_PURCHASE, PIXEL_PURCHASE_VO, PIXEL_SIGNUP, LANDING_PAGE_VIEW, LEAD_FORM_SUBMISSIONS | Available |
| — | IMPRESSIONS, STORY_OPENS, SWIPES, USES, VIDEO_VIEWS, VIDEO_VIEWS_15_SEC | Not available |
"regulations": {"restricted_delivery_signals": true} | IMPRESSIONS, SWIPES, APP_INSTALLS, PIXEL_ADD_TO_CART, PIXEL_PAGE_VIEW, PIXEL_PURCHASE, PIXEL_SIGNUP, LANDING_PAGE_VIEW, LEAD_FORM_SUBMISSIONS | Not available |
Targeting auto-expansion usage examples
Example 1 - Expansion on Interest and Custom audiences
"targeting": {
"enable_targeting_expansion": true,
"auto_expansion_options":
{
"interest_expansion_option":
{
"enabled": true
},
"custom_audience_expansion_option":
{
"enabled": true
}
}
}
This configuration will expand the targeting based both on interest and custom audiences.
Example 2 - Expansion on interest only
"targeting": {
"enable_targeting_expansion": true,
"auto_expansion_options":
{
"interest_expansion_option":
{
"enabled": true
},
"custom_audience_expansion_option":
{
"enabled": false
}
}
}
This configuration will expand the targeting based on interest targeting only.
Example 3 - Housing, Credit or Employment
"targeting": {
"enable_targeting_expansion": true,
"auto_expansion_options":
{
"interest_expansion_option":
{
"enabled": false
},
"custom_audience_expansion_option":
{
"enabled": false
}
}
}
No targeting expansion, this configuration should be used for Campaigns advertising Housing, Credit or Employment.
Example 4 - Smart Audience
"targeting": {
"demographics": [
{
"min_age": "18",
"max_age": "35",
"gender": "FEMALE",
"operation": "INCLUDE"
}
],
"enable_targeting_expansion": true,
"auto_expansion_options": {
"interest_expansion_option": {
"enabled": true
},
"custom_audience_expansion_option": {
"enabled": true
},
"auto_expansion_type": "SMART_TARGETING"
}
}
These settings activates the Smart Audience (SMART_TARGETING) which means targeting may expand across genders and also beyond the maximum age (max_age), but not below the minimum age (min_age) of 18 since a value has been set in the demographics targeting.
Example 5 - Smart Audience with suggested minimum age
"targeting": {
"demographics": [
{
"min_age": "18",
"max_age": "35",
"gender": "FEMALE",
"operation": "INCLUDE"
}
],
"enable_targeting_expansion": true,
"auto_expansion_options": {
"interest_expansion_option": {
"enabled": true
},
"custom_audience_expansion_option": {
"enabled": true
},
"demographic_expansion_option": {
"suggested_min_age": "25"
},
"auto_expansion_type": "SMART_TARGETING"
}
}
These settings means that Smart Audience (SMART_TARGETING) expansion is active, a suggested minimum age of 25 has been defined, the Smart Audience algorithm may expand below the suggested minimum age. The targeting will not expand below the minimum age (min_age) of 18 set in the demographics targeting.
App Install states
App Install states targeting can be used with the Creative types APP_INSTALL and DEEP_LINK and allows you to target a user given the user's install state for a specific App that you own. Using App Install state targeting comes with two prerequisites:
- A Snap App ID for the App needs to be set up in order to verify your app setting up your Snap App ID.
- The Ad Squad needs to have the
event_sourcesattribute set up, the Snap App ID used inevent_sourcesshould match the Snap App ID used in theapp_install_states
App Install state targeting can be applied in two different scenarios:
- When using the Optimization Goal APP_REENGAGE_OPEN or APP_REENGAGE_PURCHASE, see targeting example
- When using Dynamic Product Ads and
product_audiences, see below table and targeting example
App Install state / Optimization Goals
| Ad type | Install state | Optimization goals | Description |
|---|---|---|---|
| APP_INSTALL | NOT_INSTALLED | IMPRESSIONS, SWIPES, APP_INSTALL, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGNUP | Targets users that don't have the app installed |
| DEEP_LINK | INSTALLED | IMPRESSIONS, SWIPES, APP_REENGAGE_OPEN, APP_REENGAGE_PURCHASE | Targets users that have the app installed |
| DEEP_LINK | NOT_INSTALLED | IMPRESSIONS, SWIPES, APP_INSTALLS, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGN_UP | Targets users that don't have the app installed |
| DEEP_LINK | ALL | IMPRESSIONS, SWIPES | All users targeted |
App Install state / Product Audience
| Ad type | Product Audience | Install state | Optimization goals |
|---|---|---|---|
| APP_INSTALL | Prospecting | NOT_INSTALLED | IMPRESSIONS, SWIPES, APP_INSTALL, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGNUP |
| DEEP_LINK | Retargeting | INSTALLED | IMPRESSIONS, SWIPES, APP_REENGAGE_OPEN, APP_REENGAGE_PURCHASE |
| DEEP_LINK | Prospecting | NOT_INSTALLED | IMPRESSIONS, SWIPES, APP_INSTALLS, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGN_UP |
| DEEP_LINK | Prospecting | ALL | IMPRESSIONS, SWIPES |
Targeting Dimensions
All targeting dimensions will now have a deprecated boolean flag that will show whether the targeting dimension is deprecated. If a dimension has deprecated=true you will no longer be able to use it in the targeting_spec of an Ad Squad.
Targeting Type Support by Country
curl "https://adsapi.snapchat.com/v1/targeting/v1/options?country_code=us" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "86fd4602-89cd-46d4-a843-05d45dab484f",
"targeting_option": {
"snap_ads": [
"demographics:advanced_demographics",
"demographics:age_groups",
"demographics:age_min_max",
"demographics:gender",
"demographics:languages",
"devices:carrier",
"devices:connection_type",
"devices:marketing_name",
"devices:os_type",
"geos:country",
"geos:electoral",
"geos:metro",
"geos:postal_code",
"geos:region",
"interests:dlxc",
"interests:dlxs",
"interests:i360",
"interests:nln",
"interests:plc",
"interests:slc",
"interests:tgst",
"interests:vac",
"locations:chain_packages",
"locations:circles",
"locations:lois",
"regulated_content",
"segments:ab_segments",
"segments:engagement",
"segments:first_party",
"segments:fti",
"segments:lookalike",
"segments:mobile",
"segments:pixel"
]
}
}
This endpoint retrieves all targeting options available for the specified country code.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/v1/options
Parameters
| Parameter | Required | Possible values | Description |
|---|---|---|---|
| country_code | R | ISO ALPHA-2 Country Code (lowercase) | |
| is_intl_vac_enabled | O | true, false (default) | This parameter should be used to produce valid VAC options for countries outside of the US |
Example #1 Targeting Support for Germany
curl "https://adsapi.snapchat.com/v1/targeting/v1/options?country_code=de&is_intl_vac_enabled=true" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "f41d20fa-5ec2-45c9-8afd-a90efaaf764c",
"targeting_option": {
"snap_ads": [
"demographics:age_groups",
"demographics:age_min_max",
"demographics:gender",
"demographics:languages",
"devices:carrier",
"devices:connection_type",
"devices:marketing_name",
"devices:os_type",
"geos:country",
"geos:metro",
"geos:postal_code",
"geos:region",
"interests:slc",
"interests:vac",
"locations:chain_packages",
"locations:circles",
"regulated_content",
"segments:ab_segments",
"segments:engagement",
"segments:first_party",
"segments:fti",
"segments:lookalike",
"segments:mobile",
"segments:pixel"
]
}
}
This example retrieves all targeting options available for Germany.
Demographics
Demographics targeting allows an advertiser to find a user based on a variety of criteria.
Demographics - Age Groups
Get Age Group Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/demographics/age_group" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "57d1cb6900ff0c21bb32e920a00001737e616473617069736300016275696c642d66333735626434642d312d31332d3700010111",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"age_group": {
"name": "13-17",
"id": "13"
}
},
{
"sub_request_status": "SUCCESS",
"age_group": {
"name": "18-20",
"id": "18"
}
},
{
"sub_request_status": "SUCCESS",
"age_group": {
"name": "21-24",
"id": "21"
}
},
{
"sub_request_status": "SUCCESS",
"age_group": {
"name": "25-34",
"id": "25"
}
},
{
"sub_request_status": "SUCCESS",
"age_group": {
"name": "35+",
"id": "35"
}
}
]
}
This endpoint retrieves the list of age group targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/demographics/age_group
Demographics - Age Range
You can target ages using “min_age” and “max_age” attributes without using predefined age groups. Leaving out “max_age” from the targeting_spec will result in no age cap. Leaving out “min_age” will target 13 as the minimum age.
| Attribute | Description | Possible values |
|---|---|---|
| min_age | 35+ is deprecated but may be found in existing ad squads | 35+ |
| min_age | integer, defines the minimum age targeted | 13 - 35 |
| max_age | integer, defines the maximum age targeted. If you want no maximum cap, do not set a max_age | 13 - 55 |
See the Targeting Spec Examples for usage examples.
Demographics - Gender
Get Gender Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/demographics/gender" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "57d1cb8800ff01f6194d8f9a100001737e616473617069736300016275696c642d66333735626434642d312d31332d370001010f",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"gender": {
"name": "MALE",
"id": "1"
}
},
{
"sub_request_status": "SUCCESS",
"gender": {
"name": "FEMALE",
"id": "2"
}
},
{
"sub_request_status": "SUCCESS",
"gender": {
"name": "OTHER",
"id": "3"
}
}
]
}
This endpoint retrieves the list of gender targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/demographics/gender
Demographics - Language
Get Language Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/demographics/languages" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "591e4d8c00ff065b2527b9753e0001737e616473617069736300016275696c642d31616566313737632d312d36382d3000010156",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"languages": {
"id": "ar",
"name": "Arabic"
}
},
{
"sub_request_status": "SUCCESS",
"languages": {
"id": "en",
"name": "English"
}
},
{
"sub_request_status": "SUCCESS",
"languages": {
"id": "es",
"name": "Spanish"
}
},
{
"sub_request_status": "SUCCESS",
"languages": {
"id": "zh",
"name": "Chinese"
}
}
]
}
This endpoint retrieves the list of language targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/demographics/languages
Demographics - Advanced Demographics
Get Advanced Demographics Targeting Options
This endpoint retrieves the list of Advanced Demographics targeting options. This endpoint will stop returning Datalogix (DLXD) targeting options on the 27 September 2024, note that this endpoint will still provide non-Datalogix (DLXD) after the 27 September.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/demographics/advanced_demographics
curl "https://adsapi.snapchat.com/v1/targeting/demographics/advanced_demographics" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "57d1cb6900ff0c21bb32e920a00001737e616473617069736300016275696c642d66333735626434642d312d31332d3700010111",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"advanced_demographics": {
"name": "College Graduates",
"id": "DLXD_100"
}
},
{
"sub_request_status": "SUCCESS",
"advanced_demographics": {
"name": "Married People",
"id": "DLXD_300"
}
}
]
}
Device
Device targeting allows an advertiser to find a user based on a variety of criteria regarding the user's mobile device.
Device - Connection Type
Get Connection Type Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/device/connection_type"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"status": "success",
"request_id": "57abbd65000543a87d7116e2",
"targeting_dimensions": [
{
"sub_request_status": "success",
"connection_type": {
"name": "WIFI",
"id": "1"
}
},
{
"sub_request_status": "success",
"connection_type": {
"name": "CELL",
"id": "2"
}
}
]
}
This endpoint retrieves the list of device connection type targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/device/connection_type
Device - OS Type
Get Device OS Type Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/device/os_type"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "cb8d8708-6af7-4ff4-9ff3-43cc00887a8d",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"os_type": {
"id": "1",
"name": "iOS"
}
},
{
"sub_request_status": "SUCCESS",
"os_type": {
"id": "2",
"name": "ANDROID"
}
},
{
"sub_request_status": "SUCCESS",
"os_type": {
"id": "3",
"name": "WEB"
}
}
]
}
This endpoint retrieves the list of device OS type targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/device/os_type
Device - OS Version
Get Device OS Version Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/device/iOS/os_version"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5913bd1900ff0878f97f6fb40f0001737",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"os_version": {
"id": "1970324836974592",
"name": "7.0"
}
},
{
"sub_request_status": "SUCCESS",
"os_version": {
"id": "1970333426909184",
"name": "7.0.2"
}
},
[[snip]]
{
"sub_request_status": "SUCCESS",
"os_version": {
"id": "2818056891924480",
"name": "10.3.2"
}
}
]
}
This endpoint retrieves the list of device OS version targeting options. These OS versions can then be used in targeting as os_version_min and os_version_max.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/device/{{OS_TYPE}}/os_version
| Parameter | Possible Values |
|---|---|
| OS_TYPE | iOS, ANDROID |
Device - Carrier
Get Device Carrier Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/device/carrier"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5833291400ff098fc49db751b80001737e616473617069736300016275696c642d32663033323832622d646d612d63617272696572320001011e",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"carrier": {
"id": "US_ATT",
"name": "AT&T",
"valid_country": "us"
}
},
{
"sub_request_status": "SUCCESS",
"carrier": {
"id": "US_BOOSTMOBILE",
"name": "Boost Mobile",
"valid_country": "us"
}
},
{
"sub_request_status": "SUCCESS",
"carrier": {
"id": "US_CSPIRE",
"name": "C Spire",
"valid_country": "us"
}
}
]
}
This endpoint retrieves the list of device carrier targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/device/carrier
Device - Make
Get Device Make Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/device/marketing_name"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5964167200ff0255988362e6420001737e616473617069736300016275696c642d32353936663565632d312d38312d3100010126",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"marketing_name": {
"id": "Acer/",
"name": "Acer"
}
},
{
"sub_request_status": "SUCCESS",
"marketing_name": {
"id": "Apple/",
"name": "Apple"
}
},
{
"sub_request_status": "SUCCESS",
"marketing_name": {
"id": "Apple/iPad (3rd Gen)/",
"name": "Apple > iPad (3rd Gen)"
}
},
[[[snip]]]
{
"sub_request_status": "SUCCESS",
"marketing_name": {
"id": "Xiaomi/Redmi Note 4/",
"name": "Xiaomi > Redmi Note 4"
}
},
{
"sub_request_status": "SUCCESS",
"marketing_name": {
"id": "ZTE/",
"name": "ZTE"
}
},
{
"sub_request_status": "SUCCESS",
"marketing_name": {
"id": "ZTE/Zmax Pro/",
"name": "ZTE > Zmax Pro"
}
}
]
}
This endpoint retrieves the list of device make targeting options. Please note that specifying a parent level make option like "Apple/" in the targeting spec will include all devices of the kind "Apple/*" like "Apple/iPad (3rd Gen)/", "Apple/iPhone 4/", "Apple/iPhone 7 Plus/" etc.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/device/marketing_name
Geolocation
Geolocation targeting is based on the device's location at the time the ad is served.
Geolocation - Country
Get Country Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/geo/country"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"status": "success",
"request_id": "57abb71f00067458450ddec8",
"targeting_dimensions": [
{
"sub_request_status": "success",
"country": {
"lat": 0,
"lon": 0,
"continent": {
"id": "3",
"name": "au"
},
"country": {
"id": "166",
"name": "cocos (keeling) islands",
"code": "cck",
"code2": "cc"
}
}
},
{
"sub_request_status": "success",
"country": {
"lat": 0,
"lon": 0,
"continent": {
"id": "5",
"name": "eu"
},
"country": {
"id": "246",
"name": "finland",
"code": "fin",
"code2": "fi"
}
}
},
[[[ snip ]]]
{
"sub_request_status": "success",
"country": {
"lat": 0,
"lon": 0,
"continent": {
"id": "3",
"name": "au"
},
"country": {
"id": "334",
"name": "heard and mc donald islands",
"code": "hmd",
"code2": "hm"
}
}
},
{
"sub_request_status": "success",
"country": {
"lat": 0,
"lon": 0,
"continent": {
"id": "1",
"name": "af"
},
"country": {
"id": "454",
"name": "malawi",
"code": "mwi",
"code2": "mw"
}
}
}
]
}
This endpoint retrieves the list of country targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/geo/country
Geolocation - Region / State
Get Region / State Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/geo/us/region"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"status": "success",
"request_id": "57abb9ac000caa30eb4ac303",
"targeting_dimensions": [
{
"sub_request_status": "success",
"region": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "usa",
"code2": "us"
},
"region": {
"id": "16",
"code": "ia",
"name": "iowa"
}
}
},
{
"sub_request_status": "success",
"region": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "usa",
"code2": "us"
},
"region": {
"id": "21",
"code": "md",
"name": "maryland"
}
}
},
[[[ snip ]]]
{
"sub_request_status": "success",
"region": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "usa",
"code2": "us"
},
"region": {
"id": "31",
"code": "nj",
"name": "new jersey"
}
}
},
{
"sub_request_status": "success",
"region": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "usa",
"code2": "us"
},
"region": {
"id": "22",
"code": "ma",
"name": "massachusetts"
}
}
},
{
"sub_request_status": "success",
"region": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "usa",
"code2": "us"
},
"region": {
"id": "48",
"code": "wa",
"name": "washington"
}
}
}
]
}
This endpoint retrieves the list of region/state targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/geo/{country_code}/region
Parameters
| Parameter | Default | Description |
|---|---|---|
| country_code | ISO ALPHA-2 Country Code (lowercase) |
Geolocation - Metro / DMA
Get Metro / DMA Options
curl "https://adsapi.snapchat.com/v1/targeting/geo/us/metro"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5848879d00ff0ade2a482631b50001737e616473617069736300016275696c642d39323764616530622d312d32372d330001010c",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"metro": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "us",
"code2": "us"
},
"metro": {
"id": "557",
"name": "knoxville",
"regions": "ky/tn"
}
}
},
{
"sub_request_status": "SUCCESS",
"metro": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "us",
"code2": "us"
},
"metro": {
"id": "641",
"name": "san antonio",
"regions": "tx"
}
}
},
[[[ snip ]]]
{
"sub_request_status": "SUCCESS",
"metro": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "us",
"code2": "us"
},
"metro": {
"id": "717",
"name": "quincy-hannibal-keokuk",
"regions": "ia/il/mo"
}
}
},
{
"sub_request_status": "SUCCESS",
"metro": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "us",
"code2": "us"
},
"metro": {
"id": "546",
"name": "columbia, sc",
"regions": "sc"
}
}
}
]
}
This endpoint retrieves the list of metro/dma targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/geo/{country_code}/metro
Parameters
| Parameter | Default | Description |
|---|---|---|
| country_code | ISO ALPHA-2 Country Code (lowercase) |
Zipcode
Get Zipcode Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/geo/us/postal_code?cursor=0&limit=500"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "594db13f00ff05364288a100ff4b0001737e616473617069736300016275696c642d36356130306562372d312d37382d3100010121",
"paging": {
"next_link": "https://adsapi.snapchat.com/v1/targeting/geo/us/postal_code?limit=500&cursor=1"
},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"postal_code": {
"postalCode": "13024",
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "us",
"code2": "us"
},
"region": {
"id": "33",
"code": "ny",
"name": "new york"
},
"city": {
"id": "4587",
"name": "auburn"
}
}
},
[[snip]
{
"sub_request_status": "SUCCESS",
"postal_code": {
"postalCode": "94927",
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "us",
"code2": "us"
},
"region": {
"id": "5",
"code": "ca",
"name": "california"
},
"city": {
"id": "2370",
"name": "rohnert park"
}
}
}
]
}
This endpoint retrieves the list of zipcode targeting options.
This endpoint supports pagination. Specify the number of entries to be returned using the limit paramter. The paging object in the response will include next_link which indicates the next url to be fetched.
Please note that United Arab Emirates do not use zip codes.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/geo/{country_code}/postal_code?cursor=0&limit=500
Parameters
| Parameter | Default | Description |
|---|---|---|
| country_code | ISO ALPHA-2 Country Code (lowercase) | |
| cursor | cursor/page number | |
| limit | Page size. the number of entries to be retrieved in one page. Can be between 10-10000 |
Interests
Interest targeting allows an advertiser to find a user based on Snap Lifestyle Categories , Oracle Datalogix (DLX) Interests, Placed Visitation Segments and Snap Visitation Segments.
The availability of interest targeting will vary from country to country, you should also take into account if the Campaign is targeting Housing, Credit or Employment in which case the interest categories may look different.
Interests - Snap Lifestyle Categories
curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/scls?country_code=us"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "490744c7-a663-4e9c-95b9-edc947cb6ce6",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_1",
"name": "Adventure Seekers",
"path": "/Adventure Seekers",
"parent_id": "SLC_0",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10",
"name": "Do-It-Yourselfers",
"path": "/Do-It-Yourselfers",
"parent_id": "SLC_0",
"source": "SNAPCHAT"
}
},
<<snip>>
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_97",
"name": "Cricket Fans",
"path": "/Sports Fans/Cricket Fans",
"parent_id": "SLC_67",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_98",
"name": "Crime & Mystery Genre Fans",
"path": "/Film & TV Fans/Crime & Mystery Genre Fans",
"parent_id": "SLC_12",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_99",
"name": "Indie & Foreign Film Fans",
"path": "/Film & TV Fans/Indie & Foreign Film Fans",
"parent_id": "SLC_12",
"source": "SNAPCHAT"
}
}
]
}
This endpoint retrieves the list of Snap Lifestyle Categories targeting options by the specified country code.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/v1/interests/scls
Parameters
| Parameter | Default | Description |
|---|---|---|
| country_code | ISO ALPHA-2 Country Code (lowercase) | |
| is_hec | true | optional parameter, returns interest targeting that is safe to use when advertising Housing, Credit and Employment |
| limit | integer, min 50, max 1000 |
Interests - SCLS example
curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/scls?country_code=us&is_hec=true"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "40b06393-59de-46e7-b84a-f01d0708d3c6",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10002",
"name": "Arts & Culture Mavens - HEC",
"path": "/Arts & Culture Mavens - HEC",
"parent_id": "SLC_0",
"source": "SNAPCHAT",
"is_hec": true
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10004",
"name": "Beachgoers & Surfers - HEC",
"path": "/Beachgoers & Surfers - HEC",
"parent_id": "SLC_0",
"source": "SNAPCHAT",
"is_hec": true
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10009",
"name": "Comics & Animation Fans - HEC",
"path": "/Comics & Animation Fans - HEC",
"parent_id": "SLC_0",
"source": "SNAPCHAT",
"is_hec": true
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10012",
"name": "Film & TV Fans - HEC",
"path": "/Film & TV Fans - HEC",
"parent_id": "SLC_0",
"source": "SNAPCHAT",
"is_hec": true
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10015",
"name": "Cordcutters - HEC",
"path": "/Film & TV Fans - HEC/Cordcutters - HEC",
"parent_id": "SLC_10012",
"source": "SNAPCHAT",
"is_hec": true
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10016",
"name": "Drama Genre Fans - HEC",
"path": "/Film & TV Fans - HEC/Drama Genre Fans - HEC",
"parent_id": "SLC_10012",
"source": "SNAPCHAT",
"is_hec": true
}
},
<<snip>>
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10220",
"name": "Console Gamers - HEC",
"path": "/Gamers - HEC/Console Gamers - HEC",
"parent_id": "SLC_10033",
"source": "SNAPCHAT",
"is_hec": true
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10221",
"name": "PC Gamers - HEC",
"path": "/Gamers - HEC/PC Gamers - HEC",
"parent_id": "SLC_10033",
"source": "SNAPCHAT",
"is_hec": true
}
}
]
}
Example of retrieving Snap Lifestyle Categories for use a campaign promoting Housing, Credit or Employment.
Interests - First Party Visitation Segments
Interest targeting based on visitation segments that are provided by Snap.
Get First Party Visitation Segments
curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/vac?country_code=us"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "cc492ca5-33cd-4c23-949d-b869d6e0e2d5",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_1",
"name": "Arts & Entertainment",
"path": "/Arts & Entertainment",
"parent_id": "VAC_0",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_100",
"name": "Chipotle Restaurants",
"path": "/Dining & Nightlife/Fast Casual Restaurants/Chipotle Restaurants",
"parent_id": "VAC_99",
"source": "SNAPCHAT"
}
},
<snip>
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_97",
"name": "Ice Cream Shops",
"path": "/Dining & Nightlife/Sweet & Dessert Shops/Ice Cream Shops",
"parent_id": "VAC_96",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_99",
"name": "Fast Casual Restaurants",
"path": "/Dining & Nightlife/Fast Casual Restaurants",
"parent_id": "VAC_53",
"source": "SNAPCHAT"
}
}
]
}
This endpoint retrieves a list of targeting options for First Party Visitation Segments.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/v1/interests/vac
Parameters
| Parameter | Possible values | Description |
|---|---|---|
| country_code | ISO ALPHA-2 Country Code (lowercase) | |
| is_hec | true, false (default) | optional parameter, returns interest targeting that is safe to use when advertising Housing, Credit and Employment (only available for US) |
| limit | integer, min 50, max 1000 |
Interests - VAC example #1 United States
curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/vac?is_hec=true&country_code=us"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "913bdce1-8dbf-4dce-a224-cf7ca1edc538",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_10001",
"name": "Arts & Entertainment - HEC",
"path": "/Arts & Entertainment - HEC",
"parent_id": "VAC_0",
"source": "SNAPCHAT",
"is_hec": true
}
},
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_10008",
"name": "Movie Theaters - HEC",
"path": "/Arts & Entertainment - HEC/Movie Theaters - HEC",
"parent_id": "VAC_10001",
"source": "SNAPCHAT",
"is_hec": true
}
},
<snip>
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_10291",
"name": "Theme Parks - HEC",
"path": "/Travel - HEC/Theme Parks - HEC",
"parent_id": "VAC_10265",
"source": "SNAPCHAT",
"is_hec": true
}
},
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_10292",
"name": "Disney Parks and Hotels - HEC",
"path": "/Travel - HEC/Theme Parks - HEC/Disney Parks and Hotels - HEC",
"parent_id": "VAC_10291",
"source": "SNAPCHAT",
"is_hec": true
}
}
]
}
Example of retrieving First Party Visitation Segments for use with an Ad Set promoting Housing, Credit or Employment, targeting the United States.
Interests - VAC example #2 Germany
curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/vac?country_code=de"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "8a22cbcd-8f4b-423b-87d0-f0528399ffb7",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_1",
"name": "Arts & Entertainment",
"path": "/Arts & Entertainment",
"parent_id": "VAC_0",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_100",
"name": "Chipotle Restaurants",
"path": "/Dining & Nightlife/Fast Casual Restaurants/Chipotle Restaurants",
"parent_id": "VAC_99",
"source": "SNAPCHAT"
}
},
<snip>
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_97",
"name": "Ice Cream Shops",
"path": "/Dining & Nightlife/Sweet & Dessert Shops/Ice Cream Shops",
"parent_id": "VAC_96",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_99",
"name": "Fast Casual Restaurants",
"path": "/Dining & Nightlife/Fast Casual Restaurants",
"parent_id": "VAC_53",
"source": "SNAPCHAT"
}
}
]
}
Example of retrieving First Party Visitation Segments for use with an Ad Set targeting Germany.
Interests - First Party Shopper Segments
Interest targeting based on shopper segments that are provided by Snap.
Get First Party Shopper Segments
curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/shp?country_code=us&limit=50"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "576f7f3a-c58b-407d-bdbf-21802c8b61b9",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"shp": {
"id": "SHP_73",
"name": "Amusement Parks Buyers",
"path": "/Amusement Parks Buyers",
"parentId": "SHP_0",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"shp": {
"id": "SHP_99",
"name": "Disney Parks",
"path": "/Amusement Parks Buyers/Disney Parks",
"parentId": "SHP_73",
"source": "SNAPCHAT"
}
},
<snip>
{
"sub_request_status": "SUCCESS",
"shp": {
"id": "SHP_37",
"name": "Hotel & Motel Buyers",
"path": "/Travel Services Buyers/Hotel & Motel Buyers",
"parentId": "SHP_15",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"shp": {
"id": "SHP_122",
"name": "eCommerce Buyers",
"path": "/eCommerce Buyers",
"parentId": "SHP_0",
"source": "SNAPCHAT"
}
}
]
}
This endpoint retrieves a list of targeting options for First Party Shopper Segments.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/v1/interests/shp
Parameters
| Parameter | Default | Description | Possible values |
|---|---|---|---|
| country_code | ISO ALPHA-2 Country Code (lowercase) | us | |
| limit | integer, min 50, max 1000 |
Interests - Oracle Datalogix (DLX)
Oracle audience targeting is offered via three separate endpoints, all Oracle Datalogix interest targeting will be deprecated on the 27 September 2024.
Get Oracle Datalogix DLXS Interest Targeting Options
This endpoint retrieves the list of Oracle Datalogix DLXS Interests targeting options, this endpoint will be deprecated on the 27 September 2024.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/interests/dlxs
curl "https://adsapi.snapchat.com/v1/targeting/interests/dlxs"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57acea61000484407b52009b",
"targeting_dimensions": [
{
"sub_request_status": "success",
"dlxs": {
"name": "Apparel Shoppers",
"id": "DLXS_1"
}
},
{
"sub_request_status": "success",
"dlxs": {
"name": "Small & Mid-size SUV Shoppers",
"id": "DLXS_100"
}
}
]
}
Get Oracle Datalogix DLXC Interest Targeting Options
This endpoint retrieves the list of Oracle Datalogix DLXC targeting options, this endpoint will be deprecated on the 27 September 2024.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/interests/dlxc
curl "https://adsapi.snapchat.com/v1/targeting/interests/dlxc"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57acea61000484407b52009b",
"targeting_dimensions": [
{
"sub_request_status": "success",
"dlxc": {
"name": "Home Movie Viewers (Action)",
"id": "DLXC_101"
}
},
{
"sub_request_status": "success",
"dlxc": {
"name": "TV Viewers (Variety Shows)",
"id": "DLXC_133"
}
}
]
}
Get Oracle Datalogix DLXP Interest Targeting Options
This endpoint retrieves the list of Oracle Datalogix DLXP targeting options, this endpoint will be deprecated on the 27 September 2024.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/interests/dlxp
curl "https://adsapi.snapchat.com/v1/targeting/interests/dlxp"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "590850dd00ff05d022b1d7a5c50001737e616473617069736300016275696c642d62663930383438312d312d36322d320001013e",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"dlxp": {
"id": "DLXP_107",
"name": "Ford Dealers"
}
},
{
"sub_request_status": "SUCCESS",
"dlxp": {
"id": "DLXP_108",
"name": "Foreign Vehicle Dealers"
}
},
{
"sub_request_status": "SUCCESS",
"dlxp": {
"id": "DLXP_109",
"name": "Honda Dealers"
}
}
]
}
Get Nielsen Interest Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/interests/nln"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b3426d900ff072f79188f4fe20001737e616473617069736300016275696c642d38666335393665372d312d3137392d",
"paging": {
"next_link": "https://adsapi.snapchat.com/v1/targeting/interests/nln?cursor=1&limit=999"
},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"nln": {
"id": "NLN_1000",
"name": "Apparel Buyers",
"path": "/Apparel Buyers",
"source": "Nielsen"
}
},
{
"sub_request_status": "SUCCESS",
"nln": {
"id": "NLN_10000",
"name": "Pet Product Buyers",
"path": "/Pet Product Buyers",
"source": "Nielsen"
}
},
{
"sub_request_status": "SUCCESS",
"nln": {
"id": "NLN_10001",
"name": "Pet Store Buyers",
"parent_id": "NLN_10000",
"path": "/Pet Product Buyers/Pet Store Buyers",
"source": "NBI"
}
}
]
}
This endpoint retrieves the list of Nielsen interest targeting options. The response is paginated and contains a link to the next page of the response. To fetch all categories please keep issuing a GET request to next_link contained in the paging parameter in the response, until paging returns nothing.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/interests/nln
Location
Location targeting allows an advertiser to target users based on their location.
Location - Categories
Get Location Categories Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/location/categories_loi"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
Response:
{
"request_status": "SUCCESS",
"request_id": "5a01027200ff0e853c41a9d4810001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d33356139343261632d6c6f632d6c6f6900010106",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"categories_loi": {
"id": "LOI_1000",
"name": "Arts & Entertainment",
"path":"/Arts & Entertainment"
}
},
{
"sub_request_status": "SUCCESS",
"categories_loi": {
"id": "LOI_1001",
"name": "Comedy Clubs",
"parent_id": "LOI_1000",
"path":"/Arts & Entertainment/Comedy Clubs"
}
},
{
"sub_request_status": "SUCCESS",
"categories_loi": {
"id": "LOI_1002",
"name": "Galleries & Museums",
"parent_id": "LOI_1000",
"path":"/Arts & Entertainment/Galleries & Museums"
}
},
{
"sub_request_status": "SUCCESS",
"categories_loi": {
"id": "LOI_1003",
"name": "Movie Theaters",
"parent_id": "LOI_1000",
"path":"/Arts & Entertainment/Movie Theaters"
}
},
... // etc
]
}
This endpoint retrieves the list of location categories.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/location/categories_loi
Attributes
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| proximity | Proximity to selected location categories | R | |
| proximity_unit | Unit to be used for radius | R | METERS (default), KILOMETERS, FEET, MILES |
Location - Point Radius
"targeting": {
"regulated_content": "false",
"demographics": [
{
"age_groups": [
"21-24"
]
}
],
"geos": [
{
"country_code": "us"
}
],
"locations": [
{
"circles": [
{
"latitude": 47.612447,
"longitude": -122.336751,
"radius": 500
},
{
"latitude": 47.617102,
"longitude": -122.203961,
"radius": 50,
"unit": "KILOMETERS"
}
],
"operation": "INCLUDE"
}
]
}
Using point radius targeting advertisers can pass in lists of latitude, longitude, and radius “circles” for location targeting. You can add up to 500 circles in the targeting spec.
Attributes
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| latitude | Latitude in decimal degrees | R | |
| longitude | Longitude in decimal degrees | R | |
| radius | Radius in meters (minimum 96 meters and maximum 100000 meters) | R | |
| unit | Unit to be used for radius | O | METERS (default), KILOMETERS, FEET, MILES |
Targeting Specs - Greater than 500 rows
Any Ad Squad that contains more than 500 targeting criteria will have its targeting specifications broken out into a separate sub resource called targeting_specs and will be replaced by a property called separated_types. Any further updates or reads to the targeting spec will need to be performed on the new targeting_spec sub resource and not in the Ad Squad resource. This new resource is also described below.
Please note that before the deprecation date, you can use the below query parameter to test and build against the changes. targeting_spec_response_scope=AD_SQUAD_ONLY
Create Ad Squad
The create API call remains mostly the same, except if it contains more than 500 targeting criteria, in which case the targeting will be broken out into a new targeting sub resource. The response will contain the new separated_types attribute, indicating that this breakout has been performed.
HTTP Request
POST https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{
"adsquads": [
{
"name": "Badger Supplies 2000 US Postcode Targeting",
"status": "ACTIVE",
"campaign_id": "51334977-d500-4f6a-bb5c-e6d4c2e00067",
"type": "SNAP_ADS",
"targeting":
{
"regulated_content": false,
"geos": [
{
"country_code": "us",
"postal_code": [
"20001"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"20009"
],
"operation": "INCLUDE"
},
...
},
{
"country_code": "us",
"postal_code": [
"08903"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"08906"
],
"operation": "INCLUDE"
}
],
"devices": [
{}],
"auto_expansion_options":
{
"interest_expansion_option":
{
"enabled": true
},
"custom_audience_expansion_option":
{
"enabled": true
}
}
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-09-16T11:22:31.894Z",
"optimization_goal": "SWIPES",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD"
}
]
}' \
"https://adsapi.snapchat.com/v1/campaigns/51334977-d500-4f6a-bb5c-e6d4c2e00067/adsquads"
The above command returns JSON structured like this:
Response:
{
"request_status": "SUCCESS",
"request_id": "616edbf700ff0cbfe2f0d990390001737e7465616d6b6f363139000161646d616e616765722d6170693a6b702d726176360001010f",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad":
{
"id": "a4a40858-c794-432b-aaca-71314e019a86",
"updated_at": "2021-10-19T14:53:56.773Z",
"created_at": "2021-10-19T14:53:56.270Z",
"effective_status": "PAUSED",
"name": "Badger Supplies 2000 US Postcode Targeting",
"status": "ACTIVE",
"campaign_id": "51334977-d500-4f6a-bb5c-e6d4c2e00067",
"type": "SNAP_ADS",
"targeting":
{
"regulated_content": false,
"separated_types": [
"GEO"
],
"devices": [
{}],
"auto_expansion_options":
{
"interest_expansion_option":
{
"enabled": true
},
"custom_audience_expansion_option":
{
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement": "SNAP_ADS",
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-09-16T11:22:31.894Z",
"optimization_goal": "SWIPES",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED",
"delivery_status": [
"INVALID_EFFECTIVE_INVALID",
"INVALID_NOT_EFFECTIVE_ACTIVE"
],
"skadnetwork_properties":
{
"status": "NEVER_ENROLLED"
}
}
}]
}
GET Ad Squad:
The GET endpoint remains the same, except in the case that there are more than 500 targeting criteria, in which case it will not return any targeting spec in the response and will return a separated_types property. To retrieve the targeting spec you must call the targeting sub resource.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
"https://adsapi.snapchat.com/v1/adsquads/a4a40858-c794-432b-aaca-71314e019a86?return_placement_v2=true"
The above command returns JSON structured like this:
Response:
{
"request_status": "SUCCESS",
"request_id": "616ee96a00ff06b0b1557b48670001737e7465616d6b6f363139000161646d616e616765722d6170693a6b702d7261763600010131",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad":
{
"id": "a4a40858-c794-432b-aaca-71314e019a86",
"updated_at": "2021-10-19T14:53:56.773Z",
"created_at": "2021-10-19T14:53:56.270Z",
"effective_status": "PAUSED",
"name": "Badger Supplies US Post Code Targeting II",
"status": "ACTIVE",
"campaign_id": "51334977-d500-4f6a-bb5c-e6d4c2e00067",
"type": "SNAP_ADS",
"targeting":
{
"regulated_content": false,
"separated_types": [
"GEO"
],
"devices": [
{}],
"auto_expansion_options":
{
"interest_expansion_option":
{
"enabled": true
},
"custom_audience_expansion_option":
{
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement_v2":
{
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"INTERSTITIAL_USER",
"INTERSTITIAL_CONTENT",
"INSTREAM"
]
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-09-16T11:22:31.894Z",
"optimization_goal": "SWIPES",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED",
"delivery_status": [
"INVALID_EFFECTIVE_INVALID",
"INVALID_NOT_EFFECTIVE_ACTIVE"
],
"skadnetwork_properties":
{
"status": "NEVER_ENROLLED"
}
}
}]
}
Update Ad Squad
The update will work the same, except in the situation where there are more than 500 targeting criteria. In this case you can no longer use the Ad Squad endpoint to update the targeting criteria and doing so will return an error. You may continue to use the Ad Squad endpoint to update other fields. To update the targeting criteria, you must use the targeting resource.
HTTP Request
PUT https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{
"adsquads": [
{
"id": "a4a40858-c794-432b-aaca-71314e019a86",
"updated_at": "2021-10-19T14:53:56.773Z",
"created_at": "2021-10-19T14:53:56.270Z",
"effective_status": "PAUSED",
"name": "Badger Supplies US Postcode Targeting",
"status": "ACTIVE",
"campaign_id": "51334977-d500-4f6a-bb5c-e6d4c2e00067",
"type": "SNAP_ADS",
"targeting":
{
"regulated_content": false,
"geos": [
{
"country_code": "us",
"postal_code": [
"20001"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"20009"
],
"operation": "INCLUDE"
},
...
{
"country_code": "us",
"postal_code": [
"08903"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"08906"
],
"operation": "INCLUDE"
},
{
"country_code": "ca",
"operation": "INCLUDE"
}
],
"devices": [
{}],
"auto_expansion_options":
{
"interest_expansion_option":
{
"enabled": true
},
"custom_audience_expansion_option":
{
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement_v2":
{
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"INTERSTITIAL_USER",
"INTERSTITIAL_CONTENT",
"INSTREAM"
]
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-09-16T11:22:31.894Z",
"optimization_goal": "SWIPES"
}]
}' \
"https://adsapi.snapchat.com/v1/campaigns/51334977-d500-4f6a-bb5c-e6d4c2e00067/adsquads"
The above command returns JSON structured like this:
Response:
{
"request_status": "SUCCESS",
"request_id": "617035ff0000ff07f6b7ff00b0ef310001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d38393135316663392d312d3438382d3000010148",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad":
{
"id": "a4a40858-c794-432b-aaca-71314e019a86",
"updated_at": "2021-10-20T15:30:16.952Z",
"created_at": "2021-10-19T14:53:56.270Z",
"effective_status": "PAUSED",
"name": "Badger Supplies US Postcode Targeting",
"status": "ACTIVE",
"campaign_id": "51334977-d500-4f6a-bb5c-e6d4c2e00067",
"type": "SNAP_ADS",
"targeting":
{
"regulated_content": false,
"separated_types": [
"GEO"
],
"devices": [
{}],
"auto_expansion_options":
{
"interest_expansion_option":
{
"enabled": true
},
"custom_audience_expansion_option":
{
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement_v2":
{
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"INTERSTITIAL_USER",
"INTERSTITIAL_CONTENT",
"INSTREAM"
]
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-09-16T11:22:31.894Z",
"optimization_goal": "SWIPES",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED",
"delivery_status": [
"INVALID_EFFECTIVE_INVALID",
"INVALID_NOT_EFFECTIVE_ACTIVE"
],
"skadnetwork_properties":
{
"status": "NEVER_ENROLLED"
},
"delivery_properties_version": 1634743816283
}
}]
}
GET all targeting specs under an Ad Squad
This request retrieves all Targeting Specs under the specified Ad Squad, currently there can only be one Targeting Spec for an Ad Squad. If the response consists of an empty array it means the Ad Squad does not have an associated Targeting Spec.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/targeting_specs
URL Parameters
| Attribute | Possible values | Description |
|---|---|---|
| ad_squad_id | The ID of the Ad Squad under which the Targeting Spec is being created | |
| targeting_v2 | ENABLED | Optional parameter, returns the targeting part of the Ad Squad in compact format |
curl -X GET \
-H "Authorization: Bearer meowmeowmeow" \
"https://adsapi.snapchat.com/v1/adsquads/a4a40858-c794-432b-aaca-71314e019a86/targeting_specs"
The above command returns JSON structured like this:
Response:
{
"request_status": "SUCCESS",
"request_id": "6170522400ff065868237e7ebf0001737e7465616d6b6f363139000161646d616e616765722d6170693a776e75636b6f6c73746573740001012f",
"paging":
{},
"targeting_specs": [
{
"sub_request_status": "SUCCESS",
"targeting_spec":
{
"id": "7ba7b1f3-2eb7-471d-a143-dd9c4b60cda7",
"updated_at": "2021-10-20T15:30:16.704Z",
"created_at": "2021-10-19T14:53:57.161Z",
"container_kind": "AdSquads",
"container_id": "a4a40858-c794-432b-aaca-71314e019a86",
"type": "GEO",
"geos": [
{
"country_code": "us",
"postal_code": [
"20001"
],
"operation": "EXCLUDE"
},
{
"country_code": "us",
"postal_code": [
"20009"
],
"operation": "EXCLUDE"
},
...
{
"country_code": "us",
"postal_code": [
"08903"
],
"operation": "INCLUDE"
},
{
"country_code": "ca",
"postal_code": [
"08906"
],
"operation": "INCLUDE"
}
]
}
}]
}
GET a specific targeting spec
This request retrieves a specific Targeting Spec.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting_specs/{targeting_spec_id}
URL Parameters
| Attribute | Possible values | Description |
|---|---|---|
| targeting_spec_id | The ID of the Targeting Spec you wish to retrieve | |
| targeting_v2 | ENABLED | Optional parameter, returns the targeting part of the Ad Squad in compact format |
curl -X GET \
-H "Authorization: Bearer meowmeowmeow" \
"https://adsapi.snapchat.com/v1/targeting_specs/{targeting_spec_id}"
The above command returns JSON structured like this:
Response:
{
"request_status": "SUCCESS",
"request_id": "617069bf00ff0a62999d01b8160001737e7465616d6b6f363139000161646d616e616765722d6170693a776e75636b6f6c737465737400010128",
"targeting_specs": [
{
"sub_request_status": "SUCCESS",
"targeting_spec":
{
"id": "7ba7b1f3-2eb7-471d-a143-dd9c4b60cda7",
"updated_at": "2021-10-20T15:30:16.704Z",
"created_at": "2021-10-19T14:53:57.161Z",
"container_kind": "AdSquads",
"container_id": "a4a40858-c794-432b-aaca-71314e019a86",
"type": "GEO",
"geos": [
{
"country_code": "us",
"postal_code": [
"20001"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"20009"
],
"operation": "INCLUDE"
},
...
{
"country_code": "us",
"postal_code": [
"08903"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"08906"
],
"operation": "INCLUDE"
},
{
"country_code": "ca",
"operation": "INCLUDE"
}
]
}
}]
}
Updating a Targeting Spec
This request will update a Targeting Spec, note that the Targeting Spec has a maximum limit of 4,000 targeting criteria.
HTTP Request
PUT https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/targeting_specs
URL Parameters
| Attribute | Description |
|---|---|
| ad_squad_id | The ID of the Ad Squad under which the Targeting Spec is being created |
Attributes
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| id | The ID of the Targeting Spec you wish to update | R | |
| type | The type of targeting, currently only GEO | R | GEO |
| geos | An array containing a valid targeting spec for geos | R |
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{
"targeting_specs": [
{
"id": "7ba7b1f3-2eb7-471d-a143-dd9c4b60cda7",
"type": "GEO",
"geos": [
{
"country_code": "us",
"postal_code": [
"20001"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"20009"
],
"operation": "INCLUDE"
},
...
{
"country_code": "us",
"postal_code": [
"08903"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"08906"
],
"operation": "INCLUDE"
},
{
"country_code": "ca",
"operation": "INCLUDE"
},
{
"country_code": "ie",
"operation": "INCLUDE"
}
]
}]
}' \
"https://adsapi.snapchat.com/v1/adsquads/a4a40858-c794-432b-aaca-71314e019a86/targeting_specs"
The above command returns JSON structured like this:
Response:
{
"request_status": "SUCCESS",
"request_id": "61706cea00ff0bc60d6308beaf0001737e7465616d6b6f363139000161646d616e616765722d6170693a776e75636b6f6c737465737400010140",
"targeting_specs": [
{
"sub_request_status": "SUCCESS",
"targeting_spec":
{
"id": "7ba7b1f3-2eb7-471d-a143-dd9c4b60cda7",
"updated_at": "2021-10-20T19:24:41.668Z",
"created_at": "2021-10-19T14:53:57.161Z",
"container_kind": "AdSquads",
"container_id": "a4a40858-c794-432b-aaca-71314e019a86",
"type": "GEO",
"geos": [
{
"country_code": "us",
"postal_code": [
"20001"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"20009"
],
"operation": "INCLUDE"
},
...
{
"country_code": "us",
"postal_code": [
"08903"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"08906"
],
"operation": "INCLUDE"
},
{
"country_code": "ca",
"operation": "INCLUDE"
},
{
"country_code": "ie",
"operation": "INCLUDE"
}
]
}
}]
}