Skip to main content

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.

AttributeDescriptionRequiredNote
app_install_statesDefines whether targeted user has App installed or notOFor usage see App Install states
demographicsList of Demographic TargetsORequired when using Multi-country targeting
devicesList of Device TargetsO
geosList of Geo/Location TargetsRMulti-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
interestsList of Interest TargetsO
locationsList of Location categories/CirclesO
regulated_contentFlag to mark content within the Ad Squad as Regulated ContentOFALSE (default), TRUE
segmentsList of Customer List segment targetsO
auto_expansion_optionsThis 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 creationOFor 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

CategoryTypeSupportDescription
app_install_statesapp installation stateSee App Install statesDefines whether targeted user has App installed or not
demographicsgender, languages, age_group, min_age, max_age, DLXDINCLUDEGender, Language, Age Groups, Age Range, Advanced Demographics
devicesconnection_type, os_type, os_version, carrier, marketing_nameINCLUDEConnection type, OS Type, OS Version, Carrier, Make
geoscountryINCLUDE/EXCLUDEMulti-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
geosregionINCLUDE/EXCLUDERegion/State
geosmetroINCLUDE/EXCLUDEMetro/DMA
geospostal_codeINCLUDE/EXCLUDEZipcode/Post code
interestsSLCINCLUDE/EXCLUDESnap Lifestyle Categories
interestsDLX, DLXS, DLXC, NLN, PLC, VACINCLUDEOracle Datalogix DLX/DLXS/DLXC Interest Targeting, Nielsen Interest Targeting NLN, Placed Visitation PLC, Snap Visitation VAC
locationscategories_loi, circlesINCLUDELocation Categories, Location Point Radius
segmentssegment_idINCLUDE/EXCLUDECustomer 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.

NameDescriptionPossible Values
interest_expansion_option.enabledExpands targeting based on interest targetingtrue (default),false
custom_audience_expansion_option.enabledExpands targeting based on selected custom audiencestrue (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 in event_sources should match the Snap App ID used in the app_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 typeInstall stateOptimization goalsDescription
APP_INSTALLNOT_INSTALLEDIMPRESSIONS, SWIPES, APP_INSTALL, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGNUPTargets users that don't have the app installed
DEEP_LINKINSTALLEDIMPRESSIONS, SWIPES, APP_REENGAGE_OPEN, APP_REENGAGE_PURCHASETargets users that have the app installed
DEEP_LINKNOT_INSTALLEDIMPRESSIONS, SWIPES, APP_INSTALLS, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGN_UPTargets users that don't have the app installed
DEEP_LINKALLIMPRESSIONS, SWIPESAll users targeted

App Install state / Product Audience

Ad typeProduct AudienceInstall stateOptimization goals
APP_INSTALLProspectingNOT_INSTALLEDIMPRESSIONS, SWIPES, APP_INSTALL, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGNUP
DEEP_LINKRetargetingINSTALLEDIMPRESSIONS, SWIPES, APP_REENGAGE_OPEN, APP_REENGAGE_PURCHASE
DEEP_LINKProspectingNOT_INSTALLEDIMPRESSIONS, SWIPES, APP_INSTALLS, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGN_UP
DEEP_LINKProspectingALLIMPRESSIONS, 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

ParameterRequiredPossible valuesDescription
country_codeRISO ALPHA-2 Country Code (lowercase)
is_intl_vac_enabledOtrue, 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.

AttributeDescriptionPossible values
min_age35+ is deprecated but may be found in existing ad squads35+
min_ageinteger, defines the minimum age targeted13 - 35
max_ageinteger, defines the maximum age targeted. If you want no maximum cap, do not set a max_age13 - 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

ParameterPossible Values
OS_TYPEiOS, 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

ParameterDefaultDescription
country_codeISO 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

ParameterDefaultDescription
country_codeISO 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

ParameterDefaultDescription
country_codeISO ALPHA-2 Country Code (lowercase)
cursorcursor/page number
limitPage 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

ParameterDefaultDescription
country_codeISO ALPHA-2 Country Code (lowercase)
is_hectrueoptional parameter, returns interest targeting that is safe to use when advertising Housing, Credit and Employment
limitinteger, 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

ParameterPossible valuesDescription
country_codeISO ALPHA-2 Country Code (lowercase)
is_hectrue, false (default)optional parameter, returns interest targeting that is safe to use when advertising Housing, Credit and Employment (only available for US)
limitinteger, 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

ParameterDefaultDescriptionPossible values
country_codeISO ALPHA-2 Country Code (lowercase)us
limitinteger, 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

AttributeDescriptionRequiredPossible Values
proximityProximity to selected location categoriesR
proximity_unitUnit to be used for radiusRMETERS (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

AttributeDescriptionRequiredPossible Values
latitudeLatitude in decimal degreesR
longitudeLongitude in decimal degreesR
radiusRadius in meters (minimum 96 meters and maximum 100000 meters)R
unitUnit to be used for radiusOMETERS (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

AttributeDescription
ad_squad_idThe 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

AttributeDescription
targeting_spec_idThe 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

AttributeDescription
ad_squad_idThe ID of the Ad Squad under which the Targeting Spec is being created

Attributes

AttributeDescriptionRequiredPossible Values
idThe ID of the Targeting Spec you wish to updateR
typeThe type of targeting, currently only GEORGEO
geosAn array containing a valid targeting spec for geosR
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"
}
]
}
}]
}
Was this page helpful?
Yes
No

AI-Powered Search