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 selected interest targeting and/or selected custom audiences, by default both of these options are enabled on creation | 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 auto-expansion
The auto_expansion_options
object contains two attribures that will expand the targeting of the Ad Squad based on similar qualities and
characteristics used in the existing targeting. These two attributes are both enabled by default on creation of the Ad Squad.
Ad Squads that form part of a Campaign advertising Housing, Credit or Employment, should always have auto-expansion disabled.
Name | Description | Possible Values |
---|---|---|
interest_expansion_option.enabled | Expands targeting based on interest targeting | true (default),false |
custom_audience_expansion_option.enabled | Expands targeting based on selected custom audiences | true (default),false |
Targeting auto-expansion usage examples
Example 1
Example 1 - Expand targeting based both on interest and custom audiences:
"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
Example 2 - Expand targeting based on interest targeting only:
"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
Example 3 - Do not expand targeting:
"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.
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_sources
attribute set up, the Snap App ID used inevent_sources
should 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 - 49 |
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 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 | Description |
---|---|
ad_squad_id | The ID of the Ad Squad under which the Targeting Spec is being created |
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 | Description |
---|---|
targeting_spec_id | The ID of the Targeting Spec you wish to retrieve |
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"
}
]
}
}]
}