Skip to main content

Ad Squads

An Ad Squad is owned by a Campaign and contains one or more Ads.

Attributes

AttributeDescriptionRequiredPossible Values
campaign_idCampaign IDR
bid_microMax Bid (micro-currency)Rbid_micro is currency specific see Currency Specific bids for Mininum/Maximum value
billing_eventBilling EventRIMPRESSION
brand_safety_configBrand Safety Inventory FilterOSee Brand Safety Config section
child_ad_typeIndicates what Ad type the Ad Squad uses, if not set this value will be set automatically once an Ad has been added under the Ad Squad, at that point the attribute becomes immutableOSNAP_AD, LONGFORM_VIDEO, APP_INSTALL, REMOTE_WEBPAGE, DEEP_LINK, STORY, AD_TO_LENS, AD_TO_CALL, AD_TO_MESSAGE, FILTER, LENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_LONGFORM_VIDEO, COLLECTION
forced_view_settingIndicates the type of Commercial used by the Ad Squad. If this is set, all Creatives in the Ad Squad must have a forced_view_eligibility value of FULL_DURATION or SIX_SECONDS. If not set this value will be set automatically once a Creative with forced_view_eligibility is added to the Ad Squad, once this value is set it's immutableOFULL_DURATION, SIX_SECONDS
daily_budget_microDaily Budget (micro-currency)one of daily_budget_micro or lifetime_budget_micro must be setMinimum value 5000000 across all supported currencies
lifetime_budget_microLifetime budget (micro-currency)one of lifetime_budget_micro or daily_budget_micro must be set
end_timeEnd timeO
nameAd Squad name
max length: 375 characters
R
optimization_goalOptimization GoalRIMPRESSIONS, SWIPES, APP_INSTALLS, VIDEO_VIEWS, VIDEO_VIEWS_15_SEC, USES, STORY_OPENS, PIXEL_PAGE_VIEW, PIXEL_ADD_TO_CART, LANDING_PAGE_VIEW, PIXEL_PURCHASE, PIXEL_SIGNUP, APP_ADD_TO_CART, APP_PURCHASE, APP_SIGNUP, see Squad Optimization Goals
conversion_windowDelivery optimisation windowOSWIPE_28DAY_VIEW_1DAY (default), SWIPE_7DAY , see Delivery Optimization Windows
placement_v2PlacementRJson object containing advanced placement options See placement_v2
start_timeStart timeO
statusAd Squad statusOACTIVE, PAUSED
story_ad_creative_typeIndicates the type of Creative used in Dynamic Story Ads, required when using Dynamic Story AdsOAPP_INSTALL, WEB_VIEW, DEEP_LINK
targetingTargeting specR
typeAd Squad TypeRSNAP_ADS, LENS, FILTER
cap_and_exclusion_configThe frequency cap and exclusion specOIf this is set and the Ad Squad is inside of an Auction campaign, Multi-format Delivery cannot be used and all ads in the ad squad must be of the same ad type.
ad_scheduling_configThe schedule for running adsO
bid_strategyBidding strategy for this Ad SquadRAUTO_BID, LOWEST_COST_WITH_MAX_BID, MIN_ROAS, TARGET_COST, see bid_strategy
roas_value_microThe desired ROAS used with the MIN_ROAS BidStrategyR if BidStrategy = MIN_ROASMinimum value 10000 , Maximum value 100000000
pixel_idPixel to be associated with the Ad SquadO
measurement_provider_namesapproved measurement providerOMOAT_SS, DOUBLEVERIFY
reach_and_frequency_status**Status of the reach and frequency bookingRMust be set to PENDING which automatically updates to ACTIVE or FAILED after booking
delivery_constraintType of deliveryRDAILY_BUDGET (when using daily_budget_micro), LIFETIME_BUDGET (when using lifetime_budget_micro), REACH_AND_FREQUENCY**
reach_goal**Reach goal as specified in the Forecasting requestRMust match the value in the forecasting request
impression_goal**Reach goal as specified in the Forecasting requestRMust match the value in the forecasting request
pacing_typeType of pacingOSTANDARD (default), ACCELERATED
delivery_statusDelivery statusRead-onlySee Delivery status
event_sourcesSnap App Id to be associated with the Ad SquadO/Required when using SKAdnetwork enrollmentAvailble for Optimization Goals APP_REENGAGE_OPEN / APP_REENGAGE_PURCHASE and Dynamic Product Ads when using APP_INSTALL / DEEP_LINK
skadnetwork_properties.statusSKAdnetwork enrollment statusRead-onlyENROLLED, NEVER_ENROLLED, WITHDRAWN
deletedIndicates whether the entity has been deleted or not, only shown when using the parameter read_deleted_entitiesRead-onlytrue
separated_typesIndicates if a targeting spec type has been separated into the new "targeting_spec" entity.Read-only"separated_types": ["GEO"]

** See Reach And Frequency

Brand Safety Config

AttributeDescriptionRequiredPossible values
brand_safety_configDefines where ads are placed among Snapchat content. This attribute is mutable.Optional“inventory_option”:”FULL_INVENTORY” , “inventory_option”:”LIMITED_INVENTORY”

Validations - placement_v2

The brand_safety_config is only applied to Creator stories, this includes the following scenarios.

placement_v2.configplacement_v2.platformsplacement_v2.snapchat_positions
automatic--
customsnapchatPUBLIC_STORIES_INSTREAM

Behaviour - Brand Safety Config

ScenarioValueBehaviour
inventory_option is set to FULL_INVENTORYbrand_safety_config:{“inventory_option”: “FULL_INVENTORY”}Shows ads near any Snapchat content to maximise reach. Content still adheres to Snap's Community Guidelines and content moderation rules.
inventory_option is set to LIMITED_INVENTORYbrand_safety_config:{“inventory_option”: “LIMITED_INVENTORY”}Shows ads near content that has passed additional moderation filters. This may decrease reach and increse costs. Only avilable for Creator stories.
inventory_option is not defined on creation-Shows ads near any Snapchat content to maximise reach. Content still adheres to Snap's Community Guidelines and content moderation rules.

Example request

This request creates an Ad Squad with brand_safety_config:{“inventory_option”: “LIMITED_INVENTORY”}

cURL -X POST \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
-H 'Content-Type: application/json' \
'https://adsapi.snapchat.com/v1/campaigns/127c9fa9-8059-4a45-b81a-59125053b740/adsquads' \
-D '{
"adsquads": [
{
"name": "Badger Tunneling Campaign with Brand Safety LIMITED",
"status": "ACTIVE",
"campaign_id": "127c9fa9-8059-4a45-b81a-59125053b740",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"min_age": "18"
}
],
"geos": [
{
"country_code": "us"
}
]
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 20000,
"auto_bid": false,
"target_bid": false,
"bid_strategy": "LOWEST_COST_WITH_MAX_BID",
"lifetime_budget_micro": 100000000000,
"start_time": "2023-11-28T14:35:55.000Z",
"end_time": "2024-02-22T14:35:55.000Z",
"optimization_goal": "IMPRESSIONS",
"pixel_id": "7eda10b7-a5fe-4ac6-80f4-417e68d748fb",
"pacing_type": "STANDARD",
"brand_safety_config": {
"inventory_option": "LIMITED_INVENTORY"
}
}
]
}

Example response

{
"request_status": "SUCCESS",
"request_id": "fd5a9158-3408-4ee2-8441-44db3b841418",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "d6317370-b7ef-4a16-9a9b-a194260e728d",
"updated_at": "2024-09-12T10:19:59.008Z",
"created_at": "2024-09-12T10:19:59.008Z",
"name": "Badger Tunneling Campaign with Brand Safety LIMITED",
"status": "ACTIVE",
"campaign_id": "127c9fa9-8059-4a45-b81a-59125053b740",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"min_age": "18"
}
],
"geos": [
{
"country_code": "us"
}
],
"enable_targeting_expansion": true,
"auto_expansion_options": {
"interest_expansion_option": {
"enabled": true
},
"custom_audience_expansion_option": {
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 20000,
"auto_bid": false,
"target_bid": false,
"bid_strategy": "LOWEST_COST_WITH_MAX_BID",
"lifetime_budget_micro": 100000000000,
"start_time": "2023-11-28T14:35:55.000Z",
"end_time": "2024-02-22T14:35:55.000Z",
"optimization_goal": "IMPRESSIONS",
"pixel_id": "7eda10b7-a5fe-4ac6-80f4-417e68d748fb",
"delivery_constraint": "LIFETIME_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED",
"delivery_status": [
"INVALID_END_TIME",
"INVALID_EFFECTIVE_INVALID"
],
"skadnetwork_properties": {
"status": "NEVER_ENROLLED"
},
"brand_safety_config": {
"inventory_option": "LIMITED_INVENTORY"
}
}
}
]
}

Currency specific bids

The minimum/maximum value of bid_micro is determined by the currency attribute which is set on the Ad Account entity. All values listed are in micro-currency.

ISO codeCurrencyMinimum (micro-currency)Maximum (micro-currency)
AEDUAE Dirham10,000500,000,000
AUDAustralian Dollar10,000100,000,000
BAMBosnian Mark10,000100,000,000
CADCanadian Dollar10,000100,000,000
CHFSwiss Franc10,000100,000,000
CNYChinese Yuan10,000500,000,000
DKKDanish Krone10,000500,000,000
EUREuro10,000100,000,000
GBPPound Sterling10,000100,000,000
HKDHong Kong Dollar10,000500,000,000
ILSIsraeli New Shekel10,000500,000,000
INRIndian Rupee10,000500,000,000
KWDKuwaiti Dinar10,000100,000,000
NOKNorwegian Krone10,000500,000,000
QARQatari Rial10,000500,000,000
SARSaudi Riyal10,000500,000,000
SEKSwedish Krona10,000500,000,000
USDUS Dollar10,000500,000,000

Multi-Format Delivery

It is possible to combine Ads of different types in the same Ad Squad with some restrictions.

  • They must have the same Goal-based Bidding optimization goal.
  • Dynamic Product Ads cannot be mixed with non-dynamic ad types.
  • Commercials cannot mixed with non-commercial ads.
  • Commercials using forced_view_eligibility with the value FULL_DURATION or SIX_SECONDS can mix in the same an Ad Squad.
  • Lens ads cannot be mixed with non-lens ad types.
  • Ad Squads that contain ads of multiple formats cannot enroll in SKAdNetwork tracking.
  • Ad Squads that contain ads of multiple formats do not support frequency capping using the cap_and_exclusion_config property if they are inside of Auction campaigns.

The rules governing Multi-Format Delivery are described further in the following sections.

Eligible Ad Squad Optimization Goals

If you use one of the following Goal-based Bidding optimization goals, you will be able to put multiple types of ads in an Ad Squad.

  • IMPRESSIONS
  • SWIPES
  • APP_INSTALLS
  • PIXEL_PURCHASE
  • PIXEL_SIGNUP
  • APP_PURCHASE
  • APP_REENGAGE_OPEN

Supported Ad Combinations

The following table shows which ad types can be combined in the same Ad Squad.

Ad NameAd TypeSupports Multi-Format Delivery?Notes
Snap Ads (attachment), Story Ad, Collection AdSNAP_AD, APP_INSTALL, REMOTE_WEBPAGE, DEEP_LINK, AD_TO_LENS, AD_TO_CALL, AD_TO_MESSAGE, LEAD_GEN, STORY, COLLECTIONYESSnap Ads with different attachment types, Story Ads and Collection Ads can be mixed in the same Ad Squad.

Story Ads run in between stories (no thumbnail) when targeted at INTERSTITIAL_USER or INTERSTITIAL_CONTENT
Dynamic Snap AdSNAP_AD, STORY, COLLECTIONYESDynamic Product Ads can be mixed with each other, cannot be mixed with non-dynamic Ad types.

DPA Ad are Creatives with render_type DYNAMIC
CommercialSNAP_AD, REMOTE_WEBPAGE, AD_TO_LENSYESCommercials can be mixed with each other, cannot be mixed with non-commercials.

Commercials are Creatives with forced_view_eligibility set to FULL_DURATION or SIX_SECONDS and targeted at Premium Content Bundles.
LensLENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINKYESLenses cannot be mixed with non-Lens Ad types.

List Ad Types in an Ad Squad

curl -X GET \
-H 'Authorization: Bearer meowmeowmeow' \
'https://adsapi.snapchat.com/v1/adsquads/67fb5af9-b95f-413e-a998-130b4b58caad/ad_squad_ad_restrictions'

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "6543215600ff04cc8908e19ab30001737e616473617069736300016275696c642d62333561306232372d312d3533332d3000123123",
"ad_squad_ad_restrictions": [
{
"sub_request_status": "SUCCESS",
"ad_squad_ad_restrictions": {
"id": "567890f9-b95f-413e-a998-130b4b765432",
"updated_at": "2022-04-15T19:10:19.220Z",
"created_at": "2021-12-07T01:18:19.226Z",
"ad_types": {
"SNAP_AD": 3,
"REMOTE_WEBPAGE": 1,
"STORY": 1
}
}
}
]
}

This API request fetches a summary of the Ad types currently in the Ad Squad. The list is found in the response's ad_types attribute.

HTTP Request

GET https://adsapi.snapchat.com/v1/adsquads/{{ad_squad_id}}/ad_squad_ad_restrictions

Parameters

ParameterDefaultDescription
ad_squad_idAd Squad

Multi-format Ad Squad Example 1

This is an example of an Ad Squad that contains a SNAP_AD, a STORY Ad, and a REMOTE_WEBSITE ad.

Example output from listing the ads in the ad squad

{
"request_status": "SUCCESS",
"request_id": "625f4f7500ff054633669e73350001737e616473617069736300016275696c642d66316366613233612d312d353312345697800110",
"paging": {},
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "2b3b55f3-ddf6-43e8-9f76-c74d94db5e2a",
"updated_at": "2022-04-19T07:53:07.943Z",
"created_at": "2022-04-15T01:03:28.845Z",
"effective_status": "PAUSED",
"name": "My Snap Ad",
"ad_squad_id": "654321ab-b95f-413e-a998-12345678xyza",
"creative_id": "ee9a155d-0883-4888-aa25-3d7375yu5432",
"status": "ACTIVE",
"type": "SNAP_AD",
"render_type": "STATIC",

...

[[snip]]

...

}
},
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "3fbc4a8d-61f1-4a50-8327-b68a4d7042d6",
"updated_at": "2022-04-19T07:40:06.541Z",
"created_at": "2022-04-15T01:01:55.315Z",
"effective_status": "PAUSED",
"name": "My Story Ad",
"ad_squad_id": "654321ab-b95f-413e-a998-12345678xyza",
"creative_id": "f2afa2cd-799c-4848-8f71-192830jkf1211",
"status": "ACTIVE",
"type": "STORY",
"render_type": "STATIC",

...

[[snip]]

...
}
},
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "7976e781-ddc1-4f4f-80e4-82d91d3d596e",
"updated_at": "2022-04-19T08:14:47.629Z",
"created_at": "2022-04-15T19:10:19.174Z",
"effective_status": "PAUSED",
"name": "My Website Ad",
"ad_squad_id": "654321ab-b95f-413e-a998-12345678xyza",
"creative_id": "6fcc0703-c3e5-47ad-bf00-js82ks9102ec",
"status": "ACTIVE",
"type": "REMOTE_WEBPAGE",
"render_type": "STATIC",

...

[[snip]]

...
}
}
]
}

Multi-format Ad Squad Example 2

This is an example of an Ad Squad that contains a LENS ad and a LENS_REMOTE_WEBPAGE ad.

Example output from listing the ads in the ad squad

{
"request_status": "SUCCESS",
"request_id": "6yh2781920ff01d69c4f55568e0001737e616473617069736300016275696c642d66316366613233612d312d3533342d392k287620",
"paging": {},
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "87654231-a083-48bd-bda1-776b3944308e",
"updated_at": "2022-04-16T07:06:46.062Z",
"created_at": "2022-04-15T21:52:22.942Z",
"name": "test lens ad no attachment",
"ad_squad_id": "6543610c-9e8e-4b28-86b8-40acc2f4abcd",
"creative_id": "ed2eaf37-515d-4a54-bf6b-113j827d6543",
"status": "PAUSED",
"type": "LENS",
"render_type": "STATIC"

...

[[snip]]

...

}
},
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "12349876-cbad-42da-8f57-091416cd75ed",
"updated_at": "2022-04-20T00:53:59.890Z",
"created_at": "2022-04-20T00:53:59.545Z",
"name": "test lens remote webpage",
"ad_squad_id": "6543610c-9e8e-4b28-86b8-40acc2f4abcd",
"creative_id": "7684b71d-ec74-4de6-b1bd-c32abcdh7usi",
"status": "ACTIVE",
"type": "LENS_REMOTE_WEBPAGE",
"render_type": "STATIC",

...

[[snip]]

...
}
}
]
}

Event sources

Example request setting the event_sources to Snap App ID

curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adsquads": [{"id": "7e52b0f4-a3fc-46f2-9a33-f03d71c55047","name": "Badger Supplies Ad Squad","status": "ACTIVE","campaign_id": "7b15f643-3052-4eb3-b5e1-09fa1ce0116a","type": "SNAP_ADS","targeting": {"regulated_content": false,"geos": [{"country_code": "uk"}],"devices": [{"os_type": "iOS"}],"auto_expansion_options":{"interest_expansion_option":{"enabled": true},"custom_audience_expansion_option":{"enabled": true}}},"placement_v2": {"config": "AUTOMATIC"},"billing_event": "IMPRESSION","bid_strategy": "AUTO_BID","daily_budget_micro": 50000000,"start_time": "2021-11-01T17:12:49.707Z","end_time": "2021-12-01T17:12:49.707Z","optimization_goal": "SWIPES","event_sources": {"MOBILE_APP": ["8b5b83ec-c593-4a64-9c6d-a0eb9da0edb8"]}}]}'
https://adsapi.snapchat.com/v1/campaigns/88539b6b-93f2-4b3a-8181-ca869cb45088/adsquads

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "6011886c00ff09fe1978d146130001737e616473617069736300016275696c642d65386534326330362d312d3431372d3000010113",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "7e52b0f4-a3fc-46f2-9a33-f03d71c55047",
"updated_at": "2021-01-27T15:36:13.676Z",
"created_at": "2020-11-11T10:24:46.334Z",
"name": "Badger Supplies Ad Squad",
"status": "ACTIVE",
"campaign_id": "7b15f643-3052-4eb3-b5e1-09fa1ce0116a",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"geos": [
{
"country_code": "uk"
}
],
"devices": [
{
"os_type": "iOS"
}
],
"auto_expansion_options": {
"interest_expansion_option": {
"enabled": true
},
"custom_audience_expansion_option": {
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-11-01T17:12:49.707Z",
"end_time": "2021-12-01T17:12:49.707Z",
"optimization_goal": "SWIPES",
"event_sources": {
"MOBILE_APP": ["8b5b83ec-c593-4a64-9c6d-a0eb9da0edb8"]
},
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED"
}
}
]
}

The event_sources attribute defines a Snap App ID which is associated with the Ad Squad, events triggered by the App will be eligible for conversions and can also used to set up Mobile custom audiences. It is recommended that you add event_sources to any Ad Squad using the optimization goals APP_INSTALLS or DEEP_LINK.

The event_sources attribute is a prerequisite for App Install state targeting.

SKAdNetwork tracking

SKAdNetwork upcoming changes

On the 7 September 2022 we are making the following changes to SKAd tracking.

  • Opting an Ad Squad into SKAd tracking will only be possible at the point of creation (see existing example)
  • After the 7 September we are deprecating the ability to opt in an existing Ad Squad into SKAd tracking by means of updating it (see existing example)
  • After the 7 September we are deprecating the ability to opt out an Ad Squad out of SKAd tracking by means of updating it (see existing example)
  • You can withdraw an opted-in Ad Squad from SKAd tracking by pausing it and detaching the Apple Campaign ID using the newly introduced ecid_enroll_action, this will free up the Campaign ID for use in a different Ad Squad (see new example)
  • You can re-enable an Ad Squad into SKAd tracking by updating the ecid_enroll_action to attach an Apple Campaign ID and unpausing the Ad Squad (see new example).
  • In addition to the method that checks if an Apple Campaign ID is available, we have now introduced a new method that lists all Ad Squads that are visible to you that have an Apple Campaign ID attached to them.

SKAdNetwork prerequisites & restrictions

SKAdNetwork prerequisites

Enrolling your Ad Squad into SKAdnetwork attribution has a number of prerequisites:

  1. A Snap App ID has been set up, the iOS App ID has been added and verified, this can be checked by fetching the App with the Snap App ID and reading the attribute ios_app_id_verified, read more about the Snap App ID.
  2. A SKAdnetwork Campaign ID is available for the Snap App ID.
  3. The Ad Squad has the attribute event_sources set to the Snap App ID and is targeting only iOS devices.

SKAdNetwork restrictions

Ad Squads that are enrolled into SKAdNetwork tracking are subject to the following restrictions:

  • The Optimization goals (optimization_goal) APP_REENGAGE_OPEN and APP_REENGAGE_PURCHASE are not available.
  • The bid strategies (bid_strategy) MIN_ROAS and TARGET_COST are not available.
  • Ad Squads that are delivering ads of multiple formats cannot enroll in SKAdNetwork.

SKAdNetwork Campaign ID check

curl "https://adsapi.snapchat.com/v1/mobile_apps/fb5b83ec-c593-4a64-9c6d-a0eb9da0edba/ecid_status"
-H "Authorization: Bearer meowmeowmeow"

Example - checking SKAdnetwork campaign id availability

{
"request_status": "SUCCESS",
"request_id": "6000ff63ae00ff0aca494709c9440001737e616473617069736300016275696c642d32396339353666662d312d3431332d3100010117",
"ecid_status": "AVAILABLE_IN_GRACE_PERIOD"
}

Before you can create an Ad Squad which is opted into SKAdnetwork tracking you should carry out a check to find out the status of available Apple Campaign IDs (ecid) for the App in question. The response will inidcate whether there is a free Apple Campaign ID and the status which it is currently in.

An App is limited to 38 simultaneously live Ad sets that can be measured through the SKAdNetwork, you should allow for a cool-down period between uses of the same Apple Campaign ID to ensure clean reporting of your conversions.

SKAdnetwork Campaign ID status

ecid_statusDescription
AVAILABLEThere is at least one available App Campaign ID
AVAILABLE_IN_GRACE_PERIODAn Apple Campaign ID is available but was recently attached to another campaign, some conversions might get attributed to the new Campagin for the next 48 hours
NOT_AVAILABLEThere is no available Apple Campaign ID

HTTP Request

GET https://adsapi.snapchat.com/v1/mobile_apps/{snap_app_id}/ecid_status

Parameters

ParameterDefaultDescription
snap_app_idSnap App ID

SKAdnetwork enrollment

If all the prerequisites are met an Ad Squad can be enrolled into SKAdnetwork tracking, this can happen by creating a new Ad Squad that is enrolled on creation.

AttributeDescriptionPossible Values
placement_v2Placement for the AdsPlacement V2

SKAdnetwork AdSquad ecid status check

curl "https://adsapi.snapchat.com/v1/mobile_apps/c1e6e929-acec-466f-b023-852b8cacc18f/skadnetwork_adsquads" \
-H "Authorization: Bearer meowmeowmeow"

Example - checking all AdSquads currently assigned an Apple Campaign ID

{
"request_status": "SUCCESS",
"request_id": "62730c8b00ff0c935616bdb0930001737e7465616d6b6f363139000161646d616e616765722d6170693a776e75636b6f6c737465737400010154",
"ad_squads": [
{
"ad_squad_id": "2b985a73-eef7-4532-a64c-4b5b898666aa",
"ad_squad_name": "United States, All Genders, All Ages",
"ad_squad_status": "ACTIVE",
"ecid_status": "NOT_AVAILABLE",
"ad_account_id": "1703100d-cc15-4857-b8bf-dfb590f33999"
},
{
"ad_squad_id": "7fde64a5-936c-4ca8-b841-6d865b4ee929",
"ad_squad_name": "United States, All Genders, All Ages",
"ad_squad_status": "ACTIVE",
"ecid_status": "NOT_AVAILABLE",
"ad_account_id": "1703100d-cc15-4857-b8bf-dfb590f33999"
},
{
"ad_squad_id": "75a5de36-bcc0-4eae-a440-495e3b335d1b",
"ad_squad_name": "United States, All Genders, All Ages - a",
"ad_squad_status": "PAUSED",
"ecid_status": "AVAILABLE_IN_GRACE_PERIOD",
"ad_account_id": "2ac22383-6e7e-4134-83a3-299f1e2a05db"
},
{
"ad_squad_id": "42eb60be-91bd-4a9d-9ed0-806b550638b5",
"ad_squad_name": "United States, All Genders, All Ages",
"ad_squad_status": "ACTIVE",
"ecid_status": "NOT_AVAILABLE",
"ad_account_id": "2ac22383-6e7e-4134-83a3-299f1e2a05db"
},
{
"ad_squad_id": "0cb8390a-4c63-4cae-a6df-c77d1405546e",
"ad_squad_name": "United States, All Genders, All Ages",
"ad_squad_status": "PAUSED",
"ecid_status": "AVAILABLE_IN_GRACE_PERIOD",
"ad_account_id": "1703100d-cc15-4857-b8bf-dfb590f33999"
},
{
"ad_squad_id": "f3827145-dd9e-47d0-b57b-a2ad0eab4068",
"ad_squad_name": "United States, All Genders, All Ages",
"ad_squad_status": "ACTIVE",
"ecid_status": "NOT_AVAILABLE",
"ad_account_id": "1703100d-cc15-4857-b8bf-dfb590f33999"
},
{
"ad_squad_id": "f750048e-a1c4-4b50-979f-4d1fda2ea7d4",
"ad_squad_name": "United States, All Genders, All Ages",
"ad_squad_status": "ACTIVE",
"ecid_status": "NOT_AVAILABLE",
"ad_account_id": "2ac22383-6e7e-4134-83a3-299f1e2a05db"
},
{
"ad_squad_id": "4f579fce-9a65-4ba5-84d6-a475326b1796",
"ad_squad_name": "United States, All Genders, All Ages",
"ad_squad_status": "ACTIVE",
"ecid_status": "NOT_AVAILABLE",
"ad_account_id": "2ac22383-6e7e-4134-83a3-299f1e2a05db"
},
{
"ad_squad_id": "33773acc-c0af-49d7-846f-1d67325a400d",
"ad_squad_name": "United States, All Genders, All Ages - a",
"ad_squad_status": "PAUSED",
"ecid_status": "AVAILABLE_IN_GRACE_PERIOD",
"ad_account_id": "2ac22383-6e7e-4134-83a3-299f1e2a05db"
},
{
"ad_squad_id": "55b3c4c0-2406-4a37-b610-92951bb642a6",
"ad_squad_name": "United States, All Genders, All Ages",
"ad_squad_status": "ACTIVE",
"ecid_status": "NOT_AVAILABLE",
"ad_account_id": "2ac22383-6e7e-4134-83a3-299f1e2a05db"
},
{
"ad_squad_id": "bb5fb714-1d3c-4638-8e54-7320ab5ff81a",
"ad_squad_name": "United States, All Genders, All Ages",
"ad_squad_status": "ACTIVE",
"ecid_status": "NOT_AVAILABLE",
"ad_account_id": "1703100d-cc15-4857-b8bf-dfb590f33999"
}
]
}

This method returns a list of all Ad Squads that are using an Apple Campaign Id (ecid) for the Snap App ID in question.

The response returns the status of that Campaign Id, the status can be either NOT_AVAILABLE or AVAILABLE_IN_GRACE_PERIOD. Since Apple Campaign IDs are platform wide, you may not have permission to see all Ad Squads that are assigned an Apple Campaign ID.

Once an Apple Campaign ID has come out of it’s cool-down period it’s no longer associated with an Ad Squad and is no longer visible in the response of this request.

SKAdnetwork AdSquad status

ecid_statusDescription
AVAILABLE_IN_GRACE_PERIODThe Apple Campaign ID attached to this AdSquad is in a cooldown period, if used some conversions might get attributed to the new Campagin for the next 48 hours
NOT_AVAILABLEThis AdSquad has an Apple Campaign ID attached to it

HTTP Request

GET https://adsapi.snapchat.com/v1/mobile_apps/{{mobile_app_id}}/skadnetwork_adsquads

Parameters

ParameterDefaultDescription
snap_app_idSnap App ID

SKAdnetwork example 1

SKAdNetwork enrollement by updating an Ad Squad

Example - Updating an Ad Squad to be enrolled in the SKAdnetwork tracking

curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adsquads":[{"id":"1b99bd80-5279-41c1-9d8d-e28875d7e7dd","name":"SKAdNetwork Example - Opt in","status":"ACTIVE","campaign_id":"46fb184a-d371-49f0-8384-ea533cef217a","type":"SNAP_ADS","targeting":{"regulated_content":false,"demographics":[{"min_age":"21","max_age":"24"}],"geos":[{"country_code":"us"}],"devices":[{"os_type":"iOS","os_version_min":"11.3"}]},"targeting_reach_status":"VALID","placement_v2":{"config":"AUTOMATIC"},"billing_event":"IMPRESSION","bid_micro":200000000,"auto_bid":false,"target_bid":false,"bid_strategy":"LOWEST_COST_WITH_MAX_BID","daily_budget_micro":2000000000,"start_time":"2021-08-15T19:16:17.444Z","end_time":"2021-08-19T19:16:17.444Z","optimization_goal":"APP_INSTALLS","event_sources":{"MOBILE_APP":["fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"]},"skadnetwork_properties":{"enroll_action":"OPT_IN"}}]}'
https://adsapi.snapchat.com/v1/campaigns/46fb184a-d371-49f0-8384-ea533cef217a/adsquads

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "6006dd1400ff04d29d47769a7c0001737e616473617069736300016275696c642d34343839623532342d312d3431342d3000010141",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "1b99bd80-5279-41c1-9d8d-e28875d7e7dd",
"updated_at": "2021-01-19T13:22:29.264Z",
"created_at": "2021-01-15T13:46:43.768Z",
"created_by_app_id": "ff503f30-8e94-450b-abac-18e3e25a8da1",
"created_by_user": "82beca53-2402-45f6-bc0f-1244a2cb8936",
"name": "SKAdNetwork Example - Opt in",
"status": "ACTIVE",
"campaign_id": "46fb184a-d371-49f0-8384-ea533cef217a",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"min_age": "21",
"max_age": "24"
}
],
"geos": [
{
"country_code": "us"
}
],
"devices": [
{
"os_type": "iOS",
"os_version_min": "11.3"
}
]
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 200000000,
"auto_bid": false,
"target_bid": false,
"bid_strategy": "LOWEST_COST_WITH_MAX_BID",
"daily_budget_micro": 2000000000,
"start_time": "2021-08-15T19:16:17.444Z",
"end_time": "2021-08-19T19:16:17.444Z",
"optimization_goal": "APP_INSTALLS",
"event_sources": {
"MOBILE_APP": ["fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"]
},
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED",
"delivery_status": [
"INVALID_START_TIME",
"INVALID_NOT_EFFECTIVE_ACTIVE",
"INVALID_EFFECTIVE_INVALID"
],
"skadnetwork_properties": {
"status": "ENROLLED"
}
}
}
]
}

By updating the Ad Squad and including the attribute enroll_action with the value OPT_IN the Ad Squad will be enrolled into SKAdnetwork tracking.

skadnetwork_properties":{"enroll_action":"OPT_IN"}}]}

SKAdnetwork example 2

SKAdNetwork withdrawal by updating an Ad Squad

Example - Updating an Ad Squad to be withdrawn from the SKAdnetwork tracking

curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adsquads":[{"id":"1b99bd80-5279-41c1-9d8d-e28875d7e7dd","name":"SKAdNetwork Example - Opt out","status":"ACTIVE","campaign_id":"46fb184a-d371-49f0-8384-ea533cef217a","type":"SNAP_ADS","targeting":{"regulated_content":false,"demographics":[{"min_age":"21","max_age":"24"}],"geos":[{"country_code":"us"}],"devices":[{"os_type":"iOS","os_version_min":"11.3"}]},"targeting_reach_status":"VALID","placement_v2":{"config":"AUTOMATIC"},"billing_event":"IMPRESSION","bid_micro":200000000,"auto_bid":false,"target_bid":false,"bid_strategy":"LOWEST_COST_WITH_MAX_BID","daily_budget_micro":2000000000,"start_time":"2021-08-15T19:16:17.444Z","end_time":"2021-08-19T19:16:17.444Z","optimization_goal":"APP_INSTALLS","event_sources":{"MOBILE_APP":["fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"]},"skadnetwork_properties":{"enroll_action":"OPT_OUT"}}]}'
https://adsapi.snapchat.com/v1/campaigns/46fb184a-d371-49f0-8384-ea533cef217a/adsquads

By updating the Ad Squad and including the attribute enroll_action with the value OPT_OUT the Ad Squad will be withdrawn from SKAdnetwork tracking.

skadnetwork_properties":{"enroll_action":"OPT_OUT"}}]}

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "6006dd1400ff04d29d47769a7c0001737e616473617069736300016275696c642d34343839623532342d312d3431342d3000010141",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "1b99bd80-5279-41c1-9d8d-e28875d7e7dd",
"updated_at": "2021-01-19T13:22:29.264Z",
"created_at": "2021-01-15T13:46:43.768Z",
"created_by_app_id": "ff503f30-8e94-450b-abac-18e3e25a8da1",
"created_by_user": "82beca53-2402-45f6-bc0f-1244a2cb8936",
"name": "SKAdNetwork Example - Opt out",
"status": "ACTIVE",
"campaign_id": "46fb184a-d371-49f0-8384-ea533cef217a",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"min_age": "21",
"max_age": "24"
}
],
"geos": [
{
"country_code": "us"
}
],
"devices": [
{
"os_type": "iOS",
"os_version_min": "11.3"
}
]
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 200000000,
"auto_bid": false,
"target_bid": false,
"bid_strategy": "LOWEST_COST_WITH_MAX_BID",
"daily_budget_micro": 2000000000,
"start_time": "2021-08-15T19:16:17.444Z",
"end_time": "2021-08-19T19:16:17.444Z",
"optimization_goal": "APP_INSTALLS",
"event_sources": {
"MOBILE_APP": ["fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"]
},
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED",
"delivery_status": [
"INVALID_START_TIME",
"INVALID_NOT_EFFECTIVE_ACTIVE",
"INVALID_EFFECTIVE_INVALID"
],
"skadnetwork_properties": {
"status": "WITHDRAWN"
}
}
}
]
}

SKAdnetwork example 3

SKAdNetwork enrollement at Ad Squad creation

Example - Updating an Ad Squad to be enrolled in the SKAdnetwork tracking

curl -X POST \
-d '{"adsquads":[{"name":"SKAdNetwork Example - Creation Opt in","status":"ACTIVE","campaign_id":"46fb184a-d371-49f0-8384-ea533cef217a","bid_micro":"200000000","bid_strategy":"LOWEST_COST_WITH_MAX_BID","daily_budget_micro":"2000000000","start_time":"2021-08-15T12:16:17.444-07:00","end_time":"2021-08-19T12:16:17.444-07:00","optimization_goal":"APP_INSTALLS","event_sources":{"MOBILE_APP":["fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"]},"skadnetwork_properties":{"enroll_action":"OPT_IN"},"placement_v2":{"config":"AUTOMATIC"},"targeting":{"regulated_content":"false","demographics":[{"min_age":"21","max_age":"24"}],"geos":[{"country_code":"us"}],"devices":[{"os_type":"iOS"},"os_version_min":"11.3"]}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/campaigns/46fb184a-d371-49f0-8384-ea533cef217a/adsquads

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "6006dd1400ff04d29d47769a7c0001737e616473617069736300016275696c642d34343839623532342d312d3431342d3000010141",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "1b99bd80-5279-41c1-9d8d-e28875d7e7dd",
"updated_at": "2021-01-19T13:22:29.264Z",
"created_at": "2021-01-15T13:46:43.768Z",
"name": "SKAdNetwork Example - Creation Opt in",
"status": "ACTIVE",
"campaign_id": "46fb184a-d371-49f0-8384-ea533cef217a",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"min_age": "21",
"max_age": "24"
}
],
"geos": [
{
"country_code": "us"
}
],
"devices": [
{
"os_type": "iOS",
"os_version_min": "11.3"
}
]
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 200000000,
"auto_bid": false,
"target_bid": false,
"bid_strategy": "LOWEST_COST_WITH_MAX_BID",
"daily_budget_micro": 2000000000,
"start_time": "2021-08-15T19:16:17.444Z",
"end_time": "2021-08-19T19:16:17.444Z",
"optimization_goal": "APP_INSTALLS",
"event_sources": {
"MOBILE_APP": ["fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"]
},
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED",
"delivery_status": [
"INVALID_START_TIME",
"INVALID_NOT_EFFECTIVE_ACTIVE",
"INVALID_EFFECTIVE_INVALID"
],
"skadnetwork_properties": {
"status": "ENROLLED"
}
}
}
]
}

By creating an Ad Squad and including the attribute enroll_action with the value OPT_IN the Ad Squad will be enrolled into SKAdnetwork tracking, but this assumes an Apple Campaign ID is vailable.

skadnetwork_properties":{"enroll_action":"OPT_IN"}}]}

SKAdnetwork example 4

SKAdNetwork detaching an Apple Campaign ID

Example - detaching an Apple Campaign ID (ecid)

curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adsquads":[{"id":"1b99bd80-5279-41c1-9d8d-e28875d7e7dd","name":"SKAdNetwork Example - ECID Detach","status":"PAUSED","campaign_id":"46fb184a-d371-49f0-8384-ea533cef217a","type":"SNAP_ADS","targeting":{"regulated_content":false,"demographics":[{"min_age":"21","max_age":"24"}],"geos":[{"country_code":"us"}],"devices":[{"os_type":"iOS","os_version_min":"11.3"}]},"targeting_reach_status":"VALID","placement_v2":{"config":"AUTOMATIC"},"billing_event":"IMPRESSION","bid_micro":200000000,"auto_bid":false,"target_bid":false,"bid_strategy":"LOWEST_COST_WITH_MAX_BID","daily_budget_micro":2000000000,"start_time":"2021-08-15T19:16:17.444Z","end_time":"2021-08-19T19:16:17.444Z","optimization_goal":"APP_INSTALLS","event_sources":{"MOBILE_APP":["fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"]},"skadnetwork_properties":{"ecid_enroll_action":"DETACH"}}]}'
https://adsapi.snapchat.com/v1/campaigns/46fb184a-d371-49f0-8384-ea533cef217a/adsquads

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "6006dd1400ff04d29d47769a7c0001737e616473617069736300016275696c642d34343839623532342d312d3431342d3000010141",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "1b99bd80-5279-41c1-9d8d-e28875d7e7dd",
"updated_at": "2021-01-19T13:22:29.264Z",
"created_at": "2021-01-15T13:46:43.768Z",
"name": "SKAdNetwork Example - ECID Detach",
"status": "ACTIVE",
"campaign_id": "46fb184a-d371-49f0-8384-ea533cef217a",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"min_age": "21",
"max_age": "24"
}
],
"geos": [
{
"country_code": "us"
}
],
"devices": [
{
"os_type": "iOS",
"os_version_min": "11.3"
}
]
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 200000000,
"auto_bid": false,
"target_bid": false,
"bid_strategy": "LOWEST_COST_WITH_MAX_BID",
"daily_budget_micro": 2000000000,
"start_time": "2021-08-15T19:16:17.444Z",
"end_time": "2021-08-19T19:16:17.444Z",
"optimization_goal": "APP_INSTALLS",
"event_sources": {
"MOBILE_APP": ["fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"]
},
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED",
"delivery_status": [
"INVALID_START_TIME",
"INVALID_NOT_EFFECTIVE_ACTIVE",
"INVALID_EFFECTIVE_INVALID"
],
"skadnetwork_properties": {
"status": "ENROLLED",
"ecid_enrollment_status": "DETACHED"
}
}
}
]
}

To detach an Apple Campaign ID from an Opted-in Ad Squad in order to free it up for use elsewhere you will need to detach the Apple Campaign ID and pause the Ad Squad in question.

You can detach the Campaign ID via ecid_enroll_action and so withdraw the Ad Squad from SKAd tracking, it's possible to set the Ad Squad to paused and to detach the Campaign ID with the same API request. Note that it's not possible to set an Ad Squad live once the Apple Campaign ID has been detached.

“skadnetwork_properties”:{“ecid_enroll_action”:”DETACH”}

SKAdnetwork example 5

SKAdNetwork re-attaching an Apple Campaign ID

Example - Re-attaching an Apple Campaign ID (ecid)

curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adsquads":[{"id":"1b99bd80-5279-41c1-9d8d-e28875d7e7dd","name":"SKAdNetwork Example - ECID attach","status":"ACTIVE","campaign_id":"46fb184a-d371-49f0-8384-ea533cef217a","type":"SNAP_ADS","targeting":{"regulated_content":false,"demographics":[{"min_age":"21","max_age":"24"}],"geos":[{"country_code":"us"}],"devices":[{"os_type":"iOS","os_version_min":"11.3"}]},"targeting_reach_status":"VALID","placement_v2":{"config":"AUTOMATIC"},"billing_event":"IMPRESSION","bid_micro":200000000,"auto_bid":false,"target_bid":false,"bid_strategy":"LOWEST_COST_WITH_MAX_BID","daily_budget_micro":2000000000,"start_time":"2021-08-15T19:16:17.444Z","end_time":"2021-08-19T19:16:17.444Z","optimization_goal":"APP_INSTALLS","event_sources":{"MOBILE_APP":["fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"]},"skadnetwork_properties":{"ecid_enroll_action":"ATTACH"}}]}'
https://adsapi.snapchat.com/v1/campaigns/46fb184a-d371-49f0-8384-ea533cef217a/adsquads

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "6006dd1400ff04d29d47769a7c0001737e616473617069736300016275696c642d34343839623532342d312d3431342d3000010141",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "1b99bd80-5279-41c1-9d8d-e28875d7e7dd",
"updated_at": "2021-01-19T13:22:29.264Z",
"created_at": "2021-01-15T13:46:43.768Z",
"name": "SKAdNetwork Example - ECID attach",
"status": "ACTIVE",
"campaign_id": "46fb184a-d371-49f0-8384-ea533cef217a",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"min_age": "21",
"max_age": "24"
}
],
"geos": [
{
"country_code": "us"
}
],
"devices": [
{
"os_type": "iOS",
"os_version_min": "11.3"
}
]
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 200000000,
"auto_bid": false,
"target_bid": false,
"bid_strategy": "LOWEST_COST_WITH_MAX_BID",
"daily_budget_micro": 2000000000,
"start_time": "2021-08-15T19:16:17.444Z",
"end_time": "2021-08-19T19:16:17.444Z",
"optimization_goal": "APP_INSTALLS",
"event_sources": {
"MOBILE_APP": ["fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"]
},
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED",
"delivery_status": [
"INVALID_START_TIME",
"INVALID_NOT_EFFECTIVE_ACTIVE",
"INVALID_EFFECTIVE_INVALID"
],
"skadnetwork_properties": {
"status": "ENROLLED",
"ecid_enrollment_status": "ATTACHED"
}
}
}
]
}

To re-enable a withdrawn Ad Squad into SKAdnetwork tracking again you need to attach a free Apple Campaign ID (ecid) to the Ad Squad.

The two methods SKAdNetwork Campaign ID check and SKAdNetwork AdSquad ecid status check will allow you to find out if a Campaign ID is available, or if you need to free one up by detaching it from an AdSquad.

Once you have a free Campaign ID you can attach it by updating the Ad Squad using the ecid_enroll_action

“skadnetwork_properties”:{“ecid_enroll_action”:”ATTACH”}

Bid Strategy

Example request setting bid_strategy and bid_micro

curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adsquads":[{"id": "9077bb86-fb9a-4ded-9da9-67bc2e1dd6c5","name": "Badger Supplies Ad Squad - event sources","status": "ACTIVE","campaign_id": "4813d068-370b-45f6-a8d6-e01de878f1b5","type": "SNAP_ADS","targeting": {"regulated_content": false,"geos": [{"country_code": "uk"}],"devices": [{"os_type": "ANDROID"}],"auto_expansion_options":{"interest_expansion_option":{"enabled": true},"custom_audience_expansion_option":{"enabled": true}}},"placement_v2": {"config": "AUTOMATIC"},"bid_micro": 1000000,"bid_strategy": "TARGET_COST","daily_budget_micro": 50000000,"start_time": "2021-01-30T23:43:45.000Z","end_time": "2021-02-08T07:59:59.000Z","optimization_goal": "APP_INSTALLS","event_sources": {"MOBILE_APP": ["9b5b83ec-c593-4a64-9c6d-a0eb9da0edb9"]}}]}'
https://adsapi.snapchat.com/v1/campaigns/4813d068-370b-45f6-a8d6-e01de878f1b5/adsquads

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "60118f4f00ff026a940c321500ff0001737e616473617069736300016275696c642d65386534326330362d312d3431372d3000010143",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "9077bb86-fb9a-4ded-9da9-67bc2e1dd6c5",
"updated_at": "2021-01-27T16:05:35.770Z",
"created_at": "2021-01-27T16:03:14.293Z",
"name": "Badger Supplies Ad Squad - event sources",
"status": "ACTIVE",
"campaign_id": "4813d068-370b-45f6-a8d6-e01de878f1b5",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"geos": [
{
"country_code": "uk"
}
],
"devices": [
{
"os_type": "ANDROID"
}
],
"auto_expansion_options": {
"interest_expansion_option": {
"enabled": true
},
"custom_audience_expansion_option": {
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 1000000,
"auto_bid": false,
"target_bid": true,
"bid_strategy": "TARGET_COST",
"daily_budget_micro": 50000000,
"start_time": "2021-01-30T23:43:45.000Z",
"end_time": "2021-02-08T07:59:59.000Z",
"optimization_goal": "APP_INSTALLS",
"event_sources": {
"MOBILE_APP": ["9b5b83ec-c593-4a64-9c6d-a0eb9da0edb9"]
},
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED"
}
}
]
}

On the 20th of March 2020 we announced the deprecation of the attributes auto_bid and target_bid, please ensure that you have switched to using only bid_strategy by the 20th of June 2020. Creation of AdSquads and updating of AdSquads should only use the bid_strategy attribute.

The API will return the attributes auto_bid/target_bid when requesting the AdSquad entity but these attributes should be stripped out for any update AdSquad requests you make or the API will reject your requests come the 20th June 2020.

The below table outlines the relationship between the old bid settings and bid_strategy.

auto_bidtarget_bidbid_microbid_strategy
truefalse-----AUTO_BID
falsefalseused for bidLOWEST_COST_WITH_MAX_BID
falsetrueused for bidTARGET_COST

The bid_strategy attribute defines the bid strategy used for the Ad Squad, bid_strategy is an enumeration field which should be set to the bidding strategy of your choice, given the below options.

bid_strategyDescriptionAdditional Settings
AUTO_BIDDrive the most efficient cost per action while spending your budget-----
LOWEST_COST_WITH_MAX_BIDBids conservatively at or below your desired biduse bid_micro to set bid
MIN_ROAS**Achieves the most purchase value while maintaining a minimum return on your ad spend, this strategy requires that that APP_PURCHASE event along with the price parameter has been implementeduse roas_value_micro to set minimum ROAS in micro currency, one full unit of a currency in roas_value_micro represents a ROAS of 1, roas_value_micro value can be set between 10000 and a maximum of 100000000.
TARGET_COSTAchieves the most volume while aiming to keep your average cost per action below your target costuse bid_micro to set bid

** The MIN_ROAS bid strategy requires 50 PURCHASE conversions within 7 days, the price parameter needs to be passed with the PURCHASE event and there needs to be at least 3 unique price values.

Optimization Goals allowed per Bid Strategy.

bid_strategyOptimization goals
AUTO_BIDAPP_INSTALLS, IMPRESSIONS, STORY_OPENS, SWIPES, USES, VIDEO_VIEWS, VIDEO_VIEWS_15_SEC, PIXEL_PURCHASE, PIXEL_SIGNUP, PIXEL_PAGE_VIEW, PIXEL_ADD_TO_CART, APP_PURCHASE, APP_SIGNUP, APP_ADD_TO_CART, APP_REENGAGE_PURCHASE, APP_REENGAGE_OPEN, LANDING_PAGE_VIEW
LOWEST_COST_WITH_MAX_BIDNo restrictions
MIN_ROASAPP_PURCHASE
TARGET_COSTAPP_INSTALLS, SWIPES, USES, VIDEO_VIEWS_15_SEC, PIXEL_PURCHASE, PIXEL_SIGNUP, PIXEL_PAGE_VIEW, PIXEL_ADD_TO_CART, APP_PURCHASE, APP_SIGNUP, APP_ADD_TO_CART, APP_REENGAGE_PURCHASE, APP_REENGAGE_OPEN, STORY_OPENS, LANDING_PAGE_VIEW

MIN_ROAS examples

The Minimum ROAS (MIN_ROAS) bid strategy allows advertisers to define their desired ROAS in relation to the currency they are using within that Ad Account entity.

MIN_ROAS assumes the advertiser has implemented the in-app event APP_PURCHASE with the price parameter via their MMP. The roas_value_micro is used to define the expected ROAS and is defined in micro currency

Examples using "bid_strategy":"MIN_ROAS";

  • A roas_value_micro 1000000 in an Ad Account using the currency USD, optimizes to deliver $1 for every $1 in spend.
  • A roas_value_micro 500000 in an Ad Account using the currency GBP, optimizes to deliver £0.50 for every £1 in spend.
  • A roas_value_micro 1500000 in an Ad Account using the currency EUR, optimizes to deliver €1.50 for every €1 in spend.

Placement V2

On the 20th of March 2020 we announced the deprecation of the placement attribute in favour of placement_v2, please ensure that you have switched to using placement_v2 by the 20th of June 2020. This also means that content targeting via included_content_types and excluded_content_types moves from the Ad Squad level attributes to the attributes inclusion and exclusion which are defined within placement_v2.

Your App will not be able to set or amend the placement attribute via Creation or Update requests for any Ad Squads past the 20th June 2020. Any AdSquads that have only the placement attribute set will continue to serve based on that setting post 20th June 2020

The below table outlines the relationship between placement and placement_v2.

placementplacement_v2 - snapchat_positions
SNAP_ADSINTERSTITIAL_USER, INTERSTITIAL_CONTENT, INTERSTITIAL_SPOTLIGHT, INSTREAM
USER_STORIESINTERSTITIAL_USER
CONTENTINSTREAM
DISCOVER_FEEDFEED
CAMERACAMERA

Placement V2 Specification

AttributeDescriptionRequiredPossible Values
configConfiguration for placementRAUTOMATIC, CUSTOM
platformsThe platform to place the adsOSNAPCHAT
snapchat_positionsList of possible placement positionsINTERSTITIAL_USER, INTERSTITIAL_CONTENT, INTERSTITIAL_SPOTLIGHT, INSTREAM, PUBLIC_STORIES_INSTREAM, FEED, CAMERA
inclusionDetails about the content types to be includedO{"content_types": [List of possible content types]} Ad Squad must be of type SNAP_ADS. snapchat_positions must include INSTREAM. Inclusion and exclusion content types must be mutually exclusive NEWS, ENTERTAINMENT, SCIENCE_TECHNOLOGY, BEAUTY_FASHION, MENS_LIFESTYLE, WOMENS_LIFESTYLE, GAMING, GENERAL_LIFESTYLE, FOOD, SPORTS, YOUNG_BOLD
exclusionDetails about the content types to be includedO{"content_types": [List of possible content types]}. Ad Squad must be of type SNAP_ADS. snapchat_positions must include INSTREAM. Inclusion and exclusion content types must be mutually exclusive NEWS, ENTERTAINMENT, SCIENCE_TECHNOLOGY, BEAUTY_FASHION, MENS_LIFESTYLE, WOMENS_LIFESTYLE, GAMING, GENERAL_LIFESTYLE, FOOD, SPORTS, YOUNG_BOLD

Placement v2 gives advertisers more options and control over the location and context of where ads are placed, and includes all the advanced placement options that Snapchat has to offer. The inclusion and exclusion attributes within placement_v2 replaces the previously used included_content_types and included_content_types attributes which were defined at Ad Squad level.

config

ValueDescription
AUTOMATICSnapchat will choose the optimal placement for your ad across all of Snapchat, none of the other properties in placement_v2 can be provided
CUSTOMAdvertiser will chose all the settings for the placement. platforms must contain a value and snapchat_positions must not be empty

snapchat_positions

PositionDescription
INTERSTITIAL_USER.Ads run between friends stories.
INTERSTITIAL_CONTENT.Ads run before and after stories in publisher and our stories.
INTERSTITIAL_SPOTLIGHT*Ads run before and after public Snaps from the community.
INSTREAMAds run inside i.e. in between stories in publisher and our stories.
PUBLIC_STORIES_INSTREAMAds run within public stories.
FEEDStory Ads run alongside Publisher and Creator content in the Stories tab.
CAMERAAds run in the Lens carousel.

* The INTERSTITIAL_SPOTLIGHT placement cannot be targeted on it’s own, it needs to be combined with other placements

snapchat_positions Ad Squad type / Ad type

This table outlines the Ad Squad and Ad availability per placement position.

PositionAd Squad TypeAd Type
INTERSTITIAL_USERSNAP_ADSSNAP_AD, AD_TO_CALL, AD_TO_LENS, AD_TO_MESSAGE, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE, STORY*
INTERSTITIAL_CONTENTSNAP_ADSSNAP_AD, AD_TO_CALL, AD_TO_LENS, AD_TO_MESSAGE, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE, STORY*
INTERSTITIAL_SPOTLIGHT***SNAP_ADSSNAP_AD, AD_TO_CALL, AD_TO_MESSAGE, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE, STORY*
INSTREAMSNAP_ADSAD_TO_CALL, AD_TO_LENS, AD_TO_MESSAGE, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE, SNAP_AD, STORY
PUBLIC_STORIES_INSTREAMSNAP_ADSAD_TO_CALL, AD_TO_LENS, AD_TO_MESSAGE, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE, SNAP_AD, STORY
FEEDSNAP_ADSSTORY**
CAMERALENSLENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK

* Story Ads using the INTERSTITIAL_USER, INTERSTITIAL_CONTENT, INTERSTITIAL_SPOTLIGHT placements are not required to have a Preview Creative


** Story Ads using the FEED placement are required to have a Preview Creative


*** Ads serving in the INTERSTITIAL_SPOTLIGHT placement are required to have the Top Snap Media type VIDEO (IMAGE media is not allowed), Dynamic Ads are not allowed in the INTERSTITIAL_SPOTLIGHT placement

Example

{
"config": "CUSTOM",
"platforms": [
"SNAPCHAT",
],
"snapchat_positions": [
"INTERSTITIAL_USER",
"INSTREAM"
],
"inclusion": {
"content_types": [
"BEAUTY"
]
}

placement_v2 config Examples for different types of Ad Squads based on Ad type

Example 1

Snap Ads running with Automatic placement

"placement_v2": {
"config": "AUTOMATIC"
},

Example 2

Snap Ads running between User stories only

"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"INTERSTITIAL_USER"
]
},

Example 3

Snap Ads running between User stories and Curated content

"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"INTERSTITIAL_CONTENT",
"INTERSTITIAL_USER"
]
},

Example 4

Snap Ads running inside of curated content

"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"INSTREAM"
]
},

Example 5

Snap Ads running as commercials via premium content bundle

"placement_v2":{
"config":"CUSTOM",
"platforms":[
"SNAPCHAT"
],
"snapchat_positions":[
"INSTREAM"
],
"inclusion":{
"premium_content_bundle_ids":[
"c7e251af-3606-4f03-91f1-98456161655d"
]
},

Example 6

Story Ad running in the Stories tab

"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"FEED"
]
},

Example 7

Story Ad running in the Stories tab, between User stories and between Curated content

"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"FEED",
"INTERSTITIAL_USER",
"INTERSTITIAL_CONTENT"
]
},

Example 8

Lens Ad placed in the Camera

"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"CAMERA"
]
},

Example 9

Story Ad running in the Stories tab and placed in between public Snaps from the community.

"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"FEED",
"INTERSTITIAL_SPOTLIGHT"
]
},

Pacing Types

Validations

If pacing_type is set to ACCELERATED for accelerated delivery the following validations apply:

  • bid_strategy must be set to 'LOWEST_COST_WITH_MAX_BID'
  • bid_micro must be set
  • optimization_goal must be one of IMPRESSIONS, USES, SWIPES, VIDEO_VIEWS, VIDEO_VIEWS_15_SEC or STORY_OPENS

pacing_type is immutable and can be changed given the correct validations are in place.

Squad Optimization Goals

Goal-Based Bidding (GBB) allows a squad to be optimized toward a specific outcome.

Optimization Goal changes how the squad's bid_micro is interpreted.

Note: No matter what Optimization Goal is selected, the Billing Event will still be IMPRESSION. This may change in the future.

Optimization GoalBid InterpretationDetails
IMPRESSIONSCost Per 1000 Impressions (CPM)bid_micro will not be exceeded
SWIPESTarget Cost Per Swipebid_micro is treated as a goal, not a maximum, and can be exceeded
APP_INSTALLSTarget Cost Per Installbid_micro is treated as a goal, not a maximum, and can be exceeded
VIDEO_VIEWSTarget Cost per 2 second Video Viewbid_micro is treated as a goal, not a maximum, and can be exceeded
VIDEO_VIEWS_15_SECTarget Cost per 15 second Video Viewbid_micro is treated as a goal, not a maximum, and can be exceeded
USESCost Per Use (of filter)bid_micro is treated as a goal, not a maximum, and can be exceeded
STORY_OPENSTarget Cost Per Story Open for Story Adsbid_micro is treated as a goal, not a maximum, and can be exceeded
PIXEL_PAGE_VIEWTarget Cost Per PAGE_VIEW on webbid_micro is treated as a goal, not a maximum, and can be exceeded
PIXEL_ADD_TO_CARTTarget Cost Per ADD_TO_CART on webbid_micro is treated as a goal, not a maximum, and can be exceeded
PIXEL_PURCHASETarget Cost Per PURCHASE on webbid_micro is treated as a goal, not a maximum, and can be exceeded
PIXEL_SIGNUPTarget Cost Per SIGNUP on webbid_micro is treated as a goal, not a maximum, and can be exceeded
APP_ADD_TO_CART*Target Cost Per ADD_TO_CART on appbid_micro is treated as a goal, not a maximum, and can be exceeded
APP_PURCHASE*Target Cost Per PURCHASE on appbid_micro is treated as a goal, not a maximum, and can be exceeded
APP_SIGNUP*Target Cost Per PURCHASE on appbid_micro is treated as a goal, not a maximum, and can be exceeded
APP_REENGAGE_OPEN†Target Cost Per App openbid_micro is treated as a goal, not a maximum, and can be exceeded
APP_REENGAGE_PURCHASE†Target Cost Per App Purchasebid_micro is treated as a goal, not a maximum, and can be exceeded
LEAD_FORM_SUBMISSIONSTarget Cost Per Lead Form Submissionbid_micro is treated as a goal, not a maximum, and can be exceeded

Optimization goals PIXEL_ADD_TO_CART, PIXEL_PURCHASE, PIXEL_SIGNUP, APP_ADD_TO_CART, APP_PURCHASE and APP_SIGNUP are automatically enabled only for ad accounts that meet the following criteria:

  • Pixel; Ad Account has Snap Pixel created and installed on website, relevant Pixel events like ADD_TO_CART, SIGNUP and PURCHASE have been configured successfully
  • In-App events; App has been set to trigger and pass relevant events, ADD_TO_CART, SIGNUP and PURCHASE via the MMP
    † These optimization goals requires App Install State targeting for the App where the re-engagement takes place, see targeting example

Squad Optimization Goal Per Ad Type

This table outlines the Optimization Goals availability per Ad Type.

Optimization GoalAd Types
IMPRESSIONSSNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, FILTER, LEAD_GENERATION, LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_REMOTE_WEBPAGE, REMOTE_WEBPAGE, STORY*, AD_TO_CALL, AD_TO_MESSAGE
SWIPESAD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, LENS_APP_INSTALL, REMOTE_WEBPAGE, STORY*, AD_TO_CALL, AD_TO_MESSAGE
APP_INSTALLSAPP_INSTALL, COLLECTION, DEEP_LINK, STORY*, LENS, LENS_APP_INSTALL, LENS_DEEP_LINK
VIDEO_VIEWSSNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE
VIDEO_VIEWS_15_SECSNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE
USESLENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_REMOTE_WEBPAGE
STORY_OPENSSTORY*
PIXEL_PAGE_VIEWCOLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY*, LENS_REMOTE_WEBPAGE
PIXEL_ADD_TO_CARTCOLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY*, LENS_REMOTE_WEBPAGE
PIXEL_PURCHASECOLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY*, LENS_REMOTE_WEBPAGE
PIXEL_SIGNUPCOLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY*, LENS_REMOTE_WEBPAGE
APP_ADD_TO_CARTAPP_INSTALL, COLLECTION, DEEP_LINK, STORY**
APP_PURCHASEAPP_INSTALL, COLLECTION, DEEP_LINK, STORY*
APP_SIGNUPAPP_INSTALL, COLLECTION, DEEP_LINK, STORY**
APP_REENGAGE_OPENDEEP_LINK, COLLECTION, STORY** (COLLECTION and STORY Ads require deep_link_properties in Creative entity)
APP_REENGAGE_PURCHASEDEEP_LINK, COLLECTION, STORY** (COLLECTION and STORY Ads require deep_link_properties in Creative entity)
LANDING_PAGE_VIEWCOLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY**
LEAD_FORM_SUBMISSIONSLEAD_GENERATION

*For these Optimization Goals both STORY ads that have a Preview Creative and STORY Ads without a Preview Creative ("Tileless" Story Ads) are supported
**For these Optimization Goals only STORY ads without a Preview Creative ("Tileless" Story Ads) are supported

Squad Optimization Goal for Housing Credit Employment (HCE)

Ad Squads created under a Campaigns promoting Housing, Credit and Employment have a limited set of Optimization Goals available to them. Campaigns targeting HCE will have the setting "regulations": {"restricted_delivery_signals": true}, this indicates they can only use the Optimization Goals listed below.

Campaign settingOptimization Goal
"regulations": {"restricted_delivery_signals": true}IMPRESSIONS, SWIPES, APP_INSTALLS, PIXEL_PAGE_VIEW, PIXEL_SIGNUP

Ads on web

Snap Ads with Webview attachment can be delivered on the web version of Snapchat (https://web.snapchat.com) provided certain conditions are in place. When ads serve on the Web version of Snapchat they appear between friend stories. It’s not possible to target the Web version of Snapchat on it’s own; at least one of iOS or Android targeting is required.

Conditions

Ads will only serve on https://web.snapchat.com given the following configurations.

EntityEntity attributeDescription
Ad Squad - TargetingDevice targeting not set , WEB device targeting is assumed by default. See example targeting table below.
Ad Squad - Targeting“devices”:[ { "os_type": "WEB", "operation": "INCLUDE" } ]WEB device targeting is specified, note that at least one of iOS or Android needs to be targeted as well. See example targeting table below.
Ad Squad - Optimization goal"optimization_goal": "IMPRESSIONS"
Ad“type”:”REMOTE_WEBPAGE”Snap Ads with Webview attachments are the only type of Ad eligible for WEB
Creative“type”:”WEB_VIEW”Snap Ads with Webview attachments are the only type of Ad eligible for WEB

Example Targeting - Ads on web

ScenarioValueBehaviour
Device targeting not setAd serves on: ANDROID, iOS and WEB, assuming Optimization Goal, Ad, Creative type match the correct conditions
Device targeting set to all os_types"devices": [ { "os_type": "ANDROID", "operation": "INCLUDE" }, { "os_type": "iOS", "operation": "INCLUDE" }, { "os_type": "WEB", "operation": "INCLUDE" } ]Ad serves on: ANDROID, iOS and WEB, assuming Optimization Goal, Ad, Creative type match the correct conditions
Device targeting set to mobile only ( ANDROID , iOS)“devices”:[ { "os_type": "ANDROID", "operation": "INCLUDE" }, { "os_type": "iOS", "operation": "INCLUDE" } ]Ad serves on: ANDROID, iOS

Delivery Optimization Windows

The conversion_window attribute specifies the delivery optimisation window to be used for the Ad Squad, further information on the delivery optimization window can be found in our Business Help Centre.

Conversion window eligibility is tied to events reported to Snap via the Snap Pixel, the Snap Conversion API or other methods, the frequency and quality of events and conversions determines whether a specific conversion window is available. The eligibility can be checked using the Conversion Window Eligibility API request

Optimization GoalConversion window availabilityAd TypesEligibility
IMPRESSIONSSWIPE_28_DAY_VIEW_1DAYSNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, FILTER, LEAD_GENERATION, LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_REMOTE_WEBPAGE, REMOTE_WEBPAGE, STORY*, AD_TO_CALL, AD_TO_MESSAGEDefault eligibility
SWIPESSWIPE_28_DAY_VIEW_1DAYAD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, LENS_APP_INSTALL, REMOTE_WEBPAGE, STORY*, AD_TO_CALL, AD_TO_MESSAGEDefault eligibility
APP_INSTALLSSWIPE_28_DAY_VIEW_1DAYAPP_INSTALL, COLLECTION, DEEP_LINK, STORY*, LENS, LENS_APP_INSTALL, LENS_DEEP_LINKDefault eligibility
SWIPE_7DAYAPP_INSTALL, COLLECTION, DEEP_LINK, STORY**Eligibility dependent on volume and quality of events reported to Snap, use eligibility endpoint to check.
VIDEO_VIEWSSWIPE_28_DAY_VIEW_1DAYSNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGEDefault eligibility
VIDEO_VIEWS_15SWIPE_28_DAY_VIEW_1DAYSNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGEDefault eligibility
USESSWIPE_28_DAY_VIEW_1DAYLENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_REMOTE_WEBPAGEDefault eligibility
STORY_OPENSSWIPE_28_DAY_VIEW_1DAYSTORY*Default eligibility
PIXEL_PAGE_VIEWSWIPE_28_DAY_VIEW_1DAYCOLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY*, LENS_REMOTE_WEBPAGEDefault eligibility
PIXEL_ADD_TO_CARTSWIPE_28_DAY_VIEW_1DAYCOLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY*, LENS_REMOTE_WEBPAGEDefault eligibility
SWIPE_7DAYCOLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY**Eligibility dependent on volume and quality of events reported to Snap, use eligibility endpoint to check.
PIXEL_PURCHASESWIPE_28_DAY_VIEW_1DAYCOLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY*, LENS_REMOTE_WEBPAGEDefault eligibility
SWIPE_7DAYCOLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY**Eligibility dependent on volume and quality of events reported to Snap, use eligibility endpoint to check.
PIXEL_SIGN_UPSWIPE_28_DAY_VIEW_1DAYCOLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY*, LENS_REMOTE_WEBPAGEDefault eligibility
SWIPE_7DAYCOLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY**, LENS_REMOTE_WEBPAGEEligibility dependent on volume and quality of events reported to Snap, use eligibility endpoint to check.
APP_ADD_TO_CARTSWIPE_28_DAY_VIEW_1DAYAPP_INSTALL, COLLECTION, DEEP_LINK, STORY**Default eligibility
APP_PURCHASESWIPE_28_DAY_VIEW_1DAYAPP_INSTALL, COLLECTION, DEEP_LINK, STORY*Default eligibility
SWIPE_7DAYAPP_INSTALL, COLLECTION, DEEP_LINK, STORY**Eligibility dependent on volume and quality of events reported to Snap, use eligibility endpoint to check.
APP_SIGNUPSWIPE_28_DAY_VIEW_1DAYAPP_INSTALL, COLLECTION, DEEP_LINK, STORY**Default eligibility
APP_REENGAGE_OPENSWIPE_28_DAY_VIEW_1DAYDEEP_LINK, COLLECTION, STORY** (COLLECTION and STORY Ads require deep_link_properties in Creative entity)Default eligibility
APP_REENGAGE_PURCHASESWIPE_28_DAY_VIEW_1DAYDEEP_LINK, COLLECTION, STORY** COLLECTION and STORY Ads require deep_link_properties in Creative entityDefault eligibility
SWIPE_7DAYDEEP_LINK, COLLECTION, STORY** COLLECTION and STORY Ads require deep_link_properties in Creative entityEligibility dependent on volume and quality of events reported to Snap, use eligibility endpoint to check.
LANDING_PAGE_VIEWSWIPE_28_DAY_VIEW_1DAYCOLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY**Default eligibility
LEAD_FORM_SUBMISSIONSSWIPE_28_DAY_VIEW_1DAYLEAD_GENERATIONDefault eligibility

*For these Optimization Goals both STORY ads that have a Preview Creative and STORY Ads without a Preview Creative ("Tileless" Story Ads) are supported
**For these Optimization Goals only STORY ads without a Preview Creative ("Tileless" Story Ads) are supported

Delivery Optimisation window example

Using conversion_window with PIXEL_PURCHASE

Example - Using PIXEL_PURCHASE optimization goal with SWIPE_7DAY

curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adsquads":[{"campaign_id":"91a5edee-a6cf-42e7-8317-a310e0f65a54","name":"7 Day click delivery optimization","type":"SNAP_ADS","placement":"SNAP_ADS","optimization_goal":"PIXEL_PURCHASE","conversion_window":"SWIPE_7DAY","pixel_id":"5eda10b7-a5fe-4ac6-80f4-417e68d748fb","bid_micro":10000,"daily_budget_micro":50000000,"targeting":{"regulated_content":false,"demographics":[{"min_age":"18","gender":"FEMALE"}],"geos":[{"country_code":"us"}]},"delivery_constraint":"DAILY_BUDGET","start_time":"2021-07-13T21:12:45Z","status":"ACTIVE"}]}'
https://adsapi.snapchat.com/v1/campaigns/91a5edee-a6cf-42e7-8317-a310e0f65a54/adsquads

The above command returns JSON structured like this:

{
"request_status": "SUCCESS",
"request_id": "25356d15-e8b1-4757-9a93-92fda600f861",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "544b400a-c13e-4733-bfed-62aba316156b",
"updated_at": "2023-07-21T17:39:36.611Z",
"created_at": "2023-07-21T17:39:36.611Z",
"effective_status": "ACTIVE",
"name": "7 Day click delivery optimization",
"status": "ACTIVE",
"campaign_id": "91a5edee-a6cf-42e7-8317-a310e0f65a54",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"min_age": "18",
"gender": "FEMALE"
}
],
"geos": [
{
"country_code": "us"
}
],
"enable_targeting_expansion": true,
"auto_expansion_options": {
"interest_expansion_option": {
"enabled": true
},
"custom_audience_expansion_option": {
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement": "SNAP_ADS",
"billing_event": "IMPRESSION",
"bid_micro": 10000,
"auto_bid": false,
"target_bid": false,
"bid_strategy": "LOWEST_COST_WITH_MAX_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-07-13T21:12:45.000Z",
"optimization_goal": "PIXEL_PURCHASE",
"conversion_window": "SWIPE_7DAY",
"pixel_id": "5eda10b7-a5fe-4ac6-80f4-417e68d748fb",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED",
"delivery_status": ["INVALID_EFFECTIVE_INVALID"],
"skadnetwork_properties": {
"status": "NEVER_ENROLLED"
}
}
}
]
}

Creating an Ad Squad using the optimisation goal PIXEL_PURCHASE in combination with the delivery window SWIPE_7DAY , optimising delivery towards users that will click on the ad and convert within 7 days.

Conversion Window Eligibility

The conversion window options available to an Ad Squad depend on the frequency and quality of the events that are sent via the Snap Pixel ID and/or the Snap App ID attached to the Ad Squad. This endpoint can be used to check the Conversion Window eligibility for a specific Pixel or Snap App ID.

If both parameters are left empty the endpoint will return the available Conversion Windows for all the different Optimization Goals.

Pixel ID - Conversion Window availability

HTTP Request

GET https://adsapi.snapchat.com/v1/pixels/{pixel_id}/campaign_eligibilities

Request Parameters

AttributeDescriptionRequiredPossible values
optimization_goalOPIXEL_PURCHASE, PIXEL_SIGNUP, PIXEL_ADD_TO_CART
conversion_windowOSWIPE_7DAY

Example 1

This request has no parameters and so returns all the available conversion windows available for Pixel Id 3eda10b7-a5fe-4ac6-80f4-417e68d748fb for all optimization goals.

cURL \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
'https://adsapi.snapchat.com/v1/pixels/3eda10b7-a5fe-4ac6-80f4-417e68d748fb/campaign_eligibilities

Example response

{
"request_status": "SUCCESS",
"request_id": "544bd102-d639-4eaa-aa94-192d9b5e0903",
"paging": {},
"campaign_eligibilities": [
{
"sub_request_status": "SUCCESS",
"campaign_eligibility": {
"id": "0c6ba43b-677e-4da1-8da4-db1f3b87153a",
"updated_at": "2024-05-09T20:42:58.059Z",
"created_at": "2024-05-09T20:42:58.059Z",
"conversion_window": "SWIPE_7DAY",
"optimization_goal": "PIXEL_PURCHASE",
"eligibility_status": "ELIGIBLE_WARNING",
"event_quality_score_snapshot": 0.0,
"purchase_volume_l7_snapshot": 0,
"attributed_click_through_conversion_l7_snapshot": 0,
"is_shopify_snapshot": false,
"ineligible_properties": [
"attributed_click_through_conversion_l7",
"event_quality_score"
]
}
},
{
"sub_request_status": "SUCCESS",
"campaign_eligibility": {
"id": "98b304bb-2fef-4e36-9d91-b0390c65e4ae",
"updated_at": "2024-05-09T21:43:24.690Z",
"created_at": "2024-05-09T21:43:24.690Z",
"conversion_window": "SWIPE_7DAY",
"optimization_goal": "PIXEL_SIGNUP",
"eligibility_status": "ELIGIBLE_WARNING",
"event_quality_score_snapshot": 0.0,
"purchase_volume_l7_snapshot": 0,
"attributed_click_through_conversion_l7_snapshot": 0,
"is_shopify_snapshot": false,
"ineligible_properties": [
"attributed_click_through_conversion_l7",
"event_quality_score"
]
}
},
{
"sub_request_status": "SUCCESS",
"campaign_eligibility": {
"id": "fb59af12-745b-44a7-ac30-c56224840ce5",
"updated_at": "2024-05-09T21:33:46.474Z",
"created_at": "2024-05-09T21:33:46.474Z",
"conversion_window": "SWIPE_7DAY",
"optimization_goal": "PIXEL_ADD_TO_CART",
"eligibility_status": "ELIGIBLE_WARNING",
"event_quality_score_snapshot": 0.0,
"purchase_volume_l7_snapshot": 0,
"attributed_click_through_conversion_l7_snapshot": 0,
"is_shopify_snapshot": false,
"ineligible_properties": [
"attributed_click_through_conversion_l7",
"event_quality_score"
]
}
}
]
}

Example 2

This request returns the conversion windows available for Pixel Id 3eda10b7-a5fe-4ac6-80f4-417e68d748fb when using the PIXEL_PURCHASE optimization goal.

cURL \
-H 'Authorization: Bearer <ACCESS_TOKEN>' \
'https://adsapi.snapchat.com/v1/pixels/3eda10b7-a5fe-4ac6-80f4-417e68d748fb/campaign_eligibilities?optimization_goal=PIXEL_PURCHASE

Example response

{
"request_status": "SUCCESS",
"request_id": "5a10c853-6f2e-4695-a562-7b8a3794aafd",
"paging": {},
"campaign_eligibilities": [
{
"sub_request_status": "SUCCESS",
"campaign_eligibility": {
"id": "0c6ba43b-677e-4da1-8da4-db1f3b87153a",
"updated_at": "2024-05-09T20:42:58.059Z",
"created_at": "2024-05-09T20:42:58.059Z",
"conversion_window": "SWIPE_7DAY",
"optimization_goal": "PIXEL_PURCHASE",
"eligibility_status": "ELIGIBLE_WARNING",
"event_quality_score_snapshot": 0.0,
"purchase_volume_l7_snapshot": 0,
"attributed_click_through_conversion_l7_snapshot": 0,
"is_shopify_snapshot": false,
"ineligible_properties": [
"attributed_click_through_conversion_l7",
"event_quality_score"
]
}
}
]
}

Snap App ID - Conversion Window availability

HTTP Request

GET https://adsapi.snapchat.com/v1/mobile_apps/{snap_app_id}/campaign_eligibilities

Request Parameters

AttributeDescriptionRequiredPossible values
optimization_goalOAPP_INSTALLS, APP_PURCHASE, APP_REENGAGE_PURCHASE*
conversion_windowOSWIPE_7DAY

*This optimization goal is only available to qualifying Ad Accounts

Example 1

This request has no parameters and so returns all the available conversion windows available for Snap App ID 123 for all optimization goals.

Frequency Cap Spec

Frequency cap spec cap_and_exclusion_config allows you to specify the maximum number of times a user is exposed to an ad over a period of time.

Ad Squads that are delivering ads of multiple formats do not support frequency capping using the cap_and_exclusion_config if they are inside of Auction campaigns.

AttributeDescriptionTypePossible Values
frequency_cap_countNumber of times an ad is shown to the user in the intervalinteger
frequency_cap_typeAllowed Optimization GoalsstringIMPRESSIONS, SWIPES, VIDEO_VIEWS_15_SEC, VIDEO_VIEWS, STORY_OPENS, USES
time_intervalInterval during which the frequency cap rule is applied. frequency_cap_count is reset at the end of the interval. (Max 30 days or 720 hours)integer
frequency_cap_intervalUnit for time_intervalstringHOURS, DAYS
"cap_and_exclusion_config": {
"frequency_cap_config": [
{
"frequency_cap_count": 4,
"frequency_cap_type": "impressions",
"time_interval": 48,
"frequency_cap_interval": "hours"
}
]
}

Third-Party Tracking Tags

Snap partners with select vendors are able to use a “tagless” integration, where measurement can be set at the ad squad level, which will then apply to all child ad units within the ad Squad.

Measurement SolutionVendor Name
ViewabilityMoat
ViewabilityDoubleVerify

###How to Apply Third Party Tracking To apply third-party tracking for tagless integrations at the ad squad level, set the following value for the appropriate attribute:

Measurement SolutionVendor NameRequiredPossible values
measurement_provider_namesFlag denotes auto-tagging of all child ads in the ad squad when set to the approved vendor’s enum. Supports Moat viewability trackingOMOAT_SS, DOUBLEVERIFY

Ad Scheduling

With ad_scheduling_config, you can explicitly set which days of the week and, to what hours within each day your ads should run.

  1. Ad Squads that use ad scheduling must have a lifetime_budget_micro set instead of a daily_budget_micro
  2. The schedule set in ad_scheduling_config cannot conflict with the flight dates of the Ad Squad
  3. Ad Squads should have a minimum interval of 1 hour across any day they select to run on
  4. Ad scheduling will respect the user's timezone. The flight dates will continue to respect the ad account timezone. So an Ad Squad scheduled for Sunday morning 8-11 AM will show for a user based in Los Angeles between 8 AM and 11 AM Pacific time and for a New York based user between 8 AM - 11 AM Eastern Time which is 5AM - 8AM Pacific Time.
  5. Ad scheduling is mutable
  6. Ad scheduling config can supoort multiple ranges per day

Usage

"ad_scheduling_config": {
"monday": {
"hour_of_day": [1, 2, 3, 8, 9, 10]
},
"tuesday": {
"hour_of_day": [11, 12, 13]
}
}

This would describe an ad running on Monday from 1am - 3am && 8am - 10am and Tuesday from 11am - 1pm. The possible values for the keys are: monday, tuesday, wednesday, thursday, friday, saturday, sunday

AttributeDescriptionTypePossible Values
hour_of_dayarray of integers specifying the times of dayarray of integers0-23

Targeting Spec Examples

See the Targeting Spec Examples

Content Type

included_content_types and excluded_content_types can be used to specify more granular placement depending on the type of content.

Depending on the placement, included_content_types and excluded_content_types may or may not be specified.

placementincluded_content_typesexcluded_content_types
SNAP_ADSCannot be specifiedCan be specified
CONTENTCan be specifiedCan be specified
USER_STORIESCannot be specifiedCannot be specified
DISCOVER_FEEDCannot be specifiedCannot be specified

Create an Ad Squad

curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adsquads": [{"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be", "name": "Ad Squad Uno", "type": "SNAP_ADS", "placement_v2":{"config": "AUTOMATIC"}, "optimization_goal": "IMPRESSIONS", "bid_micro": 1000000, "daily_budget_micro": 1000000000, "bid_strategy": "LOWEST_COST_WITH_MAX_BID", "billing_event": "IMPRESSION", "targeting": {"geos": [{"country_code": "us"}]}, "start_time": "2016-08-11T22:03:58.869Z"}]}' \
https://adsapi.snapchat.com/v1/campaigns/6cf25572-048b-4447-95d1-eb48231751be/adsquads

The above command returns JSON structured like this:

{
"request_status": "success",
"request_id": "57b007e000ff09058b02a9e0220001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010110",
"adsquads": [
{
"sub_request_status": "success",
"adsquad": {
"id": "69cde0e6-0ccb-4982-8fce-1fa33507f213",
"updated_at": "2016-08-14T05:55:45.250Z",
"created_at": "2016-08-14T05:55:45.250Z",
"name": "Ad Squad Uno",
"status": "PAUSED",
"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
"type": "SNAP_ADS",
"targeting": {
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 1000000,
"auto_bid": false,
"target_bid": false,
"bid_strategy": "LOWEST_COST_WITH_MAX_BID",
"daily_budget_micro": 1000000000,
"start_time": "2016-08-11T22:03:58.869Z",
"optimization_goal": "IMPRESSIONS"
}
}
]
}

This endpoint creates an Ad Squad within a Campaign.

HTTP Request

POST https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads

Parameters

ParameterDefaultDescription
campaign_idCampaign ID

Update an Ad Squad

curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adsquads": [{"id": "990d22f3-86a5-4e9e-8afd-ac4c118896d4", "campaign_id": "d7540dee-5675-429b-95b6-a35b68537663", "name": "Ad Squad Un", "type": "SNAP_ADS", "placement_v2":{"config": "AUTOMATIC"}, "placement": "SNAP_ADS", "optimization_goal": "IMPRESSIONS", "bid_micro": 1000, "bid_strategy": "LOWEST_COST_WITH_MAX_BID", "daily_budget_micro": 5555555, "targeting": {"gender": 1}}]}'
https://adsapi.snapchat.com/v1/campaigns/d7540dee-5675-429b-95b6-a35b68537663/adsquads

The above command returns JSON structured like this:

{
"status": "success",
"request_id": "5792746b00019a287b52009b",
"adsquads": [
{
"status": "success",
"adsquad": {
"id": "990d22f3-86a5-4e9e-8afd-ac4c118896d4",
"updated_at": "2016-07-22T12:30:51.169-07:00",
"created_at": "2016-07-22T12:16:17.461-07:00",
"name": "Ad Squad Un",
"campaign_id": "d7540dee-5675-429b-95b6-a35b68537663",
"type": "SNAP_ADS",
"placement_v2": {
"config": "AUTOMATIC"
},
"optimization_goal": "IMPRESSIONS",
"bid_micro": 1000,
"bid_strategy": "LOWEST_COST_WITH_MAX_BID",
"daily_budget_micro": 5555555
}
}
]
}

This endpoint will update a specified ad squad.

Attributes that can be updated

AttributeRequired
bid_strategyR
bid_microR if BidStrategy = LOWEST_COST_WITH_MAX_BID or TARGET_COST
roas_value_microR if BidStrategy = MIN_ROAS
daily_budget_microone of daily_budget_micro or lifetime_budget_micro is required
lifetime_budget_microone of lifetime_budget_micro or daily_budget_micro is required
start_timeO *
end_timeO
nameR
statusR
targetingR
pixel_idO
cap_and_exclusion_configO
included_content_typesO
excluded_content_typesO
pacing_typeO

*start_time only updatable when date is in the future, the start_time of running Ad Squads cannot be updated

Targeting specs can now be updated regardless of whether the Ad Squad is live or paused. Updating the targeting of an Ad Squad will push the ads back into review and for live Ad Squads the delivery will be paused momentarily while the ads are re-reviewed and will resume once the ads are approved.

The field country within geos cannot be updated if the AdSquad is live.

HTTP Request

PUT https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads

Parameters

ParameterDefaultDescription
campaign_idCampaign ID

Get All Ad Squads under a Campaign

curl "https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads?return_placement_v2=true" \
-H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
"request_status": "success",
"request_id": "57b00b1500ff0476bcfb96faa20001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010b",
"adsquads": [
{
"sub_request_status": "success",
"adsquad": {
"id": "0633e159-0f41-4675-a0ba-224fbd70ac4d",
"updated_at": "2016-08-14T05:52:45.186Z",
"created_at": "2016-08-14T05:52:45.186Z",
"name": "Ad Squad Apples",
"status": "PAUSED",
"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
"type": "SNAP_ADS",
"targeting": {
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 1000000000,
"start_time": "2016-08-11T22:03:58.869Z",
"optimization_goal": "IMPRESSIONS"
}
},
{
"sub_request_status": "success",
"adsquad": {
"id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"updated_at": "2016-08-14T05:58:55.409Z",
"created_at": "2016-08-14T05:58:55.409Z",
"name": "Ad Squad Uno",
"status": "ACTIVE",
"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
"type": "SNAP_ADS",
"targeting": {
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 1000000,
"auto_bid": false,
"target_bid": true,
"bid_strategy": "TARGET_COST",
"daily_budget_micro": 1000000000,
"start_time": "2016-08-11T22:03:58.869Z",
"optimization_goal": "IMPRESSIONS"
}
}
]
}

This endpoint retrieves all ad squads within a specified campaign.

HTTP Request

GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads

Parameters

ParameterDefaultDescription
campaign_idCampaign ID
return_placement_v2trueoptional parameter for retrieving placement_v2 attribute

Get All Ad Squads under an Ad Account

curl "https://adsapi.snapchat.com/v1/adaccounts/8cf88872-048b-4447-95d1-eb48231788be/adsquads?return_placement_v2=true" \
-H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
"request_status": "success",
"request_id": "57b00b1500ff0476bcfb96faa20001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010b",
"adsquads": [
{
"sub_request_status": "success",
"adsquad": {
"id": "0633e159-0f41-4675-a0ba-224fbd70ac4d",
"updated_at": "2016-08-14T05:52:45.186Z",
"created_at": "2016-08-14T05:52:45.186Z",
"name": "Ad Squad Apples",
"status": "PAUSED",
"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
"type": "SNAP_ADS",
"targeting": {
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 1000000000,
"start_time": "2016-08-11T22:03:58.869Z",
"optimization_goal": "IMPRESSIONS"
}
},
{
"sub_request_status": "success",
"adsquad": {
"id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"updated_at": "2016-08-14T05:58:55.409Z",
"created_at": "2016-08-14T05:58:55.409Z",
"name": "Ad Squad Uno",
"status": "ACTIVE",
"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
"type": "SNAP_ADS",
"targeting": {
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 1000000,
"auto_bid": false,
"target_bid": true,
"bid_strategy": "TARGET_COST",
"daily_budget_micro": 1000000000,
"start_time": "2016-08-11T22:03:58.869Z",
"optimization_goal": "IMPRESSIONS"
}
}
]
}

This endpoint retrieves all ad squads within a specified ad account.

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/adsquads

Parameters

ParameterDefaultDescription
ad_account_idAd Account ID
return_placement_v2trueoptional parameter for retrieving placement_v2 attribute
read_deleted_entitiestrueoptional parameter, this param will return the deleted attribute on deleted Ad Squad entities

Get a Specific Ad Squad

curl "https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe?return_placement_v2=true" \
-H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
"request_status": "success",
"request_id": "57b00bd200ff0a1092e59e2ec90001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"adsquads": [
{
"sub_request_status": "success",
"adsquad": {
"id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"updated_at": "2016-08-14T05:58:55.409Z",
"created_at": "2016-08-14T05:58:55.409Z",
"name": "Ad Squad Uno",
"status": "ACTIVE",
"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
"type": "SNAP_ADS",
"targeting": {
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 1000000,
"auto_bid": false,
"target_bid": true,
"bid_strategy": "TARGET_COST",
"daily_budget_micro": 1000000000,
"start_time": "2016-08-11T22:03:58.869Z",
"optimization_goal": "IMPRESSIONS"
}
}
]
}

This endpoint retrieves a specific ad squad.

HTTP Request

GET https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}

URL Parameters

ParameterDefaultDescription
IDThe ID of the adsquad to retrieve
return_placement_v2trueoptional parameter for retrieving placement_v2 attribute
read_deleted_entitiestrueoptional parameter, this param will return the deleted attribute on deleted Ad Squad entities

Delete an Ad Squad

curl -X DELETE "https://adsapi.snapchat.com/v1/adsquads/0633e159-0f41-4675-a0ba-224fbd70ac4d" \
-H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
"request_status": "success",
"request_id": "57b00c6a00ff068aea0cfe17bd0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010109",
"adsquads": []
}

This endpoint deletes a specific ad squad.

HTTP Request

DELETE https://adsapi.snapchat.com/v1/adsquads/<ID>

URL Parameters

ParameterDescription
IDThe ID of the adsquad to delete
e
Was this page helpful?
Yes
No

AI-Powered Search