Ad Squads
An Ad Squad is owned by a Campaign and contains one or more Ads.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
campaign_id | Campaign ID | R | |
bid_micro | Max Bid (micro-currency) | R | bid_micro is currency specific see Currency Specific bids for Mininum/Maximum value |
billing_event | Billing Event | R | IMPRESSION |
brand_safety_config | Brand Safety Inventory Filter | O | See Brand Safety Config section |
child_ad_type | Indicates 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 immutable | O | SNAP_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_setting | Indicates 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 immutable | O | FULL_DURATION, SIX_SECONDS |
daily_budget_micro | Daily Budget (micro-currency) | one of daily_budget_micro or lifetime_budget_micro must be set | Minimum value 5000000 across all supported currencies |
lifetime_budget_micro | Lifetime budget (micro-currency) | one of lifetime_budget_micro or daily_budget_micro must be set | |
end_time | End time | O | |
name | Ad Squad name max length: 375 characters | R | |
optimization_goal | Optimization Goal | R | IMPRESSIONS, 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_window | Delivery optimisation window | O | SWIPE_28DAY_VIEW_1DAY (default), SWIPE_7DAY , see Delivery Optimization Windows |
placement_v2 | Placement | R | Json object containing advanced placement options See placement_v2 |
start_time | Start time | O | |
status | Ad Squad status | O | ACTIVE, PAUSED |
story_ad_creative_type | Indicates the type of Creative used in Dynamic Story Ads, required when using Dynamic Story Ads | O | APP_INSTALL, WEB_VIEW, DEEP_LINK |
targeting | Targeting spec | R | |
type | Ad Squad Type | R | SNAP_ADS, LENS, FILTER |
cap_and_exclusion_config | The frequency cap and exclusion spec | O | If 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_config | The schedule for running ads | O | |
bid_strategy | Bidding strategy for this Ad Squad | R | AUTO_BID, LOWEST_COST_WITH_MAX_BID, MIN_ROAS, TARGET_COST, see bid_strategy |
roas_value_micro | The desired ROAS used with the MIN_ROAS BidStrategy | R if BidStrategy = MIN_ROAS | Minimum value 10000 , Maximum value 100000000 |
pixel_id | Pixel to be associated with the Ad Squad | O | |
measurement_provider_names | approved measurement provider | O | MOAT_SS, DOUBLEVERIFY |
reach_and_frequency_status** | Status of the reach and frequency booking | R | Must be set to PENDING which automatically updates to ACTIVE or FAILED after booking |
delivery_constraint | Type of delivery | R | DAILY_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 request | R | Must match the value in the forecasting request |
impression_goal** | Reach goal as specified in the Forecasting request | R | Must match the value in the forecasting request |
pacing_type | Type of pacing | O | STANDARD (default), ACCELERATED |
delivery_status | Delivery status | Read-only | See Delivery status |
event_sources | Snap App Id to be associated with the Ad Squad | O/Required when using SKAdnetwork enrollment | Availble for Optimization Goals APP_REENGAGE_OPEN / APP_REENGAGE_PURCHASE and Dynamic Product Ads when using APP_INSTALL / DEEP_LINK |
skadnetwork_properties.status | SKAdnetwork enrollment status | Read-only | ENROLLED, NEVER_ENROLLED, WITHDRAWN |
deleted | Indicates whether the entity has been deleted or not, only shown when using the parameter read_deleted_entities | Read-only | true |
separated_types | Indicates 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
Attribute | Description | Required | Possible values |
---|---|---|---|
brand_safety_config | Defines 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.config | placement_v2.platforms | placement_v2.snapchat_positions |
---|---|---|
automatic | - | - |
custom | snapchat | PUBLIC_STORIES_INSTREAM |
Behaviour - Brand Safety Config
Scenario | Value | Behaviour |
---|---|---|
inventory_option is set to FULL_INVENTORY | brand_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_INVENTORY | brand_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 code | Currency | Minimum (micro-currency) | Maximum (micro-currency) |
---|---|---|---|
AED | UAE Dirham | 10,000 | 500,000,000 |
AUD | Australian Dollar | 10,000 | 100,000,000 |
BAM | Bosnian Mark | 10,000 | 100,000,000 |
CAD | Canadian Dollar | 10,000 | 100,000,000 |
CHF | Swiss Franc | 10,000 | 100,000,000 |
CNY | Chinese Yuan | 10,000 | 500,000,000 |
DKK | Danish Krone | 10,000 | 500,000,000 |
EUR | Euro | 10,000 | 100,000,000 |
GBP | Pound Sterling | 10,000 | 100,000,000 |
HKD | Hong Kong Dollar | 10,000 | 500,000,000 |
ILS | Israeli New Shekel | 10,000 | 500,000,000 |
INR | Indian Rupee | 10,000 | 500,000,000 |
KWD | Kuwaiti Dinar | 10,000 | 100,000,000 |
NOK | Norwegian Krone | 10,000 | 500,000,000 |
QAR | Qatari Rial | 10,000 | 500,000,000 |
SAR | Saudi Riyal | 10,000 | 500,000,000 |
SEK | Swedish Krona | 10,000 | 500,000,000 |
USD | US Dollar | 10,000 | 500,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 valueFULL_DURATION
orSIX_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 Name | Ad Type | Supports Multi-Format Delivery? | Notes |
---|---|---|---|
Snap Ads (attachment), Story Ad, Collection Ad | SNAP_AD, APP_INSTALL, REMOTE_WEBPAGE, DEEP_LINK, AD_TO_LENS, AD_TO_CALL, AD_TO_MESSAGE, LEAD_GEN, STORY, COLLECTION | YES | Snap 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 Ad | SNAP_AD, STORY, COLLECTION | YES | Dynamic Product Ads can be mixed with each other, cannot be mixed with non-dynamic Ad types. DPA Ad are Creatives with render_type DYNAMIC |
Commercial | SNAP_AD, REMOTE_WEBPAGE, AD_TO_LENS | YES | Commercials 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. |
Lens | LENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK | YES | Lenses 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
Parameter | Default | Description |
---|---|---|
ad_squad_id | Ad 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:
- 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. - A SKAdnetwork Campaign ID is available for the Snap App ID.
- 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
andAPP_REENGAGE_PURCHASE
are not available. - The bid strategies (bid_strategy)
MIN_ROAS
andTARGET_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_status | Description |
---|---|
AVAILABLE | There is at least one available App Campaign ID |
AVAILABLE_IN_GRACE_PERIOD | An 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_AVAILABLE | There is no available Apple Campaign ID |
HTTP Request
GET https://adsapi.snapchat.com/v1/mobile_apps/{snap_app_id}/ecid_status
Parameters
Parameter | Default | Description |
---|---|---|
snap_app_id | Snap 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.
Attribute | Description | Possible Values |
---|---|---|
placement_v2 | Placement for the Ads | Placement 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_status | Description |
---|---|
AVAILABLE_IN_GRACE_PERIOD | The 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_AVAILABLE | This 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
Parameter | Default | Description |
---|---|---|
snap_app_id | Snap 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
andbid_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_bid | target_bid | bid_micro | bid_strategy |
---|---|---|---|
true | false | ----- | AUTO_BID |
false | false | used for bid | LOWEST_COST_WITH_MAX_BID |
false | true | used for bid | TARGET_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_strategy | Description | Additional Settings |
---|---|---|
AUTO_BID | Drive the most efficient cost per action while spending your budget | ----- |
LOWEST_COST_WITH_MAX_BID | Bids conservatively at or below your desired bid | use 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 implemented | use 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_COST | Achieves the most volume while aiming to keep your average cost per action below your target cost | use 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_strategy | Optimization goals |
---|---|
AUTO_BID | APP_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_BID | No restrictions |
MIN_ROAS | APP_PURCHASE |
TARGET_COST | APP_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
.
placement | placement_v2 - snapchat_positions |
---|---|
SNAP_ADS | INTERSTITIAL_USER, INTERSTITIAL_CONTENT, INTERSTITIAL_SPOTLIGHT, INSTREAM |
USER_STORIES | INTERSTITIAL_USER |
CONTENT | INSTREAM |
DISCOVER_FEED | FEED |
CAMERA | CAMERA |
Placement V2 Specification
Attribute | Description | Required | Possible Values |
---|---|---|---|
config | Configuration for placement | R | AUTOMATIC, CUSTOM |
platforms | The platform to place the ads | O | SNAPCHAT |
snapchat_positions | List of possible placement positions | INTERSTITIAL_USER, INTERSTITIAL_CONTENT, INTERSTITIAL_SPOTLIGHT, INSTREAM, PUBLIC_STORIES_INSTREAM, FEED, CAMERA | |
inclusion | Details about the content types to be included | O | {"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 |
exclusion | Details about the content types to be included | O | {"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
Value | Description |
---|---|
AUTOMATIC | Snapchat will choose the optimal placement for your ad across all of Snapchat, none of the other properties in placement_v2 can be provided |
CUSTOM | Advertiser will chose all the settings for the placement. platforms must contain a value and snapchat_positions must not be empty |
snapchat_positions
Position | Description |
---|---|
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. |
INSTREAM | Ads run inside i.e. in between stories in publisher and our stories. |
PUBLIC_STORIES_INSTREAM | Ads run within public stories. |
FEED | Story Ads run alongside Publisher and Creator content in the Stories tab. |
CAMERA | Ads 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.
Position | Ad Squad Type | Ad Type |
---|---|---|
INTERSTITIAL_USER | SNAP_ADS | SNAP_AD, AD_TO_CALL, AD_TO_LENS, AD_TO_MESSAGE, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE, STORY* |
INTERSTITIAL_CONTENT | SNAP_ADS | SNAP_AD, AD_TO_CALL, AD_TO_LENS, AD_TO_MESSAGE, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE, STORY* |
INTERSTITIAL_SPOTLIGHT*** | SNAP_ADS | SNAP_AD, AD_TO_CALL, AD_TO_MESSAGE, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE, STORY* |
INSTREAM | SNAP_ADS | AD_TO_CALL, AD_TO_LENS, AD_TO_MESSAGE, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE, SNAP_AD, STORY |
PUBLIC_STORIES_INSTREAM | SNAP_ADS | AD_TO_CALL, AD_TO_LENS, AD_TO_MESSAGE, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE, SNAP_AD, STORY |
FEED | SNAP_ADS | STORY** |
CAMERA | LENS | LENS, 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 setoptimization_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 Goal | Bid Interpretation | Details |
---|---|---|
IMPRESSIONS | Cost Per 1000 Impressions (CPM) | bid_micro will not be exceeded |
SWIPES | Target Cost Per Swipe | bid_micro is treated as a goal, not a maximum, and can be exceeded |
APP_INSTALLS | Target Cost Per Install | bid_micro is treated as a goal, not a maximum, and can be exceeded |
VIDEO_VIEWS | Target Cost per 2 second Video View | bid_micro is treated as a goal, not a maximum, and can be exceeded |
VIDEO_VIEWS_15_SEC | Target Cost per 15 second Video View | bid_micro is treated as a goal, not a maximum, and can be exceeded |
USES | Cost Per Use (of filter) | bid_micro is treated as a goal, not a maximum, and can be exceeded |
STORY_OPENS | Target Cost Per Story Open for Story Ads | bid_micro is treated as a goal, not a maximum, and can be exceeded |
PIXEL_PAGE_VIEW | Target Cost Per PAGE_VIEW on web | bid_micro is treated as a goal, not a maximum, and can be exceeded |
PIXEL_ADD_TO_CART | Target Cost Per ADD_TO_CART on web | bid_micro is treated as a goal, not a maximum, and can be exceeded |
PIXEL_PURCHASE | Target Cost Per PURCHASE on web | bid_micro is treated as a goal, not a maximum, and can be exceeded |
PIXEL_SIGNUP | Target Cost Per SIGNUP on web | bid_micro is treated as a goal, not a maximum, and can be exceeded |
APP_ADD_TO_CART* | Target Cost Per ADD_TO_CART on app | bid_micro is treated as a goal, not a maximum, and can be exceeded |
APP_PURCHASE* | Target Cost Per PURCHASE on app | bid_micro is treated as a goal, not a maximum, and can be exceeded |
APP_SIGNUP* | Target Cost Per PURCHASE on app | bid_micro is treated as a goal, not a maximum, and can be exceeded |
APP_REENGAGE_OPEN† | Target Cost Per App open | bid_micro is treated as a goal, not a maximum, and can be exceeded |
APP_REENGAGE_PURCHASE† | Target Cost Per App Purchase | bid_micro is treated as a goal, not a maximum, and can be exceeded |
LEAD_FORM_SUBMISSIONS | Target Cost Per Lead Form Submission | bid_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 Goal | Ad Types |
---|---|
IMPRESSIONS | SNAP_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 |
SWIPES | AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, LENS_APP_INSTALL, REMOTE_WEBPAGE, STORY*, AD_TO_CALL, AD_TO_MESSAGE |
APP_INSTALLS | APP_INSTALL, COLLECTION, DEEP_LINK, STORY*, LENS, LENS_APP_INSTALL, LENS_DEEP_LINK |
VIDEO_VIEWS | SNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE |
VIDEO_VIEWS_15_SEC | SNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE |
USES | LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_REMOTE_WEBPAGE |
STORY_OPENS | STORY* |
PIXEL_PAGE_VIEW | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY*, LENS_REMOTE_WEBPAGE |
PIXEL_ADD_TO_CART | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY*, LENS_REMOTE_WEBPAGE |
PIXEL_PURCHASE | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY*, LENS_REMOTE_WEBPAGE |
PIXEL_SIGNUP | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY*, LENS_REMOTE_WEBPAGE |
APP_ADD_TO_CART | APP_INSTALL, COLLECTION, DEEP_LINK, STORY** |
APP_PURCHASE | APP_INSTALL, COLLECTION, DEEP_LINK, STORY* |
APP_SIGNUP | APP_INSTALL, COLLECTION, DEEP_LINK, STORY** |
APP_REENGAGE_OPEN | DEEP_LINK, COLLECTION, STORY** (COLLECTION and STORY Ads require deep_link_properties in Creative entity) |
APP_REENGAGE_PURCHASE | DEEP_LINK, COLLECTION, STORY** (COLLECTION and STORY Ads require deep_link_properties in Creative entity) |
LANDING_PAGE_VIEW | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY** |
LEAD_FORM_SUBMISSIONS | LEAD_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 setting | Optimization 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.
Entity | Entity attribute | Description |
---|---|---|
Ad Squad - Targeting | — | Device 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
Scenario | Value | Behaviour |
---|---|---|
Device targeting not set | — | Ad 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 Goal | Conversion window availability | Ad Types | Eligibility |
---|---|---|---|
IMPRESSIONS | SWIPE_28_DAY_VIEW_1DAY | SNAP_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 | Default eligibility |
SWIPES | SWIPE_28_DAY_VIEW_1DAY | AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, LENS_APP_INSTALL, REMOTE_WEBPAGE, STORY*, AD_TO_CALL, AD_TO_MESSAGE | Default eligibility |
APP_INSTALLS | SWIPE_28_DAY_VIEW_1DAY | APP_INSTALL, COLLECTION, DEEP_LINK, STORY*, LENS, LENS_APP_INSTALL, LENS_DEEP_LINK | Default eligibility |
SWIPE_7DAY | APP_INSTALL, COLLECTION, DEEP_LINK, STORY** | Eligibility dependent on volume and quality of events reported to Snap, use eligibility endpoint to check. | |
VIDEO_VIEWS | SWIPE_28_DAY_VIEW_1DAY | SNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE | Default eligibility |
VIDEO_VIEWS_15 | SWIPE_28_DAY_VIEW_1DAY | SNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE | Default eligibility |
USES | SWIPE_28_DAY_VIEW_1DAY | LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_REMOTE_WEBPAGE | Default eligibility |
STORY_OPENS | SWIPE_28_DAY_VIEW_1DAY | STORY* | Default eligibility |
PIXEL_PAGE_VIEW | SWIPE_28_DAY_VIEW_1DAY | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY*, LENS_REMOTE_WEBPAGE | Default eligibility |
PIXEL_ADD_TO_CART | SWIPE_28_DAY_VIEW_1DAY | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY*, LENS_REMOTE_WEBPAGE | Default eligibility |
SWIPE_7DAY | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY** | Eligibility dependent on volume and quality of events reported to Snap, use eligibility endpoint to check. | |
PIXEL_PURCHASE | SWIPE_28_DAY_VIEW_1DAY | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY*, LENS_REMOTE_WEBPAGE | Default eligibility |
SWIPE_7DAY | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY** | Eligibility dependent on volume and quality of events reported to Snap, use eligibility endpoint to check. | |
PIXEL_SIGN_UP | SWIPE_28_DAY_VIEW_1DAY | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY*, LENS_REMOTE_WEBPAGE | Default eligibility |
SWIPE_7DAY | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY**, LENS_REMOTE_WEBPAGE | Eligibility dependent on volume and quality of events reported to Snap, use eligibility endpoint to check. | |
APP_ADD_TO_CART | SWIPE_28_DAY_VIEW_1DAY | APP_INSTALL, COLLECTION, DEEP_LINK, STORY** | Default eligibility |
APP_PURCHASE | SWIPE_28_DAY_VIEW_1DAY | APP_INSTALL, COLLECTION, DEEP_LINK, STORY* | Default eligibility |
SWIPE_7DAY | APP_INSTALL, COLLECTION, DEEP_LINK, STORY** | Eligibility dependent on volume and quality of events reported to Snap, use eligibility endpoint to check. | |
APP_SIGNUP | SWIPE_28_DAY_VIEW_1DAY | APP_INSTALL, COLLECTION, DEEP_LINK, STORY** | Default eligibility |
APP_REENGAGE_OPEN | SWIPE_28_DAY_VIEW_1DAY | DEEP_LINK, COLLECTION, STORY** (COLLECTION and STORY Ads require deep_link_properties in Creative entity) | Default eligibility |
APP_REENGAGE_PURCHASE | SWIPE_28_DAY_VIEW_1DAY | DEEP_LINK, COLLECTION, STORY** COLLECTION and STORY Ads require deep_link_properties in Creative entity | Default eligibility |
SWIPE_7DAY | DEEP_LINK, COLLECTION, STORY** COLLECTION and STORY Ads require deep_link_properties in Creative entity | Eligibility dependent on volume and quality of events reported to Snap, use eligibility endpoint to check. | |
LANDING_PAGE_VIEW | SWIPE_28_DAY_VIEW_1DAY | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY** | Default eligibility |
LEAD_FORM_SUBMISSIONS | SWIPE_28_DAY_VIEW_1DAY | LEAD_GENERATION | Default 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
Attribute | Description | Required | Possible values |
---|---|---|---|
optimization_goal | O | PIXEL_PURCHASE, PIXEL_SIGNUP, PIXEL_ADD_TO_CART | |
conversion_window | O | SWIPE_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
Attribute | Description | Required | Possible values |
---|---|---|---|
optimization_goal | O | APP_INSTALLS, APP_PURCHASE, APP_REENGAGE_PURCHASE* | |
conversion_window | O | SWIPE_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.
Attribute | Description | Type | Possible Values |
---|---|---|---|
frequency_cap_count | Number of times an ad is shown to the user in the interval | integer | |
frequency_cap_type | Allowed Optimization Goals | string | IMPRESSIONS, SWIPES, VIDEO_VIEWS_15_SEC, VIDEO_VIEWS, STORY_OPENS, USES |
time_interval | Interval 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_interval | Unit for time_interval | string | HOURS, 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 Solution | Vendor Name |
---|---|
Viewability | Moat |
Viewability | DoubleVerify |
###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 Solution | Vendor Name | Required | Possible values |
---|---|---|---|
measurement_provider_names | Flag denotes auto-tagging of all child ads in the ad squad when set to the approved vendor’s enum. Supports Moat viewability tracking | O | MOAT_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.
- Ad Squads that use ad scheduling must have a lifetime_budget_micro set instead of a daily_budget_micro
- The schedule set in ad_scheduling_config cannot conflict with the flight dates of the Ad Squad
- Ad Squads should have a minimum interval of 1 hour across any day they select to run on
- 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.
- Ad scheduling is mutable
- 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
Attribute | Description | Type | Possible Values |
---|---|---|---|
hour_of_day | array of integers specifying the times of day | array of integers | 0-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.
placement | included_content_types | excluded_content_types |
---|---|---|
SNAP_ADS | Cannot be specified | Can be specified |
CONTENT | Can be specified | Can be specified |
USER_STORIES | Cannot be specified | Cannot be specified |
DISCOVER_FEED | Cannot be specified | Cannot 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
Parameter | Default | Description |
---|---|---|
campaign_id | Campaign 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
Attribute | Required |
---|---|
bid_strategy | R |
bid_micro | R if BidStrategy = LOWEST_COST_WITH_MAX_BID or TARGET_COST |
roas_value_micro | R if BidStrategy = MIN_ROAS |
daily_budget_micro | one of daily_budget_micro or lifetime_budget_micro is required |
lifetime_budget_micro | one of lifetime_budget_micro or daily_budget_micro is required |
start_time | O * |
end_time | O |
name | R |
status | R |
targeting | R |
pixel_id | O |
cap_and_exclusion_config | O |
included_content_types | O |
excluded_content_types | O |
pacing_type | O |
*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
Parameter | Default | Description |
---|---|---|
campaign_id | Campaign 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
Parameter | Default | Description |
---|---|---|
campaign_id | Campaign ID | |
return_placement_v2 | true | optional 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
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID | |
return_placement_v2 | true | optional parameter for retrieving placement_v2 attribute |
read_deleted_entities | true | optional 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
Parameter | Default | Description |
---|---|---|
ID | The ID of the adsquad to retrieve | |
return_placement_v2 | true | optional parameter for retrieving placement_v2 attribute |
read_deleted_entities | true | optional 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
Parameter | Description |
---|---|
ID | The ID of the adsquad to delete |
e |