Introduction
Welcome to the Snapchat Marketing API!
Code references are presented in the main column and examples in CURL can be viewed in the dark area to the right.
Announcements
Subscribing to Marketing API Announcements
To keep up to date on the latest changes to the Marketing API, you can sign up to receive Marketing API Announcements. Subscribing to these announcements allows you to receive updates on new releases, changes and deprecations for the Marketing API and the Conversions API.
February 2024
Effective February 26th, 2024, we are requiring Public Profile usage in ads via the Marketing API. This means your Creatives need to include the profile_properties attribute where a profile_id is to be used (see API docs here). While including the profile_properties is required on creation, you will still be able to override the Profile name by using the brand_name attribute.
July 2023
European Union Digital Services Act
Effective August 25, 2023 in compliance with the European Digital Services Act (DSA), some targeting and optimization settings will no longer be available when targeting Snapchatters aged 13-17 in the 27 countries of the European Union (EU). We are also extending this to the United Kingdom (UK).
Some targeting options will no longer be available for Ad Squads reaching Snapchatters aged 13-17 in the EU and the UK
No longer available targeting | Available targeting |
---|---|
Gender | Placement |
Interest targeting | Age |
Customer lists | Language |
Dynamic Product Ads Retargeting | Location |
Advanced demographics (already unavailable in the EU and the UK | Device |
Install state targeting |
Most optimization goals will no longer be available for Ad Squads reaching Snapchatters aged 13-17 in the EU and the UK
No longer available Optimisation Goals | Available Optimisation Goals |
---|---|
SWIPES | IMPRESSIONS |
APP_INSTALLS | Reserved Campaigns (Takeovers, Reach & Frequency, Snap Select) |
VIDEO_VIEWS , VIDEO_VIEWS_15_SEC | |
USES | |
STORY_OPENS | |
PIXEL_PAGE_VIEW, PIXEL_ADD_TO_CART, PIXEL_PURCHASE, PIXEL_SIGNUP | |
APP_ADD_TO_CART, APP_PURCHASE, APP_SIGNUP, APP_REENGAGE_OPEN, APP_REENGAGE_PURCHASE | |
LEAD_FORM_SUBMISSIONS |
To learn how these changes may impact current campaigns visit our Business Help Centre article on the EU DSA
May 2023
Pagination
To reduce latencies and improve reliability we are now introducing a default pagination size to all of our endpoints that support pagination. Currently we support pagination for Marketing API endpoints that can request large amounts of data, but we do not enforce any default limit.
- On the 23rd of July, 2023 all Marketing API endpoints that support pagination will be paginated and will have a default limit of 1000 rows even if you did not specify any pagintion parameters.
- By the 23rd of July, 2023 you must support the pagination features supported by the API to continue consuming the API without any disruptions.
- The limit parameter can still be passed to the API and can be used to specify a limit lower than 1000.
Impact
This change will only apply to GET
requests that are retrieving data. Non-paginated requests will continue to work,
however, they will only return a maximum of 1000 entities per request by default.
For example, if you are currently calling GET /v1/adsquads/{ad_squad_id}/ads
and receiving 2000 ad entities in the
response. You will now receive 1000 ad entities in the response along with a next_link
that can be used to fetch the
next page.
Migration
Follow the Pagination section of API Patterns to implement pagination in your requests.
December 2022
Deprecation announcements
The Long form Video attachment and Audience Filters are due for deprecation on 1 February 2023, it will not be possible to create Longform Video attachments or Audience Filters after deprecation.
The
snapchat_positions
options GAMES and AUDIENCE_EXTENSION have been deprecated, these were found underplacement_v2
which specifies the placement of Ads in the Snapchat client.The reporting parameter
platform_stats
has been deprecated
Targeting auto-expansion changes
In late January we will make two changes to Targeting auto expansion:
We are deprecating the attribute
enable_targeting_expansion
in favour ofauto_expansion_options
.auto_expansion_options
allows targeting to expand by interest viainterest_expansion_option
, and custom audiences viacustom_audience_expansion_option
Both expansion options will be enabled by default when creating an Ad Squad.
Ad Squads that form part of a Campaign targeting Housing, Credit or Employment, should always have auto-expansion disabled.
Auto expansion is described in full in the Targeting section of our docs.
May 2022
SKAdnetwork updates - Deprecation of Opt-out & Introduction of ecid_status
On the 7 September 2022 we are limiting enrollment to the point of Ad Squad creation, we are also deprecating the opt-out action for SKAd enrolled Ad Squads.
Whilst you won’t be able to opt-out an Ad Squad out of SKAd tracking, you will be able to free up the Apple Campaign ID by pausing the Ad Squad and detaching the Campaign ID using the new attribute ecid_status
The full changes along with a description of how to set the ecid_status
are described in the SKAdnetwork tracking section of our docs.
April 2022
Rename of “Snap Audience Match” (or “SAM”) to “Customer List”
We found that the term “Snap Audience Match” (or its acronym, “SAM”) was not intuitive for most advertisers. To help advertisers better understand what the feature does at a glance, we renamed this to “Customer List”.
August/October 2021
Ad Squad endpoint update
We are introducing an important behavior change to Ad Squad endpoint and the targeting entity in it. This is behavior change only affects targeting specs that have 500 or more GEO targeting criteria (country, region_id, postal_code). If you do not use more than 500 GEO targeting criteria in a single ad squad, you may ignore this change.
The complete changes are listed in the Targeting section for greater than 500 targeting rows
Timeline The changes listed below are already available for testing under a query parameter - targeting_spec_response_scope=AD_SQUAD_ONLY.
The changes will become default without the query parameter starting the 6th of January. On this date the old behavior will be deprecated.
Changes Any Ad Squad that contains more than 500 targeting criteria will have its targeting specifications broken out into a separate sub resource called targeting_specs and will be replaced by a property called separated_types. Any further updates or reads to the targeting spec will need to be performed on the new targeting_spec sub resource and not in the Ad Squad resource.
Pagination
To reduce latencies and improve reliability we are now introducing a default pagination size to all of our endpoints that support pagination. Currently we support pagination for Marketing API endpoints that can request large amounts of data, but we do not enforce any default limit.
- On the 27th of November all Marketing API endpoints that support pagination will be paginated and will have a default limit of 1000 rows even if you did not specify any pagintion parameters.
- By the 27th of November you must support the pagination features supported by the API to continue consuming the API without any disruptions.
- The limit parameter can still be passed to the API and can be used to specify a limit lower than 1000.
May 2021
Deprecation of Story Ad Position Reach Metrics
On the 23 August 2021 We are deprecating the Story Ad specific metrics position_uniques
and position_frequency
, the deprecation date will be 90 days after the announcement date.
Deprecation of position_uniques
and position_frequency
Announcement date: 25 May 2021
Deprecation date: 23 August 2021
The parameters position_uniques
and position_frequency
as described in the following section will be deprecated.
April 2021
Measurement And Reporting
As part of the changes made by Apple for their ATT (Apple Transparent Tracking) rollout, we will be making changes to our attribution. These changes will be reflected in our reporting API. There will be no changes to the existing API interface and so this is not a strict breaking change. However, API developers will need to update their implementation to account for the changes listed in the measurement section of the docs as there will be a regression in the API functionality.
Overview
The highest level object is an Organization. Each Organization is tied to a specific Brand, Advertiser, or Partner. An Organization has an over-arching line of credit established with Snap Inc.
An Organization owns:
- One or more Funding Sources. A Funding Source references the Organization’s line of credit or a portion thereof.
- One or more Ad Accounts. An Ad Account references one or more Funding Sources.
Ad Accounts are the primary vehicle for organizing all relevant advertising objects. An Ad Account owns:
- One or more ad Campaigns (and all of its children).
- One or more Media objects. Media are the most atomic objects - a single video file is a Media object.
- One or more Creative objects. A Creative references at least one Media object along with metadata regarding how the creative should be presented to the user.
- Zero or more Audience Segments. An Audience Segment is a targetable list of user identifiers using the advertiser’s first-party data.
An Organization (Org A) can grant another Organization (Org B) permission to access one or more of their Ad Accounts. A common case is a Brand granting a Snapchat MPP permission to advertise on their behalf using the Brand’s line of credit.
Quick Start
Here’s a high-level look at what it takes to launch a Snap Ad.
Let’s Run a Snap Ad!
- Snap Inc. creates your Organization, Funding Source, and Ad Account.
- Create a Media object.
- Upload the video file to the Media object.
- Create a Creative using the Media object ID.
- Create a Campaign.
- Create an Ad Squad. Set the bid, objective, and targeting at this stage.
- Create an Ad referencing the Creative object ID.
- Fin!
API Patterns
The API has a consistent pattern for requests.
Get Many Entities
Pattern:
GET /v1/{PLURAL_PARENT_ENTITY_NAME}/{PARENT_ENTITY_ID}/{PLURAL_ENTITY_NAME}
Example:
GET /v1/adaccounts/ff869d1f-0923-4d28-8577-4c36291f0fca/campaigns
Get a Single Entity
Pattern:
GET /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}
Example:
GET /v1/adaccounts/ff869d1f-0923-4d28-8577-4c36291f0fca
Pagination
curl "https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/ads?limit=50" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b3f92d000ff0943024587937a0001737e616473617069736300016275696c642d33346664346130642d312d3138322d320001010d",
"paging": {
"next_link": "https://adsapisc.appspot.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/ads?cursor=CnEKFgoJY3JlYXRlZEF0EgkIoLnp8JLP0QISU2oKc35hZHNhcGlzY3ItCxIDQWRzIiQzMmFkZmYzMC1iNDk0LTQ4NWQtODMwYi04MjZlNDAzZTVkNjgMogEVYWQtbWFuYWdlci1wcm9kdWN0aW9uGAAgAQ&limit=50"
},
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "8ade8ef7-0cde-4eaa-bde6-990133575229",
"updated_at": "2018-04-04T00:59:02.774Z",
"created_at": "2018-04-04T00:56:35.051Z",
"created_by_app_id": "87947032-5fbd-46a7-ba60-073ca8efefbb",
"created_by_user": "1dcd753d-aca4-4f2d-8818-1edd38053a36",
"last_updated_by_app_id": "87947032-5fbd-46a7-ba60-073ca8efefbb",
"last_updated_by_user": "1dcd753d-aca4-4f2d-8818-1edd38053a36",
"name": "Test",
"ad_squad_id": "4c8e53c2-1747-4b50-a8a8-8200fe75aac5",
"creative_id": "6ad4e432-f679-4a9b-af1d-c5781212dd75",
"status": "ACTIVE",
"type": "SNAP_AD",
"review_status": "APPROVED"
}...
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "32adff30-b494-485d-830b-826e403e5d68",
"updated_at": "2017-07-31T21:34:50.311Z",
"created_at": "2017-01-19T21:26:02.020Z",
"created_by_app_id": "4bc57a9c-c2ab-4a12-ba71-adda3c0189f9",
"last_updated_by_app_id": "4bc57a9c-c2ab-4a12-ba71-adda3c0189f9",
"name": "happy time in 910 2",
"ad_squad_id": "33a7ea1e-6413-4bb7-a4ac-35b0a258681e",
"creative_id": "9e37d1ee-5f27-45ff-8317-ab35a57a5bf4",
"status": "PAUSED",
"type": "SNAP_AD",
"review_status": "APPROVED"
}
}
]
}
For calls that fetch many entities we recommend that you use pagination. The limit parameter specifies how many entities should be returned per page.
The returned result will contain a paging attribute, this in turn holds a next_link attribute which holds the API call to fetch the next page.
Paginated calls are ordered by the attribute CreatedAt
, non-paginated calls are unsorted.
Paginated calls are supported for these requests;
- Get all Ads under an Ad Account/Campaign/Ad Squad
- Get all Ad Squads under an Ad Account/Campaign
- Get all Campaigns under an Ad Account
- Get all Creatives under an Ad Account
- Get all Media under an Ad Account
- Get all Ad Accounts under an Organization
- Get all Audience Segments under an Ad Account
- Get all Mobile Apps under an Organization
- Get all Billing Centers under an Organization
- Get all Pixels under an Organization
- Get all Interaction Zones under an Ad Account
- Get all Dynamic Templates under an Ad Account
- Get Zipcode targeting options
- Get Audit logs
Parameter | Required | Description |
---|---|---|
limit | O | integer, min 50, max 1000 |
Pattern:
GET /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}?limit={value between 50 - 1000}
Example:
GET /v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/ads?limit=50
Entity Request Limits
Whilst the Create and Update endpoints support the creation/editing of several objects in a single POST request there is a limit to the number of entities that can be created/edited in a single request.
Entity type | Create/Update limit per Request |
---|---|
Creative | 10 |
Media | 10 |
Organization | 15 |
Ad Account | 15 |
Segments | 15 |
Campaign | 30 |
Ad Squad | 30 |
Ad | 30 |
Create One or More Entities
The Create endpoints support bulk creation, meaning you can create several objects at the same time as long as they share the same parent. For example, you can create muliple Campaigns within a single Ad Account in a single POST request.
Pattern:
POST /v1/{PLURAL_PARENT_ENTITY_NAME}/{PARENT_ENTITY_ID}/{PLURAL_ENTITY_NAME}
Example:
POST /v1/adaccounts/ff869d1f-0923-4d28-8577-4c36291f0fca/campaigns
Update One or More Entities
The Update endpoints support bulk update, meaning you can update several objects at the same time as long as they share the same parent. For example, you can update muliple Campaigns within a single Ad Account in a single PUT request.
Pattern:
PUT /v1/{PLURAL_PARENT_ENTITY_NAME}/{PARENT_ENTITY_ID}/{PLURAL_ENTITY_NAME}
Example:
PUT /v1/adaccounts/ff869d1f-0923-4d28-8577-4c36291f0fca/campaigns
Delete a Single Entity
Pattern:
DELETE /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}
Example:
DELETE /v1/campaigns/0be21d8a-2720-4668-9576-0fa566a6ff55
Monetary Values
All Monetary Values are presented in micro-currency, wherein 1.00 in the Ad Account’s currency (USD, CAD, GBP, EUR, AUD) is equal to 1,000,000 micro-currency.
Examples
Currency Value | Micro-Currency Value |
---|---|
$1.00 | 1000000 |
$0.50 | 500000 |
$50,000 | 50000000000 |
$123.45 | 123450000 |
Authentication
To authorize, use this code:
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
-H "Authorization: Bearer meowmeowmeow"
Make sure to replace
meowmeowmeow
with your access token.
The Snapchat Marketing API uses access tokens to control access and authenticate requests, the access token will reflect the user permissions when used in API requests.
The access token should be included in all API requests to the server in the Authorization header in the following way:
Authorization: Bearer meowmeowmeow
Obtain App Credentials
OAuth apps are set up in the ‘Business Details’ section in Snap Business Manager, you need to be an Organization Admin to see the app dashboard, when setting up an app you need to agree to the Snap Developer Terms and the Snap Business Tools Terms.
Refer to this guide to setup your OAuth app in Business Manager.
When setting up an OAuth app you need to provide a name and a redirect_uri, the redirect_uri is where the user is redirected upon authentication.
Depending on your objectives you may want the redirect_uri to simply display the code value so that you can copy it and use it in an app built elsewhere to generate tokens, or you may choose to build the entry point for your entire app on the redirect_uri so that it may read the code value automatically upon user authentication.
Upon creation of an app you will be presented with client_id and client_secret, the secret is only ever displayed at the point of creation so you will need to keep track of this.
User Auth via Redirect
Direct the user’s browser to the Authorization URL. The user will be presented with a login screen and confirmation prompt asking the user to authorize the OAuth App to act on behalf of the user.
GET https://accounts.snapchat.com/login/oauth2/authorize
Parameters
Parameter | Default | Description |
---|---|---|
client_id | Client ID | |
redirect_uri | URLEncoded Redirect URI (must match URI on OAuth App) | |
response_type | Must be “code” | |
scope | Refer to the scopes reference table below | |
state | Optional; Will be passed through in redirect; Used for verification of request authenticity |
Scopes
Scope | Description |
---|---|
snapchat-marketing-api | This scope allows the app to read and write to the Snapchat marketing APIs |
snapchat-offline-conversions-api | This scope allows the app to read and write to the Snapchat Conversions APIs |
snapchat-profile-api | This scope allows the app to read the Snapchat Public Profile APIs |
Note: To use multiple scopes please pass in a space separated list of scopes example scope=snapchat-marketing-api snapchat-offline-conversions-api
# Sample URL to redirect the OAuth users to - Single Scope
https://accounts.snapchat.com/login/oauth2/authorize
?client_id=4cxxxx8-1c33-xxxx-8798-xxxxxxxx
&redirect_uri=https://test.animalfarm.com/callback
&response_type=code
&scope=snapchat-marketing-api
# Sample URL to redirect the OAuth users to - Multiple Scopes
https://accounts.snapchat.com/login/oauth2/authorize
?client_id=4cxxxx8-1c33-xxxx-8798-xxxxxxxx
&redirect_uri=https://test.animalfarm.com/callback
&response_type=code
&scope=snapchat-marketing-api snapchat-offline-conversions-api
Receive the Redirected User
After the user approves or cancels the authorization, they will be redirected to your Redirect URI. If the user approved the request for the OAuth App to act on their behalf, there will be 2 query parameters passed along to your Redirect URI.
Parameters
Parameter | Default | Description |
---|---|---|
code | One-time use code that can be exchanged for an Access Token and a Refresh Token | |
state | Optional; Used for verification of request authenticity |
Generate an Access Token
In order to access the API on behalf of the user that just authorised the app you must generate an Access Token that represents the user. To generate an Access Token you must first receive a Code from a successful user OAuth Web Redirect Flow described above. Once you have the Code you can exchange it for a short-lived Access Token and long-lived Refresh Token. The Access Token is valid for 1800 seconds = 30 minutes.
# With shell, you can just pass the correct header with each request
curl -X POST \
-d "grant_type=authorization_code" \
-d "client_id={client_id}" \
-d "client_secret={client_secret}" \
-d "code={code}" \
-d "redirect_uri={redirect_uri}"
https://accounts.snapchat.com/login/oauth2/access_token
The above command returns JSON structured like this:
{
"expires_in": 1800,
"token_type": "Bearer",
"refresh_token": "32eb12f037712a6b60404d6d9c170ee9ae4d5b9936c73dd03c23fffff1213cb3",
"access_token": "0.MGQCxyz123"
}
HTTP Request
POST https://accounts.snapchat.com/login/oauth2/access_token
Parameters
Parameter | Default | Description |
---|---|---|
client_id | Client ID | |
client_secret | Client Secret | |
code | One-time Use Code from User Redirect or Refresh Token | |
grant_type | “authorization_code” | |
redirect_uri | URLEncoded Redirect URI. Required when grant_type=authorization_code. Must match redirect_uri from the previous /authorize call |
Refresh the Access Token
Access Tokens are short-lived. When you receive a 401 token expired error, you should use your Refresh Token to generate a new Access Token and retry the request. Many standard OAuth2 libraries can handle this expiration-retry pattern for you.
# With shell, you can just pass the correct header with each request
curl -X POST \
-d "refresh_token={refresh_token}" \
-d "client_id={client_id}" \
-d "client_secret={client_secret}" \
-d "grant_type=refresh_token" \
https://accounts.snapchat.com/login/oauth2/access_token
The above command returns JSON structured like this:
{
"access_token": "0.MGQCxyz123",
"token_type": "Bearer",
"expires_in": 1800,
"refresh_token": "32eb12f037712a6b60404d6d9c170ee9ae4d5b9936c73dd03c23fffff1213cb3",
"scope": "snapchat-marketing-api"
}
HTTP Request
POST https://accounts.snapchat.com/login/oauth2/access_token
Parameters
Parameter | Default | Description |
---|---|---|
client_id | Client ID | |
client_secret | Client Secret | |
grant_type | “refresh_token” | |
refresh_token | The refresh token you received when generating your first access token |
Full Web Flow Example
1. Open the authorize link in a browser:
https://accounts.snapchat.com/login/oauth2/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope=snapchat-marketing-api&state=wmKkg0TWgppW8PTBZ20sldUmF7hwvU
2. Login & Authorize via UI
3. Locate "code" query parameter in the redirect
4. Exchange code for access token + refresh token
curl -X POST \
-d "code={one_time_use_code}" \
-d "client_id={client_id}" \
-d "client_secret={client_secret}" \
-d "grant_type=authorization_code" \
-d "redirect_uri=redirect_uri"
https://accounts.snapchat.com/login/oauth2/access_token
5. When the access token expires, generate a new one using the refresh token
curl -X POST \
-d "refresh_token={refresh_token}" \
-d "client_id={client_id}" \
-d "client_secret={client_secret}" \
-d "grant_type=refresh_token" \
https://accounts.snapchat.com/login/oauth2/access_token
The above command returns JSON structured like this:
{
"expires_in": 1800,
"token_type": "Bearer",
"refresh_token": "xyz",
"access_token": "0.1234567890"
}
Access Token Expiration
Access Tokens are short-lived and expire after a number of seconds indicated by the expires_in property in the response, currently the expiry is 1800 seconds = 30 minutes.
When a request is attempted with an expired token, the response will be a 401 Not Authorized with additional headers.
< HTTP/1.1 401 Unauthorized
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Headers: Content-Type, Authorization
< WWW-Authenticate: Bearer error="invalid_token", error_description="The access token expired"
< X-Cloud-Trace-Context: e0fdbe35c49ad238e624635b6a45813d;o=1
< Date: Mon, 15 Aug 2016 21:10:01 GMT
< Content-Type: text/html
< Server: Google Frontend
< Content-Length: 0
User
Get Authenicated User
curl "https://adsapi.snapchat.com/v1/me"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
"me": {
"id": "a22b5575-9052-437e-96c1-db781d62d203",
"updated_at": "2018-09-28T23:33:01.706Z",
"created_at": "2018-09-28T23:30:27.009Z",
"email": "honey.badger@hooli.com",
"organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"display_name": "Honey Badger",
"snapchat_username": "honey_badger",
"member_status": "MEMBER",
"bitmoji": {
"avatar_id": "199953104_65-s7",
"selfie_id": "10226021",
"background_id": "398580551",
"scene_id": ""
}
}
This endpoint retrieves information about the Snapchat user that is represented by the access token used, the information includes the snapchat_username
.
HTTP Request
GET https://adsapi.snapchat.com/v1/me
Organizations
An Organization represents an brand, partner or ad agency, creation happens via Snap Business Manager.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | Organization name | R |
Create an Organization
The only way to set up an Organization is to sign up for a Business account with Snap Business Manager.
Get All Organizations
curl "https://adsapi.snapchat.com/v1/me/organizations" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57affee300ff0d91229fabb9710001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010110",
"organizations": [
{
"sub_request_status": "success",
"organization": {
"id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"updated_at": "2017-05-26T15:14:44.877Z",
"created_at": "2017-05-26T15:14:44.877Z",
"name": "My Organization",
"address_line_1": "101 Stewart St",
"locality": "Seattle",
"administrative_district_level_1": "WA",
"country": "US",
"postal_code": "98134",
"type": "ENTERPRISE"
}
},
{
"sub_request_status": "success",
"organization": {
"id": "507d7a57-94de-4239-8a74-e93c00ca53e6",
"updated_at": "2016-08-01T15:14:44.877Z",
"created_at": "2017-08-01T15:14:44.877Z",
"name": "Hooli",
"address_line_1": "1100 Silicon Vallety Rd",
"locality": "San Francisco",
"administrative_district_level_1": "CA",
"country": "US",
"postal_code": "94110",
"type": "ENTERPRISE"
}
}
]
}
This endpoint retrieves all organizations.
HTTP Request
GET https://adsapi.snapchat.com/v1/me/organizations
Get All Organizations with Ad Accounts
curl "https://adsapi.snapchat.com/v1/me/organizations?with_ad_accounts=true" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b985a7300ff0b4b064df945b80001737e616473617069736300016275696c642d33346634346232622d312d3230302d320001011f",
"organizations": [
{
"sub_request_status": "SUCCESS",
"organization": {
"id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"updated_at": "2018-09-04T16:27:01.066Z",
"created_at": "2016-08-09T17:12:49.707Z",
"name": "Hooli Inc",
"country": "US",
"postal_code": "90291",
"locality": "Venice",
"contact_name": "",
"contact_email": "",
"contact_phone": "",
"tax_type": "NONE",
"address_line_1": "64 Market St",
"administrative_district_level_1": "CA",
"accepted_term_version": "8",
"is_agency": true,
"configuration_settings": {
"notifications_enabled": true
},
"type": "ENTERPRISE",
"state": "ACTIVE",
"roles": [
"member"
],
"ad_accounts": [
{
"id": "8b8e40af-fc64-455d-925b-ca80f7af6914",
"updated_at": "2018-03-07T23:39:20.469Z",
"created_at": "2018-03-27T23:42:43.513Z",
"name": "Hooli Originals",
"type": "PARTNER",
"status": "ACTIVE",
"currency": "USD",
"timezone": "America/Los_Angeles",
"roles": [
"reports"
]
},
{
"id": "497979f0-ea17-4971-8288-054883f1caca",
"updated_at": "2017-01-04T22:58:38.179Z",
"created_at": "2018-09-07T14:41:36.002Z",
"name": "Pied piper Test Account",
"type": "PARTNER",
"status": "ACTIVE",
"currency": "USD",
"timezone": "America/Los_Angeles",
"roles": [
"admin"
]
},
{
"id": "22ada972-f2aa-4d06-a45a-a7a80f53ae34",
"updated_at": "2017-07-28T02:32:03.914Z",
"created_at": "2017-12-08T21:56:57.305Z",
"name": "Initech Corp",
"type": "PARTNER",
"status": "ACTIVE",
"currency": "USD",
"timezone": "America/Los_Angeles",
"roles": [
"creative"
]
}
],
"my_display_name": "Honey Badger",
"my_invited_email": "honey.badget@hooli.com",
"my_member_id": "8454ada6-cec8-4e97-a0a7-c0b262c4137b"
}
}
]
}
This endpoint retrieves all organizations the user has access to and the ad accounts beneath each of those organizations. The roles attribute holds shows the role that the user holds within the Ad Account in question, Ad Account roles are explain in the Roles section.
HTTP Request
GET https://adsapi.snapchat.com/v1/me/organizations?with_ad_accounts=true
Get a Specific Organization
curl "https://adsapi.snapchat.com/v1/organizations/40d6719b-da09-410b-9185-0cc9c0dfed1d" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5928472c00ff04f7eaae709d770001737e7465616d6b6f363139000161646d616e616765722d61706",
"organizations": [
{
"sub_request_status": "SUCCESS",
"organization": {
"id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"updated_at": "2017-05-26T15:14:44.877Z",
"created_at": "2017-05-26T15:14:44.877Z",
"name": "My Organization",
"address_line_1": "101 Stewart St",
"locality": "Seattle",
"administrative_district_level_1": "WA",
"country": "US",
"postal_code": "98134",
"type": "ENTERPRISE"
}
}
]
}
This endpoint retrieves a specific organization.
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/<ID>
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the organization to retrieve |
Funding Sources
An Funding Source is owned by an Organization and defines the financial instrument/terms responsible for the ad spend. Funding sources are assigned to an Ad Account in order to pay for the activity within that Ad Account.
Attributes
Attribute | Description | Possible Values | Supported for type |
---|---|---|---|
id | ID of the funding source | ALL | |
created_at | Date of creation | ALL | |
updated_at | Date of last update | ALL | |
type | Funding Source type | LINE_OF_CREDIT, CREDIT_CARD, COUPON, PAYPAL | ALL |
status | Status of the funding source | ACTIVE, REDEEMED, SPENT, EXPIRED, DELETED | ALL |
budget_spent_micro | Budget Spent (micro-currency) | LINE_OF_CREDIT | |
currency | Account currency | USD, CAD, GBP, AUD, EUR | LINE_OF_CREDIT, COUPON |
total_budget_micro | Total Budget (micro-currency) | LINE_OF_CREDIT, CREDIT_CARD | |
budget_spent_micro | Budget spent (micro-currency) | LINE_OF_CREDIT, CREDIT_CARD | |
available_credit_micro | Total available credit | LINE_OF_CREDIT, COUPON | |
card_type | Credit Card Type | AMEX, DINERS_CLUB, DISCOVER, JCB, MAESTRO, MASTERCARD, VISA, UNKNOWN | CREDIT_CARD |
name | Name of the Credit Card | ALL | |
last_4 | Last 4 digits of the Credit Card | CREDIT_CARD | |
expiration_year | Expiration year of the Credit Card | CREDIT_CARD | |
expiration_month | Expiration month of the Credit Card | CREDIT_CARD | |
daily_spend_limit_micro | Daily spend limit for Credit Card (micro-currency) | CREDIT_CARD | |
daily_spend_limit_currency | Currency for the daily_spend_limit_micro | USD, CAD, GBP, AUD, EUR | CREDIT_CARD |
value_micro | Value of the COUPON (micro-currency) | COUPON | |
start_date | Start date of the COUPON | COUPON | |
end_date | End date of the COUPON | COUPON | |
Email associated with Paypal | PAYPAL |
Create a Funding Source
Funding sources using credit cards and PayPal can be set up using Business Manager
The Partner Manager team creates all other types of Funding Sources on behalf of partners and advertisers. Please reach out to your partner manager for assistance.
Get All Funding Sources
curl "https://adsapi.snapchat.com/v1/organizations/{organization_id}/fundingsources" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "59236a2500ff05763ff95f2fcc0001737e7465616d6b6f363139000161646d616e616765722d6170693a6b6162726168616d0001011d",
"fundingsources": [
{
"sub_request_status": "SUCCESS",
"fundingsource": {
"id": "1e224e75-3883-42cf-a5d9-ce505945d2d3",
"updated_at": "2017-05-22T22:46:30.917Z",
"created_at": "2017-05-22T22:46:30.917Z",
"type": "CREDIT_CARD",
"card_type": "DISCOVER",
"name" : "My DISCOVER card",
"last_4": "1100",
"expiration_month": "12",
"expiration_year": "2020",
"daily_spend_limit_micro": 25000000,
"daily_spend_currency": "USD"
}
},
{
"sub_request_status": "SUCCESS",
"fundingsource": {
"id": "9d111fbf-da5f-4526-9e7b-226f847b3d7e",
"updated_at": "2017-05-22T22:46:30.920Z",
"created_at": "2017-05-22T22:46:30.920Z",
"type": "LINE_OF_CREDIT",
"available_credit_micro": 2000000000,
"currency": "USD",
"total_budget_micro": 10000000000,
"status": "ACTIVE",
"credit_account_type": "MANAGED",
"budget_spent_micro": 8000000000
}
},
{
"sub_request_status": "SUCCESS",
"fundingsource": {
"id": "d24b4011-3560-47ea-86fa-0ed14c6b90d4",
"updated_at": "2017-05-22T22:46:30.920Z",
"created_at": "2017-05-22T22:46:30.920Z",
"type": "COUPON",
"available_credit_micro": 10000000000,
"currency": "EUR",
"value_micro": 10000000000,
"status": "REDEEMED",
"start_date": "2017-05-22T22:46:30.923Z",
"end_date": "2017-05-22T22:46:30.923Z"
}
}
]
}
This endpoint retrieves all funding sources for the specified Organization.
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/fundingsources
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Get a Specific Funding Source
curl "https://adsapi.snapchat.com/v1/fundingsources/e703eb9f-8eac-4eda-a9c7-deec3935222d" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b000ffd800ff05551a197221f10001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010c",
"fundingsources": [
{
"sub_request_status": "success",
"fundingsource": {
"id": "e703eb9f-8eac-4eda-a9c7-deec3935222d",
"updated_at": "2016-08-11T22:03:54.337Z",
"created_at": "2016-08-11T22:03:54.337Z",
"name": "Hooli Test Ad Account Funding Source",
"type": "LINE_OF_CREDIT",
"organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"currency": "USD"
}
}
]
}
This endpoint retrieves a specific funding source.
HTTP Request
GET https://adsapi.snapchat.com/v1/fundingsources/{funding_source_id}
URL Parameters
Parameter | Description |
---|---|
funding_source_id | The ID of the funding source to retrieve |
Billing Centers
Billing Centers allow Businesses to have multiple invoicing locations to choose from. A Billing Center is the contact that will be receiving invoices.
Billing Centers can only be created via Snap Business Manager.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
organization_id | Organization ID | R | |
name | Name of the Billing Center | R | |
email_address | Email address | R | |
address_line_1 | Address line 1 | R | |
locality | Locality | R | |
administrative_district_level_1 | District | R | |
country | Country | R | |
postal_code | Post code | R | |
alternative_email_addresses | Array of email addresses | O |
Get all Billing Centers
curl "https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/billingcenters" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eaa971a00ff05c3d6fabff7fb0001737e616473617069736300016275696c642d63386238336332372d312d3334372d310001011a",
"paging": {},
"billingcenters": [
{
"sub_request_status": "SUCCESS",
"billingcenter": {
"id": "8b8db2a8-2b48-42f0-858a-88901a782b27",
"updated_at": "2017-10-17T12:25:50.866Z",
"created_at": "2017-10-17T12:25:50.866Z",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"name": "Duck Billing Center",
"email_address": "mr_duck@example.com",
"address_line_1": "11 Duck Pond Avenue",
"locality": "London",
"administrative_district_level_1": "GB-LND",
"country": "GB",
"postal_code": "NW1 4RY"
}
},
{
"sub_request_status": "SUCCESS",
"billingcenter": {
"id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd",
"updated_at": "2020-02-30T09:49:52.118Z",
"created_at": "2020-02-30T09:49:52.118Z",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"name": "Kianjous Billing Center",
"email_address": "honeybear_ltd@example.com",
"address_line_1": "10 Honey Bear Road",
"locality": "London",
"administrative_district_level_1": "GB-LND",
"country": "GB",
"postal_code": "NW1 4RY",
"alternative_email_addresses": [
"honeybear_burrow@example.com"
]
}
}
]
}
The following API request retrieves all Billing Centers for an Organization.
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/billingcenters
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Get a specific Billing Center
curl "https://adsapi.snapchat.com/v1/billingcenters/6e0f4532-3702-4f0b-9889-9fe5d0614afd" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eaa9e6000ff0570e6188bd1110001737e616473617069736300016275696c642d63386238336332372d312d3334372d3100010138",
"billingcenters": [
{
"sub_request_status": "SUCCESS",
"billingcenter": {
"id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd",
"updated_at": "2020-02-30T09:49:52.118Z",
"created_at": "2020-02-30T09:49:52.118Z",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"name": "Kianjous Billing Center",
"email_address": "honeybear_ltd@example.com",
"address_line_1": "10 Honey Bear Road",
"locality": "London",
"administrative_district_level_1": "GB-LND",
"country": "GB",
"postal_code": "NW1 4RY",
"alternative_email_addresses": [
"honeybear_burrow@example.com"
]
}
}
]
}
The following API request retrieves a specific Billing Center.
HTTP Request
GET https://adsapi.snapchat.com/v1/billingcenters/{billing_center_id}
Parameters
Parameter | Default | Description |
---|---|---|
billing_center_id | Billing Center ID |
Create a Billing Center
curl -X POST \
-d '{"billingcenters":[{"organization_id":"8fdeefec-f502-4ca8-9a84-6411e0a51053","name":"Kianjous Billing Center","email_address":"honeybear_ltd@example.com","address_line_1":"10 Honey Bear Road","locality":"London","administrative_district_level_1":"GB-LND","country":"GB","postal_code":"NW1 4RY","alternative_email_addresses":["honeybear_burrow@example.com"]}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/billingcenters
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eaa9f3f00ff0e03450355dbc60001737e616473617069736300016275696c642d63386238336332372d312d3334372d310001010b",
"billingcenters": [
{
"sub_request_status": "SUCCESS",
"billingcenter": {
"id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd",
"updated_at": "2020-02-30T09:49:52.118Z",
"created_at": "2020-02-30T09:49:52.118Z",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"name": "Kianjous Billing Center",
"email_address": "honeybear_ltd@example.com",
"address_line_1": "10 Honey Bear Road",
"locality": "London",
"administrative_district_level_1": "GB-LND",
"country": "GB",
"postal_code": "NW1 4RY",
"alternative_email_addresses": [
"honeybear_burrow@example.com"
]
}
}
]
}
The following API request creates a new Billing Center.
HTTP Request
POST https://adsapi.snapchat.com/v1/organizations/{organization_id}/billingcenters
Parameters
Parameter | Default | Description |
---|---|---|
billing_center_id | Billing Center ID |
Update a Billing Center
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"billingcenters":[{"id":"6e0f4532-3702-4f0b-9889-9fe5d0614afd","organization_id":"1fdeefec-f502-4ca8-9a84-6411e0a51053","name":"Kianjous Billing Center","email_address":"honeybear_ltd@example.com","address_line_1":"10 Honey Bear Road","locality":"London","administrative_district_level_1":"GB-LND","country":"GB","postal_code":"NW1 4RY","alternative_email_addresses":["honeybear_burrow@example.com","mr_duck@example.com"]}]}'
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/billingcenters
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eac190700ff04ae16ca53679d0001737e616473617069736300016275696c642d38653566343030352d312d3334382d3000010107",
"billingcenters": [
{
"sub_request_status": "SUCCESS",
"billingcenter": {
"id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd",
"updated_at": "2020-05-01T12:41:43.470Z",
"created_at": "2020-04-30T09:49:52.118Z",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"name": "Kianjous Billing Center",
"email_address": "honeybear_ltd@example.com",
"address_line_1": "10 Honey Bear Road",
"locality": "London",
"administrative_district_level_1": "GB-LND",
"country": "GB",
"postal_code": "NW1 4RY",
"alternative_email_addresses": [
"honeybear_burrow@example.com",
"mr_duck@example.com"
]
}
}
]
}
The following API request updates a Billing Center with new details.
Attributes that can be updated
Attribute | Required |
---|---|
name | R |
email_address | R |
address_line_1 | R |
locality | R |
administrative_district_level_1 | R |
country | R |
postal_code | R |
alternative_email_addresses | O |
HTTP Request
PUT https://adsapi.snapchat.com/v1/organizations/{organization_id}/billingcenters
Parameters
Parameter | Default | Description |
---|---|---|
billing_center_id | Billing Center ID |
Invoices
Invoices can only be created by Snap, Invoices are allocated on an Ad Account basis and can be fetched by an member with one of the following roles, Organization Admin, Ad Account Admin, or Campaign Manager.
Attributes
Attribute | Description | Possible Values |
---|---|---|
org_id | Organization ID | |
invoice_id | Invoice ID | |
netsuite_file_id | Snap Internal ID | |
ad_account_id | Ad Account ID | |
customer.name | Customer name | |
customer.netsuite_id | Snap Internal ID | |
document_number | Document number | |
line_last_modified | Date | |
last_modified | Date | |
amount_cent | Invoice amount in cents | |
currency | Currency of the invoice | AUD, CAD, EUR, GBP, USD, SEK, DKK, NOK |
billing_period | Specifies the billing period | |
due_date | Due date of the invoice | |
created_at | Creation date of the invoice | |
invoice_status | Indicates whether the invoice has been collected | COLLECTED, SENT_FOR_COLLECTION |
invoice_content | Bytestream (Base64), this Bytestream can turned into a PDF |
List invoices by Ad Account
curl "https://adsapi.snapchat.com/v1/adaccounts/88cdd2d0-b604-455a-925b-b8eb68823e48/invoices" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f0f19d700ff0306e63ea5ff00980001737e616473617069736300016275696c642d61646161313865312d312d3336372d3000010102",
"invoices": [
{
"sub_request_status": "SUCCESS",
"invoice": {
"org_id": "8ba72a1b-0901-4b9e-951a-e39b9ad27aa3",
"invoice_id": "861b7c55-7e35-4348-918f-3758db350b80",
"netsuite_file_id": "5910692",
"ad_account_id": "88cdd2d0-b604-455a-925b-b8eb68823e48",
"customer": {
"name": "Badger Tunneling Inc.",
"netsuite_id": "8828020"
},
"document_number": "146810",
"line_last_modified": "2020-05-14T08:20:00.000Z",
"last_modified": "2020-05-14T08:20:00.000Z",
"amount_cent": 1171496,
"currency": "USD",
"billing_period": "April 2020",
"due_date": "2020-06-05T00:00:00.000Z",
"created_at": "2020-05-02T06:45:00.000Z",
"invoice_status": "COLLECTED"
}
},
{
"sub_request_status": "SUCCESS",
"invoice": {
"org_id": "8ba72a1b-0901-4b9e-951a-e39b9ad27aa3",
"invoice_id": "8848a897-e1b7-4433-a9a1-78fbafb5d52b",
"netsuite_file_id": "8036582",
"ad_account_id": "88cdd2d0-b604-455a-925b-b8eb68823e48",
"customer": {
"name": "Badger Tunneling Inc.",
"netsuite_id": "8828020"
},
"document_number": "151141",
"line_last_modified": "2020-06-09T08:34:00.000Z",
"last_modified": "2020-06-09T08:34:00.000Z",
"amount_cent": 375222,
"currency": "USD",
"billing_period": "May 2020",
"due_date": "2020-07-05T00:00:00.000Z",
"created_at": "2020-06-02T07:05:00.000Z",
"invoice_status": "COLLECTED"
}
},
{
"sub_request_status": "SUCCESS",
"invoice": {
"org_id": "8ba72a1b-0901-4b9e-951a-e39b9ad27aa3",
"invoice_id": "8be7c07f-b1dc-4aca-9729-348bf05b67a6",
"netsuite_file_id": "8170796",
"ad_account_id": "88cdd2d0-b604-455a-925b-b8eb68823e48",
"customer": {
"name": "Badger Tunneling Inc.",
"netsuite_id": "8828020"
},
"document_number": "154209",
"line_last_modified": "2020-07-07T16:15:00.000Z",
"last_modified": "2020-07-07T16:15:00.000Z",
"amount_cent": 1329360,
"currency": "USD",
"billing_period": "June 2020",
"due_date": "2020-08-06T00:00:00.000Z",
"created_at": "2020-07-02T04:53:00.000Z",
"invoice_status": "SENT_FOR_COLLECTION"
}
}
]
}
This endpoint will list all invoices for a given Ad Account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/invoices
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Get individual Invoice
curl "https://adsapi.snapchat.com/v1/adaccounts/04cdd2d0-b604-455a-925b-b8eb68823e48/invoices/2be7c07f-b1dc-4aca-9729-348bf05b67a6" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f107ce000ff0da20b969610630001737e616473617069736300016275696c642d61646161313865312d312d3336372d3000010131",
"invoices": [
{
"sub_request_status": "SUCCESS",
"invoice": {
"org_id": "eba72a1b-0901-4b9e-951a-e39b9ad27aa3",
"invoice_id": "2be7c07f-b1dc-4aca-9729-348bf05b67a6",
"netsuite_file_id": "6216757",
"ad_account_id": "04cdd2d0-b604-455a-925b-b8eb68823e48",
"customer": {
"name": "Flo Health, Inc.",
"netsuite_id": "7828020"
},
"document_number": "154209",
"line_last_modified": "2020-07-15T09:03:00.000Z",
"last_modified": "2020-07-15T09:03:00.000Z",
"amount_cent": 1329360,
"currency": "USD",
"billing_period": "June 2020",
"due_date": "2020-08-06T00:00:00.000Z",
"created_at": "2020-07-02T04:53:00.000Z",
"invoice_status": "COLLECTED"
}
}
]
}
This endpoint retrieve an individual invoice for a given Ad Account
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/invoices/{invoice_id}
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID | |
invoice_id | Invoice ID | |
include_pdf | false | optional parameter for retrieving the invoice_content attribute |
Example 1 - Invoice
Retrieving an invoice
curl "https://adsapi.snapchat.com/v1/adaccounts/9d874f18-8a86-422b-a4c0-67525472f339/invoices/93106732-4504-4220-83f6-035c30bf38a9" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f15b33d00ff04a2f415f889b70001737e616473617069736300016275696c642d65626530306366642d312d3336382d300001014c",
"invoices": [
{
"sub_request_status": "SUCCESS",
"invoice": {
"org_id": "96412453-e008-4353-a8da-881ed5170e9c",
"invoice_id": "93106732-4504-4220-83f6-035c30bf38a9",
"netsuite_file_id": "9214559",
"ad_account_id": "9d874f18-8a86-422b-a4c0-67525472f339",
"customer": {
"name": "Hedgehogs interactive Ltd",
"netsuite_id": "90053849"
},
"document_number": "150239",
"line_last_modified": "2020-07-14T23:43:00.000Z",
"last_modified": "2020-07-14T23:43:00.000Z",
"amount_cent": 132095,
"currency": "USD",
"billing_period": "May 2020",
"due_date": "2020-07-05T00:00:00.000Z",
"created_at": "2020-06-02T02:54:00.000Z",
"invoice_status": "COLLECTED"
}
}
]
}
This example retrieves an individual invoice.
Example 2 - Invoice - invoice_content
Retrieving an invoice with invoice_content
curl "https://adsapi.snapchat.com/v1/adaccounts/9e08d5dd-023b-429e-904c-0924291dc478/invoices/9db4ab51-6402-4b20-b47b-a893267dfb3f?include_pdf=true" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f15b5cd00ff0781f49f7748b80001737e616473617069736300016275696c642d65626530306366642d312d3336382d3000010150",
"invoices": [
{
"sub_request_status": "SUCCESS",
"invoice": {
"org_id": "97433ff4-1fb6-416f-b726-069624ac1de2",
"invoice_id": "9db4ab51-6402-4b20-b47b-a893267dfb3f",
"netsuite_file_id": "5489672",
"ad_account_id": "9e08d5dd-023b-429e-904c-0924291dc478",
"customer": {
"name": "Le Chipmunks Inc",
"netsuite_id": "1277123"
},
"document_number": "124357",
"line_last_modified": "2020-02-21T02:11:00.000Z",
"last_modified": "2020-02-21T02:11:00.000Z",
"amount_cent": 953057,
"currency": "EUR",
"billing_period": "November 2019",
"due_date": "2020-02-03T00:00:00.000Z",
"created_at": "2019-12-02T15:41:00.000Z",
"invoice_content": "JVBERi0xLjMKJd/++LIKMSAwIG9iago8PC ... emUgMzI+PgpzdGFydHhyZWYKMjY1ODQKJSVFT0YK",
"invoice_status": "COLLECTED"
}
}
]
}
This example retrieves an individual invoice for with the parameter include_pdf which adds the attribute invoice_content
on the invoice entity that is returned.
Transactions
Transactions enable businesses to manage and track all financial exchanges within the Snap Business Manager.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
organization_id | Organization ID | R | |
account_id | Ad Account ID | R | |
payment_action_id | Payment Action ID | R | |
payment_action_type | Payment Type | R | AUTHORIZATION, CHARGE, CORRECTION, REFUND, VERIFICATION, UNRECOGNIZED. |
credential_id | Credential ID | R | |
credential_type | Credential Type | R | COUPON, CREDIT_CARD, DIRECT_DEBIT, IN_APP_PURCHASE, LINE_OF_CREDIT, PAYPAL, PREPAY, SNAPCHAT. |
payment_items | Array of Payment Items. See table below | R | |
status | Transaction Status | R | COMPLETED, FAILED, PENDING, UNRECOGNIZED. |
total_amount | Transaction Amount | R | { “amount”: Number, “currency_type”: “USD”} |
Payment Item
Attribute | Description | Required | Possible Values |
---|---|---|---|
payment_item_id | Payment Item ID | R | |
name | Payment Item Name | R | |
start_date | Start Date in ISO time string | R | |
end_date | End Date in ISO time string | R | |
subtotal_amount.amount | Item Amount | R | |
subtotal_amount.currency_type | Item Amount Currency | R | USD, CAD, GBP, EUR, AUD |
Get all Transactions
curl "https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/transactions" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "1f4f4b52-91cc-4d9a-9bdf-f7aa93337df2",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"transactions": [
{
"sub_request_status": "SUCCESS",
"transaction": {
"id": "755d42ac-13b9-492f-95a5-628455fd8331",
"account_id": "ea3e370f-43ae-5h53-8f10-1d2z47d9778a",
"payment_items": [
{
"payment_item_id": "23c06de7-526b-472c-a041-c3da568e5b00",
"name": "Example Transactions",
"start_date": "2023-10-07T04:00:00.000Z",
"end_date": "2023-10-08T03:59:59.999Z",
"subtotal_amount": {
"amount": 585,
"currency_type": "USD"
},
"quantity": 1847
},
{
"payment_item_id": "23c06de7-526b-471c-a041-c3da568e5b00",
"name": "Example Transactions",
"start_date": "2023-10-07T04:00:00.000Z",
"end_date": "2023-10-08T03:59:59.999Z",
"subtotal_amount": {
"amount": 79000,
"currency_type": "USD"
},
"quantity": 469559
},
],
"payment_action_id": "90dbd505-577b-4249-81e6-377be22ed8d3",
"payment_action_type": "CHARGE",
"credential_type": "LINE_OF_CREDIT",
"credential_id": "288194d8-02bb-4719-a448-28g865e3e213",
"payment_method_id": "e703eb9f-8eac-4eda-deec3935444d",
"total_amount": {
"amount": 210252,
"currency_type": "USD"
},
"status": "COMPLETED",
"created_time": "2023-10-08T10:31:14.804Z",
"last_update_time": "2023-10-08T10:31:15.684Z"
}
}
]
}
The following API request retrieves all Transactions for an Organization.
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/transactions
Parameters
Parameter | Default | Description |
---|---|---|
start_time | Start time of transactions in UTC yyyy-mm-ddThh:mm:ss | |
end_time | End time of transactions in UTC yyyy-mm-ddThh:mm:ss | |
ad_account_id | Ad Account ID of the ad account to retrieve |
Ad Accounts
An Ad Account is owned by an Organization and contains Ad Campaigns. Ad Accounts have one or more Funding Sources (Credit card, Paypal, Lines of Credit etc).
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
advertiser | Name of the Advertiser | R | User input |
currency | Account currency | R | AUD, DKK, CAD, EUR, GBP, NOK, SEK, USD |
funding_source_ids | Array of Funding Source IDs | R | |
billing_type | Type of billing | R | IO, REVOLVING |
name | Account name | R | User input |
organization_id | Organization ID | R | |
test | Indicates Ad Account is a test ad account, test ad accounts can never serve live ads | O | true |
timezone | Account timezone, remember to take the time differences into account when you set up your application. All our timings are stored in UTC which means you are required to add/remove hours to make up a full 24 hours when using the DAY granularity in the API | R | Africa/Cairo, Africa/Johannesburg, America/Anchorage, America/Cancun, America/Chicago, America/Dawson, America/Dawson_Creek, America/Denver, America/Edmonton, America/Halifax, America/Hermosillo, America/Los_Angeles, America/Mazatlan, America/Mexico_City, America/Montevideo, America/New_York, America/Phoenix, America/Rainy_River, America/Regina, America/Tijuana, America/Toronto, America/Vancouver, Asia/Amman, Asia/Beirut, Asia/Dubai, Asia/Hong_Kong, Asia/Irkutsk, Asia/Jerusalem, Asia/Kamchatka, Asia/Krasnoyarsk, Asia/Magadan, Asia/Nicosia, Asia/Omsk, Asia/Qatar, Asia/Riyadh, Asia/Shanghai, Asia/Singapore, Asia/Vladivostok, Asia/Yakutsk, Asia/Yekaterinburg, Atlantic/Canary, Australia/Perth, Australia/Sydney, Europe/Amsterdam, Europe/Berlin, Europe/Brussels, Europe/Dublin, Europe/Helsinki, Europe/Istanbul, Europe/Kaliningrad, Europe/London, Europe/Luxembourg, Europe/Madrid, Europe/Malta, Europe/Moscow, Europe/Oslo, Europe/Paris, Europe/Rome, Europe/Samara, Europe/Stockholm, Europe/Vienna, Europe/Vilnius, Europe/Warsaw, Europe/Zurich, Pacific/Auckland, Pacific/Honolulu, UTC |
type | Account type | R | DIRECT, PARTNER |
lifetime_spend_cap_micro | Required if billing_type is set to IO, the lifetime spend cap of the account in micro currency | O | |
advertiser_organization_id | Organization ID of the Advertiser selected | read-only | |
paying_advertiser_name | Name of the paying advertiser/political entity, required if the Ad Account will contain political/advocacy ads | O | max 32 characters |
regulations | Required if the Ad Account will contain ads for Credit, Housing or Employment, this attribute is immutable once set to true | O | { “restricted_delivery_signals”: true } |
agency_representing_client | Account name | R | true/false |
client_based_in_country | Required if agency_representing_client is true and if Advertiser is based in France or targeting Ads to audiences in France |
O | FR |
client_paying_invoices | Required if agency_representing_client is true and if Advertiser is based in France or targeting Ads to audiences in France |
O | true/false |
agency_client_metadata | Client metadata is required if agency_representing_client is true and if the Advertiser is based in France or is targeting Ads to audiences in France |
O | JSON object containing the attributes; name, email, address_line_1, city,administrative_district_level_1, country, zipcode, tax_id |
delivery_status | Delivery status | Read-only | See Delivery status |
Create an Ad Account
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adaccounts": [{"name": "Example Ad Account","type": "PARTNER","status": "ACTIVE","organization_id": "7fdeefec-f502-4ca8-9a84-6411e0a51058","funding_source_ids": ["6ca1687a-f2b4-437d-8554-a85403a714c5"],"currency": "USD","billing_type": "IO","billing_center_id": "9b8db2a8-2b48-42f0-858a-88901a782b27","lifetime_spend_cap_micro": "200000000000","timezone": "America\/Los_Angeles","advertiser": "Example Advertiser Inc"}]}' \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/adaccounts
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e7b42c900ff0e76f111031c2c0001737e616473617069736300016275696c642d62313763613636652d312d3333372d3200010122",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "7c6d2e91-3a7c-4230-b048-f724bf217a82",
"updated_at": "2020-03-25T11:38:50.273Z",
"created_at": "2020-03-25T11:38:50.273Z",
"name": "Example Ad Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"funding_source_ids": [
"6ca1687a-f2b4-437d-8554-a85403a714c5"
],
"currency": "USD",
"timezone": "America/Los_Angeles",
"advertiser": "Example Advertiser Inc",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"billing_center_id": "9b8db2a8-2b48-42f0-858a-88901a782b27",
"billing_type": "IO",
"lifetime_spend_cap_micro": 200000000000,
"agency_representing_client": false,
"client_paying_invoices": false
}
}
]
}
This endpoint creates an Ad Account within the specified Organization. When setting up new Ad Accounts it’s important to take the below factors into account, not following these points may cause the Ad Account to be suspended.
If the ad account will be used for housing, credit or employment advertising it needs to have the attribute
regulations.restricted_delivery_signals
set totrue
If the ad account will be used for political advertising the attribute
paying_advertiser_name
needs to be filled out with the political organization or advocacy group who is paying for the ad (32 character limit)If the Ad Account is owned by an agency buying ads on behalf of an advertiser the attribute
agency_representing_client
needs to be set totrue
If the Ad Account is owned by an agency buying ads on behalf of an advertiser, and the Advertiser is based in France, or will target ads to an audience in France, the following settings will apply:
- The attribute
agency_representing_client
needs to be set totrue
- The attribute
client_paying_invoices
needs to be set totrue
if the agency is paying the invoices, orfalse
if the advertiser they represent is paying the invoices - The attribute
client_based_in_country
needs to be set tofr
- The attribute
agency_client_metadata
needs to be set using the attributesname
,email
,address_line_1
,city
,administrative_district_level_1
,country
,zipcode
andtax_id
- The attribute
HTTP Request
POST https://adsapi.snapchat.com/v1/organizations/{organization_id}/adaccounts
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Get All Ad Accounts
curl "https://adsapi.snapchat.com/v1/organizations/{organization_id}/adaccounts" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0015e00ff07d5c0c38928ad0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010107",
"adaccounts": [
{
"sub_request_status": "success",
"adaccount": {
"id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"updated_at": "2016-08-11T22:03:58.869Z",
"created_at": "2016-08-11T22:03:58.869Z",
"name": "Hooli Test Ad Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"funding_source_ids": [
"e703eb9f-8eac-4eda-a9c7-deec3935222d"
],
"currency": "USD",
"timezone": "America/Los_Angeles",
"advertiser": "Hooli"
}
},
{
"sub_request_status": "success",
"adaccount": {
"id": "81cf9302-764c-429a-8561-e3bc329cf987",
"updated_at": "2016-08-11T22:03:58.869Z",
"created_at": "2016-08-11T22:03:58.869Z",
"name": "Awesome Ad Account",
"type": "DIRECT",
"status": "ACTIVE",
"organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"funding_source_ids": [
"7abfb9c6-0258-4eee-9898-03a8c099695d"
],
"currency": "USD",
"timezone": "America/Los_Angeles",
"advertiser": "Hooli"
}
}
]
}
This endpoint retrieves all ad accounts for the specified Organization.
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/{organization-id}/adaccounts
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Get a Specific Ad Account
curl "https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0021900ff06bbfeb44f77240001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010e",
"adaccounts": [
{
"sub_request_status": "success",
"adaccount": {
"id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"updated_at": "2016-08-11T22:03:58.869Z",
"created_at": "2016-08-11T22:03:58.869Z",
"name": "Hooli Test Ad Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"funding_source_ids": [
"e703eb9f-8eac-4eda-a9c7-deec3935222d"
],
"currency": "USD",
"timezone": "America/Los_Angeles",
"advertiser": "Hooli"
}
}
]
}
This endpoint retrieves a specific Ad Account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}
URL Parameters
Parameter | Description |
---|---|
ad_account_id | Ad Account ID of the ad account to retrieve |
Update Ad Account
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adaccounts": [{"type": "PARTNER","advertiser": "Example Advertiser Inc","advertiser_organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053","billing_center_id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd","billing_type": "IO","currency": "USD","id": "7c6d2e91-3a7c-4230-b048-f724bf217a82","lifetime_spend_cap_micro": 200000000000,"name": "Example Ad Account","organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053","funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],"status": "ACTIVE","timezone": "America/Los_Angeles","agency_representing_client": false,"client_paying_invoices": false}]}'
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/adaccounts
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eac3e0c00ff07836d9acd3b2a0001737e616473617069736300016275696c642d38653566343030352d312d3334382d3000010137",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "7c6d2e91-3a7c-4230-b048-f724bf217a82",
"updated_at": "2020-05-01T15:19:41.536Z",
"created_at": "2020-03-25T11:38:50.273Z",
"name": "Example Ad Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"funding_source_ids": [
"5ca1687a-f2b4-437d-8554-a85403a714c5"
],
"currency": "USD",
"timezone": "America/Los_Angeles",
"advertiser": "Example Advertiser Inc",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"billing_center_id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd",
"billing_type": "IO",
"lifetime_spend_cap_micro": 200000000000,
"agency_representing_client": false,
"client_paying_invoices": false
}
}
]
}
This endpoint updates a specific Ad Account.
Attributes that can be updated
Attribute | Required |
---|---|
name | R |
advertiser | R |
billing_center_id | R |
lifetime_spend_cap_micro | R |
regulations.restricted_delivery_signals | R |
agency_representing_client | R |
paying_advertiser_name | O |
client_paying_invoices | O |
client_based_in_country | O |
agency_client_metadata | O |
HTTP Request
PUT https://adsapi.snapchat.com/v1/organizations/{organization_id}/adaccounts
URL Parameters
Parameter | Description |
---|---|
organization_id | Organization ID of the Organization to which the Ad Account belongs |
Update an Ad Account’s Lifetime Spend Cap
curl -X PUT \
-H 'Authorization: Bearer meowmeowmeow' \
-H 'Content-Type: application/json' \
-d '{"adaccounts": [{"id":"123b9ca6-92f2-49c3-a3ed-0ea58afb467e","name":"Hooli Ad Account","type":"PARTNER","status":"ACTIVE","organization_id":"40c6719b-da09-410b-9185-0cc9c0dfed1d","funding_source_ids":["cdc67eba-a774-4954-9b94-9502bbdac1bc"],"currency":"USD","timezone":"America/Los_Angeles","brand_name":"Hooli","lifetime_spend_cap_micro":1500000000
}]}' \
https://adsapi.snapchat.com/v1/organizations/40c6719b-da09-410b-9185-0cc9c0dfed1d/adaccounts
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0021900ff06bbfeb44f77240001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010e",
"adaccounts": [
{
"sub_request_status": "success",
"adaccount": {
"id": "123b9ca6-92f2-49c3-a3ed-0ea58afb467e",
"updated_at": "2016-08-11T22:03:58.869Z",
"created_at": "2016-08-11T22:03:58.869Z",
"name": "Hooli Ad Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "40c6719b-da09-410b-9185-0cc9c0dfed1d",
"funding_source_ids": [
"e703eb9f-8eac-4eda-a9c7-deec3935222d"
],
"currency": "USD",
"timezone": "America/Los_Angeles",
"brand_name":"Hooli",
"lifetime_spend_cap_micro":1500000000
}
}
]
}
This endpoint updates the Lifetime Spend Limit of a specific ad account, this can only be updated for Ad Accounts where the billing_type
is set to IO
. Please note that once the Lifetime Spend Limit is set for a specific ad account, it can only be increased or decreased but not removed.
Assign Funding Source
Assigning funding sources to ad accounts can be done in Business Manager. Please reach out to your partner manager for further assistance.
Ad Account creation - Example 1
Ad Account - Used for Political advertising
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adaccounts": [{"name": "Votes for Dogs Account","type": "PARTNER","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],"currency": "GBP","timezone": "Europe/London","advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27","billing_type": "REVOLVING","agency_representing_client": false,"client_paying_invoices": false,"paying_advertiser_name": "The Pugs & Poodle Alliance","regulations": {"restricted_delivery_signals": false}}]}' \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/adaccounts
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eac0cdb00ff06d4845e8997c40001737e616473617069736300016275696c642d38653566343030352d312d3334382d300001015f",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "2b0efb26-973b-4085-aef1-bd0bef429b91",
"updated_at": "2020-05-01T11:49:48.045Z",
"created_at": "2020-05-01T11:49:48.045Z",
"name": "Votes for Dogs Account",
"type": "PARTNER",
"status": "PENDING",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"funding_source_ids": [
"5ca1687a-f2b4-437d-8554-a85403a714c5"
],
"currency": "GBP",
"timezone": "Europe/London",
"paying_advertiser_name": "The Pugs & Poodle Alliance",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27",
"billing_type": "REVOLVING",
"agency_representing_client": false,
"client_paying_invoices": false,
"regulations": {
"restricted_delivery_signals": false
}
}
}
]
}
This request creates an Ad account that will be used for Political or Advocacy Ads, it contains the attribute paying_advertiser_name
.
Ad Account creation - Example 2
Ad Account - Used for Credit, Housing, Employment Ads
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adaccounts": [{"name": "Account for Credit Housing Employment Ads","type": "PARTNER","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],"currency": "EUR","timezone": "Europe/Paris","advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27","billing_type": "REVOLVING","agency_representing_client": false,"client_paying_invoices": false,"regulations": {"restricted_delivery_signals": true}}]}' \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/adaccounts
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eac0e1600ff0abfa792ff005a320001737e616473617069736300016275696c642d38653566343030352d312d3334382d3000010153",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "f249cfe1-973f-4a04-899a-c1f65b9070a0",
"updated_at": "2020-05-01T11:55:03.343Z",
"created_at": "2020-05-01T11:55:03.343Z",
"name": "Account for Credit Housing Employment Ads",
"type": "PARTNER",
"status": "PENDING",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"funding_source_ids": [
"5ca1687a-f2b4-437d-8554-a85403a714c5"
],
"currency": "EUR",
"timezone": "Europe/Paris",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27",
"billing_type": "REVOLVING",
"agency_representing_client": false,
"client_paying_invoices": false,
"regulations": {
"restricted_delivery_signals": true
}
}
}
]
}
This request creates an Ad account that can be used for housing, credit and employment ads, the restricted_delivery_signals
within the regulations
attribute has been set to true
.
Ad Account creation - Example 3
Ad Account - Agency representing client, client based in France or targeting France
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{ "adaccounts": [{"name": "délicieux aliments pour chiens","type": "PARTNER","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],"currency": "EUR","timezone": "Europe/Paris","advertiser_organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053","billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27","billing_type": "REVOLVING","agency_representing_client": true,"client_based_in_country": "FR","client_paying_invoices": false,"agency_client_metadata": {"name": "Madamemoiselle Poodle","email": "poodle_client@example.com","address_line_1": "101 Boulevard la Fayette","city": "Paris","administrative_district_level_1": "FR-O","country": "FR","zipcode": "62100","tax_id": "FR12345678900"},"regulations": {"restricted_delivery_signals": false}}]}' \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/adaccounts
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eab157200ff07dcbf0737d8790001737e616473617069736300016275696c642d63386238336332372d312d3334372d3100010128",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "cdfc6dbd-9ac6-416a-b386-d473dd6e6d64",
"updated_at": "2020-04-30T18:14:11.150Z",
"created_at": "2020-04-30T18:14:11.150Z",
"name": "Délicieux aliments pour chiens",
"type": "PARTNER",
"status": "PENDING",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"funding_source_ids": [
"5ca1687a-f2b4-437d-8554-a85403a714c5"
],
"currency": "EUR",
"timezone": "Europe/Paris",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27",
"billing_type": "REVOLVING",
"agency_representing_client": true,
"client_based_in_country": "FR",
"client_paying_invoices": false,
"agency_client_metadata": {
"name": "Madamemoiselle Poodle",
"email": "poodle_client@example.com",
"address_line_1": "101 Boulevard la Fayette",
"city": "Paris",
"administrative_district_level_1": "FR-O",
"country": "FR",
"zipcode": "62100",
"tax_id": "FR12345678900"
},
"regulations": {
"restricted_delivery_signals": false
}
}
}
]
}
This request creates an Ad Account that is owned by an Agency representing a client, where the Advertiser is paying the invoices and where the Advertiser is based in France, or where the Ad Account will target ads to audience in France.
agency_representing_client
has been set totrue
client_based_in_country
has been set toFR
client_paying_invoices
has been set tofalse
as the Advertiser is paying the invoices (note that this should be set totrue
if the Agency pays the invoices)agency_client_metadata
has been filled out with the address of the Advertiser and their French Tax ID
Ad Account creation - Example 4
Ad Account - Setting up a test Ad Account
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adaccounts": [{"name":"The Dalmatian Test Account","type":"PARTNER","status":"ACTIVE","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058","currency": "EUR","timezone": "Europe\/London","advertiser":"Dalmatian Retail", "billing_type":"REVOLVING","billing_center_id":"7b8db2a8-2b48-42f0-858a-88901a782b27","agency_representing_client":false, "client_paying_invoices": false,"test":true}]}' \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/adaccounts
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f68d35200ff0864c8d10ae0dd0001737e616473617069736300016275696c642d35373264613164312d312d3338362d300001013d",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "a54ccc44-12fa-4952-b813-95f5dcfc27e7",
"updated_at": "2020-09-21T16:22:43.094Z",
"created_at": "2020-09-21T16:22:43.094Z",
"name": "The Dalmatian Test Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"currency": "EUR",
"timezone": "Europe/London",
"advertiser": "Dalmatian Retail",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"billing_center_id": "7b8db2a8-2b48-42f0-858a-88901a782b27",
"test": true,
"billing_type": "REVOLVING",
"agency_representing_client": false,
"client_paying_invoices": false
}
}
]
}
This request creates an Ad Account with the test parameter set to true, the resulting Ad Account never will be able to serve ads. The intention of setting up such an Ad Account is to be able to execute write requests without risking that ads will go live.
Members
A Member represents a Snapchat account user who is a member of an Organization, a Member needs to be assigned a Role within both the Organization and individual Ad Accounts in order to access entities.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
display_name | Name of the user | R | |
organization_id | Organization ID | R | |
member_status | Name of the Advertiser | R | INVITED, MEMBER |
email address of the user | R |
Get all Members of an Organization
curl "https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/members" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea05c4800ff08ac5ff42a0f740001737e616473617069736300016275696c642d64313063316333662d312d3334352d3000010102",
"members": [
{
"sub_request_status": "SUCCESS",
"member": {
"id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
"updated_at": "2017-10-17T12:25:50.815Z",
"created_at": "2017-10-17T12:25:50.815Z",
"email": "honeybear@example.com",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"display_name": "Honey Bear",
"member_status": "MEMBER"
}
},
{
"sub_request_status": "SUCCESS",
"member": {
"id": "b124e762-9720-4f89-bdd2-7fe06e71d7cc",
"updated_at": "2020-03-05T11:29:31.562Z",
"created_at": "2018-09-28T19:05:09.787Z",
"email": "jack_the_bear@example.com",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"display_name": "Jack Polarbear",
"member_status": "MEMBER"
}
},
{
"sub_request_status": "SUCCESS",
"member": {
"id": "d051973d-32b2-496b-b44a-345986bce17d",
"updated_at": "2020-04-22T14:56:33.164Z",
"created_at": "2020-04-22T14:45:04.452Z",
"email": "guinea_pig@example.com",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"display_name": "Esmeralda the Guinea Pig",
"member_status": "MEMBER"
}
}
]
}
The following API request returns the information of all Members of an Organization, this includes their display name, email address and member status. Members who have not yet accepted their invite will have the status INVITED, members that have accepted the invite will have the status MEMBER.
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/members
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Get a specific Member
curl "https://adsapi.snapchat.com/v1/members/d051973d-32b2-496b-b44a-345986bce17d" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea05dcf00ff05a0584dcd2c0f0001737e616473617069736300016275696c642d64313063316333662d312d3334352d300001015b",
"members": [
{
"sub_request_status": "SUCCESS",
"member": {
"id": "d051973d-32b2-496b-b44a-345986bce17d",
"updated_at": "2020-04-22T14:56:33.164Z",
"created_at": "2020-02-22T14:45:04.452Z",
"email": "honeybear@example.com",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"display_name": "Honey Bear",
"member_status": "MEMBER"
}
}
]
}
The following API request returns the information of a specific Member.
HTTP Request
GET https://adsapi.snapchat.com/v1/members/{member_id}
Parameters
Parameter | Default | Description |
---|---|---|
member_id | Member ID |
Create Member
curl -X POST \
-d '{"members": [{"email": "honeybear@example.com","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","display_name": "Honey Bear"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/members
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea0587000ff0360f26d1e8c1d0001737e616473617069736300016275696c642d64313063316333662d312d3334352d3000010157",
"members": [
{
"sub_request_status": "SUCCESS",
"member": {
"id": "d051973d-32b2-496b-b44a-345986bce17d",
"updated_at": "2020-04-22T14:45:04.452Z",
"created_at": "2020-04-22T14:45:04.452Z",
"email": "honeybear@example.com",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"display_name": "Honey Bear",
"member_status": "INVITED"
}
}
]
}
The following API request creates a member within the chosen Organization, this will trigger an email invite to the user in question.
When the user accepts the invite the member_status
attribute will update from INVITED to MEMBER. Member creation should always be coupled with a Role creation within the Organization.
HTTP Request
POST https://adsapi.snapchat.com/v1/organizations/{organization_id}/members
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Delete Member
curl -X DELETE "https://adsapi.snapchat.com/v1/members/d051973d-32b2-496b-b44a-345986bce17d" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status":"SUCCESS",
"request_id":"5ea6f3f900ff01fa13ebea326c0001737e616473617069736300016275696c642d39326335343566322d312d3334362d3000010107",
"members":[]
}
The following API request deletes a member from the Organization.
HTTP Request
DELETE https://adsapi.snapchat.com/v1/{{member_id}}
Parameters
Parameter | Default | Description |
---|---|---|
member_id | Member ID |
Roles
Roles exist at two levels, Organization level and Ad Account level.
Organization Roles
Attributes
Attribute. | Description | Required | Possible Values |
---|---|---|---|
member_id | Member ID | R | |
organization_id | Organization ID | R | |
type | Organization role type | R | admin, business_admin, data_admin, member |
A Member
entity must be assigned one of the Organization role types.
Name | Description |
---|---|
admin | Admin access to everything in the Organization and all Ad Accounts including creating, updating, deleting entities, adding new Members, assigning Roles |
business_admin | Can access full Business Manager capabilities (payment methods, roles, organization details), but doesn’t have access to individual ad accounts or catalogs |
data_admin | Reporting Admin role tailored for reporting only, this Role has reporting access only to all Ad Accounts in the Organization |
member | Required for all Members who do not have the admin role, also a prerequisite for Ad Account Roles |
Ad Account Roles
Attributes
Attribute. | Description | Required | Possible Values |
---|---|---|---|
member_id. | Member ID | R | |
ad_account_id | Ad Account ID | R | |
type | Ad Account role type | R | admin, creative, general, reports, audience |
In order to be assigned an Ad Account role the Member in question first needs the Organization role type member
.
Name | Description |
---|---|
admin. | Admin access to everything in the Ad Account |
creative | Has full control of Creative and Media entities, and read access to all other entities. |
general | Has full control of sub-Ad Account level entities (Campaigns, Ad Squads, Ads) |
reports | Has read-only access to the Ad Account for reporting purposes. |
audience | Has full control of Audience entities |
Catalog Roles
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
member_id | Member ID | R | |
catalog_id | Catalog ID | R | |
type | Catalog role type | R | catalog_admin, catalog_advertiser |
In order to be assigned a Catalog role the Member in question first needs the Organization role type member
.
Name | Description |
---|---|
catalog_admin | Catalog Admins can edit and view existing catalogs which they have been assigned to by an Organization Admin, as well as create ads from those catalogs |
catalog_advertiser | Catalog Advertisers can create ads from catalogs which they have been assigned to by an Organization Admin, however they cannot edit those catalogs |
Get Roles for Member
curl "https://adsapi.snapchat.com/v1/members/d051973d-32b2-496b-b44a-345986bce17d/roles?limit=100" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea9654400ff07724b540651010001737e616473617069736300016275696c642d36373239363666352d312d3334372d3000010115",
"paging": {},
"roles": [
{
"sub_request_status": "SUCCESS",
"role": {
"id": "53155cfb-fc21-4d5f-a3dc-2ab7d8c7db03",
"updated_at": "2020-02-04T12:32:22.365Z",
"created_at": "2020-02-04T12:32:22.281Z",
"container_kind": "AdAccounts",
"container_id": "8fb3b893-7978-43d5-81fe-fe0613972092",
"member_id": "d051973d-32b2-496b-b44a-345986bce17d",
"ad_account_id": "8fb3b893-7978-43d5-81fe-fe0613972092",
"type": "reports"
}
},
{
"sub_request_status": "SUCCESS",
"role": {
"id": "9e19db05-340d-4cdf-8de9-09022a2842cf",
"updated_at": "2019-02-06T23:26:11.401Z",
"created_at": "2018-10-17T11:48:58.601Z",
"container_kind": "AdAccounts",
"container_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"member_id": "d051973d-32b2-496b-b44a-345986bce17d",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"type": "admin"
}
},
{
"sub_request_status": "SUCCESS",
"role": {
"id": "ab0e7b9b-e0c0-441e-b26b-90ebd13c564a",
"updated_at": "2019-02-07T00:52:25.576Z",
"created_at": "2018-10-17T11:48:24.559Z",
"container_kind": "Organizations",
"container_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"member_id": "d051973d-32b2-496b-b44a-345986bce17d",
"organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053",
"type": "member"
}
}
]
}
The following API request returns all Roles assigned to a Member, this includes Roles within both Organizations and Ad Accounts.
HTTP Request
GET https://adsapi.snapchat.com/v1/members/{member_id}/roles
Parameters
Parameter | Default | Description |
---|---|---|
something_id | Organization ID | |
limit | integer, min 50, max 1000 |
Get all Roles in Organization
curl "https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/roles?limit=100" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea9636000ff0d8046762797040001737e616473617069736300016275696c642d36373239363666352d312d3334372d300001010c",
"paging": {},
"roles": [
{
"sub_request_status": "SUCCESS",
"role": {
"id": "1001050f-325e-486f-902f-e7eea192755f",
"updated_at": "2019-12-05T14:30:20.480Z",
"created_at": "2019-12-05T14:30:20.480Z",
"container_kind": "Organizations",
"container_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053",
"member_id": "63ef6f6d-09f4-4eb7-aa52-c83bcc35608c",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"type": "admin"
}
},
{
"sub_request_status": "SUCCESS",
"role": {
"id": "10d8b407-40f3-406d-8d04-2d5c59ff55fd",
"updated_at": "2020-03-05T11:29:31.964Z",
"created_at": "2020-03-05T11:29:31.964Z",
"container_kind": "Organizations",
"container_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053",
"member_id": "b124e762-9720-4f89-bdd2-7fe06e71d7cc",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"type": "member"
}
},
{
"sub_request_status": "SUCCESS",
"role": {
"id": "20feac40-828c-46e2-a57b-60b5e0274ce4",
"updated_at": "2020-03-25T17:54:39.170Z",
"created_at": "2020-03-25T17:54:39.170Z",
"container_kind": "Organizations",
"container_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053",
"member_id": "9db3e9a8-b7d4-4bb9-922f-72ea22d10aa6",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"type": "member"
}
},
{
"sub_request_status": "SUCCESS",
"role": {
"id": "57fa3d11-7330-461e-aca0-0d010d5b4932",
"updated_at": "2019-02-06T07:42:30.365Z",
"created_at": "2017-10-17T12:25:50.821Z",
"container_kind": "Organizations",
"container_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053",
"member_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"type": "admin"
}
}
]
}
The following API request returns all Roles assigned within an Organization.
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/roles
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID | |
limit | integer, min 50, max 1000 |
Create Organization Role
curl -X POST \
-d '{"roles": [{"member_id": "d051973d-32b2-496b-b44a-345986bce17d","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","type": "member"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/organizations/1fdeefec-f502-4ca8-9a84-6411e0a51053/roles
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea8334500ff06d6157db3e3d40001737e616473617069736300016275696c642d36373239363666352d312d3334372d3000010137",
"roles": [
{
"sub_request_status": "SUCCESS",
"role": {
"id": "9a121178-73f0-4089-8f80-a60e5445e8ea",
"updated_at": "2020-04-28T13:44:37.586Z",
"created_at": "2020-04-28T13:44:37.586Z",
"container_kind": "Organizations",
"container_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"member_id": "d051973d-32b2-496b-b44a-345986bce17d",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"type": "member"
}
}
]
}
The following API request creates an Organization Role for a Member, this should follow any Member invitation to the Organization.
HTTP Request
POST https://adsapi.snapchat.com/v1/organizations/{organization_id}/roles
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Get all Roles in Ad Account
curl "https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/roles?limit=200" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea85f5100ff0e03a2de2a46760001737e616473617069736300016275696c642d36373239363666352d312d3334372d3000010106",
"paging": {},
"roles": [
{
"sub_request_status": "SUCCESS",
"role": {
"id": "4c73255a-903a-423c-a98d-862bba405ec0",
"updated_at": "2019-05-22T13:04:14.694Z",
"created_at": "2019-05-22T13:04:14.694Z",
"container_kind": "AdAccounts",
"container_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"member_id": "9227efda-b0d4-497e-82b9-0125780892ec",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"type": "creative"
}
},
{
"sub_request_status": "SUCCESS",
"role": {
"id": "e293289e-14d8-432a-9edb-2943b75da2ec",
"updated_at": "2019-02-07T18:08:18.706Z",
"created_at": "2018-10-18T19:41:56.727Z",
"container_kind": "AdAccounts",
"container_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"member_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"type": "admin"
}
},
{
"sub_request_status": "SUCCESS",
"role": {
"id": "f7cd2f3c-de7e-4b4f-b8f4-44f2b428bca9",
"updated_at": "2020-03-25T17:55:01.620Z",
"created_at": "2020-03-25T17:55:01.344Z",
"container_kind": "AdAccounts",
"container_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"member_id": "9db3e9a8-b7d4-4bb9-922f-72ea22d10aa6",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"type": "general"
}
}
]
}
The following API gets a list of all Roles that have been created under an Ad Account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/roles
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID | |
limit | integer, min 50, max 1000 |
Create Ad Account Role
curl -X POST \
-d '{"roles": [{"member_id": "d051973d-32b2-496b-b44a-345986bce17d","ad_account_id": "8c545687-a599-4faa-a704-4b097c6da5fe","type": "creative"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8c545687-a599-4faa-a704-4b097c6da5fe/roles
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea8335700ff09599711db33160001737e616473617069736300016275696c642d36373239363666352d312d3334372d3000010135",
"roles": [
{
"sub_request_status": "SUCCESS",
"role": {
"id": "5191aec7-b771-4c56-9963-126b14dbe2e3",
"updated_at": "2020-02-28T13:44:55.746Z",
"created_at": "2020-02-28T13:44:55.746Z",
"container_kind": "AdAccounts",
"container_id": "8c545687-a599-4faa-a704-4b097c6da5fe",
"member_id": "d051973d-32b2-496b-b44a-345986bce17d",
"ad_account_id": "8c545687-a599-4faa-a704-4b097c6da5fe",
"type": "creative"
}
}
]
}
The following API request creates an Ad Account role for the Member. Note that a prerequisite for an Ad Account role is for the Member to already have a member
role in the Organization under which the Ad Account exists.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/roles
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Update Ad Account Role
curl -X PUT \
-d '{"roles":[{"id":"f7cd2f3c-de7e-4b4f-b8f4-44f2b428bca9","container_kind":"AdAccounts","container_id":"22225ba6-7559-4000-9663-bace8adff5f2","member_id":"9db3e9a8-b7d4-4bb9-922f-72ea22d10aa6","ad_account_id":"22225ba6-7559-4000-9663-bace8adff5f2","type":"general"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "583521e0-da89-48a6-8bc9-195ad595391b",
"roles": [
{
"sub_request_status": "SUCCESS",
"role": {
"id": "f7cd2f3c-de7e-4b4f-b8f4-44f2b428bca9",
"updated_at": "2022-09-21T00:50:46.146Z",
"created_at": "2020-03-25T17:55:01.344Z",
"container_kind": "AdAccounts",
"container_id": "22225ba6-7559-4000-9663-bace8adff5f2",
"member_id": "9db3e9a8-b7d4-4bb9-922f-72ea22d10aa6",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2",
"type": "general"
}
}
]
}
The following API request updates the Ad Account role for a Member.
Attributes that can be updated
Attribute | Description | Required | Possible Values |
---|---|---|---|
type | role type | R | admin, audience, creative, general, reports |
HTTP Request
PUT https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/roles
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create Catalog Role
curl -X POST \
-d '{"roles": [{"member_id": "819eff0f-2673-480b-8f72-c128e61c6cc4","catalog_id": "9318ff5c-78f7-47db-8a32-675f0b787c75","type": "catalog_admin"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/catalogs/9318ff5c-78f7-47db-8a32-675f0b787c75/roles
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "6074452e00ff00ff05354518127f0001737e616473617069736300016275696c642d34303334633634322d312d3433382d320001015c",
"roles": [
{
"sub_request_status": "SUCCESS",
"role": {
"id": "9f53e57d-cdbc-4c04-901d-bbe940b2a36c",
"updated_at": "2021-04-12T13:03:42.378Z",
"created_at": "2021-04-12T13:03:42.378Z",
"container_kind": "Catalogs",
"container_id": "8318ff5c-78f7-47db-8a32-675f0b787c75",
"member_id": "819eff0f-2673-480b-8f72-c128e61c6cc4",
"catalog_id": "9318ff5c-78f7-47db-8a32-675f0b787c75",
"type": "catalog_admin"
}
}
]
}
The following API request creates a Catalog role for the Member. Note that a prerequisite for a Catalog role is for the Member to already have a member
role in the Organization under which the Catalog exists.
HTTP Request
POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/roles
Parameters
Parameter | Default | Description |
---|---|---|
catalog_id | Catalog ID |
Get all Roles for Catalog
curl "https://adsapi.snapchat.com/v1/catalogs/9318ff5c-78f7-47db-8a32-675f0b787c75/roles?limit=200" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "60744c2d00ff0e2580408852b00001737e616473617069736300016275696c642d34303334633634322d312d3433382d320001012b",
"paging": {},
"roles": [
{
"sub_request_status": "SUCCESS",
"role": {
"id": "9f53e57d-cdbc-4c04-901d-bbe940b2a36c",
"container_kind": "Catalogs",
"container_id": "8318ff5c-78f7-47db-8a32-675f0b787c75",
"member_id": "919eff0f-2673-480b-8f72-c128e61c6cc4",
"catalog_id": "9318ff5c-78f7-47db-8a32-675f0b787c75",
"type": "catalog_admin"
}
},
{
"sub_request_status": "SUCCESS",
"role": {
"id": "9e85e2f6-e6fe-4bc8-883d-a7d839c3e5bd",
"container_kind": "Catalogs",
"container_id": "8318ff5c-78f7-47db-8a32-675f0b787c75",
"member_id": "971cfcae-895d-4314-9460-e2ffd2515dd0",
"catalog_id": "9318ff5c-78f7-47db-8a32-675f0b787c75",
"type": "catalog_advertiser"
}
}
]
}
The following API request gets a list of all Roles that have been created under a Catalog.
HTTP Request
GET https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/roles
Parameters
Parameter | Default | Description |
---|---|---|
catalog_id | Catalog ID | |
limit | integer, min 50, max 1000 |
Public Profiles Roles
Attributes
API Attribute | Ads Manager | Description |
---|---|---|
business_account_manager | Admin | Can change Public Profiles, add or remove any Snaps from Public Story, manage Saved Stories, assign roles and view insights |
business_account_collaborator | Collaborator | Can view insights and add or remove any Snaps from their Public Story within a profile |
business_account_story_contributor | Story Contributor | Can view all past Snaps. They can also add, remove and view insights on Snaps they post within a profile. |
business_account_data_analyst | Insights Viewer | Can view the profile’s Public Story, Saved Story, Lens and profile analytics. |
creative_contributor | Creative Contributor | Can submit content, such as Lenses, to profile’s Public Profile. |
Delete Role
curl -X DELETE "https://adsapi.snapchat.com/v1/roles/5191aec7-b771-4c56-9963-126b14dbe2e3" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea8338a00ff0ded779b7f217a0001737e616473617069736300016275696c642d36373239363666352d312d3334372d3000010130",
"roles": []
}
The following API request removes a Role from an Organisation, Catalog or Ad Account. If you are deleting all of a Member’s Roles, you should also delete the Member entity from the Organization.
HTTP Request
DELETE https://adsapi.snapchat.com/v1/roles/{role_id}
Parameters
Parameter | Default | Description |
---|---|---|
role_id | Role ID |
Campaigns
A campaign has a business objective and organizes Ad Squads. You can define a goal and view stats for this campaign to see whether your goal has been reached. The reports and stats combines all the ad squads within this campaign.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
daily_budget_micro | Daily Spend Cap (micro-currency) | O | |
end_time | End time | O | |
name | Campaign name | R | max length: 375 characters |
start_time | Start time | R | |
status | Campaign status | R | ACTIVE, PAUSED |
lifetime_spend_cap_micro | Lifetime spend cap for the campaign (microcurrency) | O | |
measurement_spec | The apps to be tracked for this campaign | R - Required for tracking installs for campaigns containing these ad types: APP_INSTALL, DEEP_LINK, STORY (which swipes up to APP_INSTALL, DEEP_LINK) LENS_APP_INSTALL, LENS_DEEP_LINK | {“ios_app_id”:“1234”, “android_app_url”:“com.snapchat.android”} |
objective | Objective of the Campaign | O | BRAND_AWARENESS (default), APP_CONVERSION, APP_INSTALL, CATALOG_SALES, ENGAGEMENT, LEAD_GENERATION, VIDEO_VIEW, WEB_CONVERSION, PROMOTE_STORIES, PROMOTE_PLACES |
buy_model** | Buy Model | O | AUCTION(default), RESERVED |
regulations++ | Required for Campaigns that run Ads for Credit, Housing, Employment (CHE) | O | { “restricted_delivery_signals”: true } |
regulations+- | The candidate / ballot field is optional, but may be required in certain states | O | { “candidate_ballot_information”:“Voting rights for dogs” } |
delivery_status | Delivery status | Read-only | See Delivery status |
deleted | Indicates whether the entity has been deleted or not, only shown when using the parameter read_deleted_entities |
Read-only | true |
** Coming soon. See Reach And Frequency
++ The regulations attribute alongside restricted_delivery_signals is required for Campaigns running Ads promoting Credit, Housing, Employment (CHE), this attribute has to be activated at Ad Account level first or it cannot be used at Campaign level; https://businesshelp.snapchat.com/en-US/a/create-ad-account
+- The regulations attribute alongside the candidate_ballot_information field is optional, but may be required in certain states The paying_advertiser attribute has to be activated at Ad Account level first or the candidate/ballot field cannot be used at Campaign level; https://businesshelp.snapchat.com/en-US/a/create-ad-account
To enable app install and post-install attribution on ads, the ‘measurement_spec’ field must be populated with the corresponding iOS and Android app IDs on campaign creation.
lifetime_spend_cap_micro
can be increased and removed. Reducing the limit is allowed as long as the new limit is 1.1 times the amount already spent. daily_budget_micro
set at the campaign level & the new lifetime_spend_cap_micro
are evaluated independently. Delivery stops when either the Ad Account spend cap or the Campaign Lifetime spend cap is reached.
Create a Campaign
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"campaigns": [{"name": "Cool Campaign", "ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1d0d", "status": "PAUSED", "start_time": "2016-08-11T22:03:58.869Z"}]}' \
"https://adsapi.snapchat.com/v1/adaccounts/{ad_acount_id}/campaigns"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b002ad00ff07e1f50fd2267f0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"campaigns": [
{
"sub_request_status": "success",
"campaign": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"updated_at": "2016-08-14T05:33:33.876Z",
"created_at": "2016-08-14T05:33:33.876Z",
"name": "Cool Campaign",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"status": "PAUSED",
"start_time": "2016-08-11T22:03:58.869Z"
}
}
]
}
This endpoint will create a campaign within a specified ad account.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/campaigns
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Update a Campaign
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"campaigns": [{"name": "Cool Campaign", "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "status": "PAUSED", "start_time": "2016-08-11T22:03:58.869Z", "end_time": "2016-08-21T22:03:58.869-0700", "id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39"}]}'
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/campaigns
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0032700ff07e0cfdaa5e1a40001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010105",
"campaigns": [
{
"sub_request_status": "success",
"campaign": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"updated_at": "2016-08-14T05:35:35.943Z",
"created_at": "2016-08-14T05:33:33.876Z",
"name": "Cool Campaign",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"status": "PAUSED",
"start_time": "2016-08-11T22:03:58.869Z",
"end_time": "2016-08-22T05:03:58.869Z"
}
}
]
}
This endpoint will update a specified campaign.
Attributes that can be updated
Attribute | Description | Required | Possible Values |
---|---|---|---|
end_time | End time | O | |
name | Campaign name | R | |
daily_budget_micro | Daily Spend Cap (micro-currency) | O | |
lifetime_spend_cap_micro | Lifetime spend cap for the campaign (micro-currency) | O | |
start_time | Start time | O | |
status | Campaign status | R | ACTIVE, PAUSED |
HTTP Request
PUT https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/campaigns
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Get All Campaigns
curl "https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/campaigns" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b003c700ff0f2e66c37f96c20001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010103",
"campaigns": [
{
"sub_request_status": "success",
"campaign": {
"id": "06302efa-4c0f-4e36-b880-a395a36cef64",
"updated_at": "2016-08-12T20:28:58.738Z",
"created_at": "2016-08-12T20:28:58.738Z",
"name": "Campaign One",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"daily_budget_micro": 200000000,
"status": "ACTIVE",
"start_time": "2016-08-10T17:12:49.707Z",
"end_time": "2016-08-13T17:12:49.707Z"
}
},
{
"sub_request_status": "success",
"campaign": {
"id": "0fc8e179-6f3b-46e7-be8e-ca53fd404ece",
"updated_at": "2016-08-12T21:06:18.343Z",
"created_at": "2016-08-12T21:06:18.343Z",
"name": "Campaign Deux",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"daily_budget_micro": 500000000,
"status": "ACTIVE",
"start_time": "2016-08-10T17:12:49.707Z",
"end_time": "2016-08-13T17:12:49.707Z"
}
},
[[[ snip ]]]
{
"sub_request_status": "success",
"campaign": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"updated_at": "2016-08-14T05:36:46.441Z",
"created_at": "2016-08-14T05:33:33.876Z",
"name": "Cool Campaign",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"status": "PAUSED",
"start_time": "2016-08-11T22:03:58.869Z",
"end_time": "2016-08-22T05:03:58.869Z"
}
},
{
"sub_request_status": "success",
"campaign": {
"id": "fedf8e04-0176-4ce3-a1ca-148204aee62c",
"updated_at": "2016-08-12T02:18:33.412Z",
"created_at": "2016-08-12T02:18:33.412Z",
"name": "Crazy Campaign",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"start_time": "2016-08-11T22:03:58.869Z",
"status": "PAUSED"
}
}
]
}
This endpoint retrieves all campaigns within a specified ad account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/campaigns
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID | |
read_deleted_entities | true | optional parameter, this param will return the deleted attribute on deleted Campaign entities |
Get a Specific Campaign
curl "https://adsapi.snapchat.com/v1/campaigns/92e1c28a-a331-45b4-8c26-fd3e0eea8c39" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0049c00ff0e8cb21af5199c0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010107",
"campaigns": [
{
"sub_request_status": "success",
"campaign": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"updated_at": "2016-08-14T05:36:46.441Z",
"created_at": "2016-08-14T05:33:33.876Z",
"name": "Cool Campaign",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"status": "PAUSED",
"start_time": "2016-08-11T22:03:58.869Z",
"end_time": "2016-08-22T05:03:58.869Z"
}
}
]
}
This endpoint retrieves a specific campaign.
HTTP Request
GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}
URL Parameters
Parameter | Default | Description |
---|---|---|
campaign_id | Campaign ID | |
read_deleted_entities | true | optional parameter, this param will return the deleted attribute on deleted Campaign entities |
Delete a Specific Campaign
curl -X DELETE "https://adsapi.snapchat.com/v1/campaigns/92e1c28a-a331-45b4-8c26-fd3e0eea8c39" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b004dc00ff0e29c26b5d51840001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010106",
"campaigns": []
}
This endpoint deletes a specific campaign.
HTTP Request
DELETE https://adsapi.snapchat.com/v1/campaigns/<ID>
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the campaign to delete |
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 |
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 | 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, 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
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.
- 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 |
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 |
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 auto 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, 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, LENS_APP_INSTALL, REMOTE_WEBPAGE, 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, REMOTE_WEBPAGE |
VIDEO_VIEWS_15_SEC | SNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, 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) |
LEAD_FORM_SUBMISSIONS | LEAD_GENERATION |
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.
Optimization Goal | Ad Types | Description |
---|---|---|
All Optimization Goals | SWIPE_28DAY_VIEW_1DAY (default) | This is the default delivery optimization for all optimization goals, it can be left out on creation |
PIXEL_PURCHASE | SWIPE_7DAY | This delivery optimization window will unlock for Ad Accounts that has accrued a certain amount of PIXEL_PURCHASE conversions |
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.
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 |
Ads
Ad is a light weight entity that contains all the information needed to display the ad. It also contains a third party measurement URL if needed.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_squad_id | Ad Squad ID | R | |
creative_id | Creative ID | R | |
name | Ad name | R | max length: 375 characters |
paying_advertiser_name | Name of the paying advertiser/political entity | O | This value is inherited from the Ad Account entity and is immutable |
review_status | Ad Review Status | READ ONLY | PENDING, APPROVED, REJECTED |
review_status_reasons | List of Ad Review Rejection Reasons | READ ONLY | if rejected, list of reasons |
status | Ad status | R | ACTIVE, PAUSED |
type | Ad type | R | SNAP_AD, 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, COLLECTION, LEAD_GENERATION |
delivery_status | Delivery status | Read-only | See Delivery status |
deleted | Indicates whether the entity has been deleted or not, only shown when using the parameter read_deleted_entities |
Read-only | true |
Ad Type <-> Creative Type Mapping
Ad Type | Allowed Creative Type |
---|---|
APP_INSTALL | APP_INSTALL |
SNAP_AD | SNAP_AD (aka top snap only) |
REMOTE_WEBPAGE | WEB_VIEW |
DEEP_LINK | DEEP_LINK |
STORY | COMPOSITE |
AD_TO_LENS | AD_TO_LENS |
AD_TO_CALL | AD_TO_CALL |
AD_TO_MESSAGE | AD_TO_MESSAGE |
LENS | LENS |
LENS_REMOTE_WEBPAGE | LENS_WEB_VIEW |
LENS_APP_INSTALL | LENS_APP_INSTALL |
LENS_DEEP_LINK | LENS_DEEP_LINK |
COLLECTION | COLLECTION |
LEAD_GENERATION | LEAD_GENERATION |
Create an Ad
curl -X POST \
-d '{"ads":[{"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe", "creative_id":"c1e6e929-acec-466f-b023-852b8cacc18f", "name": "Ad One", "type": "SNAP_AD", "status": "PAUSED"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b018c500ff0d22d3cefd730d0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010107",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:07:50.241Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "PAUSED",
"type": "SNAP_AD"
}
}
]
}
This endpoint creates an Ad within an Ad Squad.
HTTP Request
POST https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Parameters
Parameter | Default | Description |
---|---|---|
ad_squad_id | Ad Squad ID |
Update an Ad
curl -X PUT \
-d '{"ads":[{"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4", "ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe", "creative_id":"c1e6e929-acec-466f-b023-852b8cacc18f", "name": "Ad One", "type": "SNAP_AD", "status": "ACTIVE"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01a6300ff0c09d23a7706470001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010108",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:14:45.174Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "ACTIVE",
"type": "SNAP_AD"
}
}
]
}
This endpoint updates an Ad.
Attributes that can be updated
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | Ad name | R | |
status | Ad status | R | ACTIVE, PAUSED |
on_swipe_tracking_urls | Third-party swipe-up tags | O | |
third_party_tracking_urls | Third-party impression tags | O |
HTTP Request
PUT https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Parameters
Parameter | Default | Description |
---|---|---|
ad_squad_id | Ad Squad ID |
Get All Ads under an Ad Squad
curl "https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01b3400ff0608a82948df6b0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "2ded6d53-0805-4ff8-b984-54a7eb5c8918",
"updated_at": "2016-08-14T07:18:05.699Z",
"created_at": "2016-08-14T07:18:05.699Z",
"name": "Ad Two",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "PAUSED",
"type": "SNAP_AD"
}
},
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:14:45.174Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "ACTIVE",
"type": "SNAP_AD"
}
}
]
}
This endpoint retrieves all ads within a specified ad squad.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Parameters
Parameter | Default | Description |
---|---|---|
ad_squad_id | Ad Squad ID |
Get All Ads under a Campaign
curl "https://adsapi.snapchat.com/v1/campaigns/77b217e4-7a2c-455b-9fd6-02a55c924177/ads" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f8453bc00ff0d27cde61b08060001737e616473617069736300016275696c642d32626566663136392d312d3339322d3000010102",
"paging": {},
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "0bfdb79e-38cc-470f-8593-789b51b83c97",
"updated_at": "2018-09-12T18:11:00.831Z",
"created_at": "2018-09-12T18:02:25.767Z",
"name": "Fur Coat Shine",
"ad_squad_id": "7fc34710-1c46-417e-bfc6-c4d5696aac4f",
"creative_id": "7ef92e04-e99f-4e22-9496-5cc82b129c77",
"status": "ACTIVE",
"type": "APP_INSTALL",
"render_type": "STATIC",
"review_status": "APPROVED",
"approval_type": "FULL",
"delivery_status": [
"VALID"
]
}
},
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "54d00642-58bb-4db4-8a04-84ffd56258f7",
"updated_at": "2018-08-31T16:34:37.673Z",
"created_at": "2018-08-31T15:36:57.096Z",
"name": "Fur coat conditioner",
"ad_squad_id": "71ca9842-4628-4660-9ba3-3be2e7d15778",
"creative_id": "348e9545-5706-4ff6-8701-2971db6e0017",
"status": "ACTIVE",
"type": "APP_INSTALL",
"render_type": "STATIC",
"review_status": "APPROVED",
"approval_type": "FULL",
"delivery_status": [
"VALID"
]
}
},
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "d1e3c618-b4a0-46ec-8982-b3b357c35507",
"updated_at": "2018-08-31T15:48:52.200Z",
"created_at": "2018-08-31T13:43:41.986Z",
"name": "Claw polish",
"ad_squad_id": "71ca9842-4628-4660-9ba3-3be2e7d15778",
"creative_id": "e261479b-4f2b-443f-8fde-583816fb0167",
"status": "ACTIVE",
"type": "APP_INSTALL",
"render_type": "STATIC",
"review_status": "APPROVED",
"approval_type": "FULL",
"delivery_status": [
"VALID"
]
}
}
]
}
This endpoint retrieves all Ads under a specified Campaign.
HTTP Request
GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/ads
Parameters
Parameter | Default | Description |
---|---|---|
campaign_id | Campaign ID |
Get All Ads under an Ad Account
curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/ads" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01b3400ff0608a82948df6b0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "2ded6d53-0805-4ff8-b984-54a7eb5c8918",
"updated_at": "2016-08-14T07:18:05.699Z",
"created_at": "2016-08-14T07:18:05.699Z",
"name": "Ad Two",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "PAUSED",
"type": "SNAP_AD"
}
},
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:14:45.174Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "ACTIVE",
"type": "SNAP_AD"
}
}
]
}
This endpoint retrieves all Ads under a specified Ad account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/ads
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID | |
read_deleted_entities | true | optional parameter, this param will return the deleted attribute on deleted Ad entities |
Get a Specific Ad
curl "https://adsapi.snapchat.com/v1/ads/e8d6217f-32ab-400f-9e54-39a86a7963e4"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01adc00ff0a5290ad9d42c00001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010103",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:14:45.174Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "ACTIVE",
"type": "SNAP_AD"
}
}
]
}
This endpoint retrieves a specific ad.
HTTP Request
GET https://adsapi.snapchat.com/v1/ads/{ad_id}
URL Parameters
Parameter | Default | Description |
---|---|---|
ad_id | Ad ID | |
read_deleted_entities | true | optional parameter, this param will return the deleted attribute on deleted Ad entities |
Delete an Ad
curl -X DELETE "https://adsapi.snapchat.com/v1/ads/2ded6d53-0805-4ff8-b984-54a7eb5c8918" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01b6200ff05d100ff30ca9b1d0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010101",
"ads": []
}
This endpoint deletes a specific ad.
HTTP Request
DELETE https://adsapi.snapchat.com/v1/ads/{ad_id}
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the ad to delete |
Third-Party Tracking Tags
On the 1st of January 2020 we will be sunsetting the fields on_swipe_tracking_urls
and third_party_tracking_urls
.
From the 1st of January 2020 it won’t be possible to update an Ad entity without removing the third-party tracking from the deprecated fields. This tracking can instead be implemented within the two fields third_party_on_swipe_tracking_urls
and third_party_paid_impression_tracking_urls
.
If you are trafficking third-party tags to the fields on_swipe_tracking_urls
and/or third_party_tracking_urls
you should amend your app as soon as possible and make use of the corresponding fields third_party_on_swipe_tracking_urls
and third_party_paid_impression_tracking_urls
.
Additionally MOAT tracking at Ad level will also be sunset on the 1st of January 2020, for any Ads where you wish to implement MOAT tracking you should instead activate the MOAT tracking at AdSquad level, using the new measurement_provider_names
attribute. Activation at AdSquad level will apply MOAT tracking to all Ad entities within the AdSquad.
Snap currently allows third-party tags from DCM, MDAR and Integral Ad Science (IAS).
MOAT tracking should be implemented at AdSquad level tracking activation via the measurement_provider_names
attribute.
curl -X PUT \
-d '{"ads":[{"id": "ebb64f61-0e12-4f3c-a55c-71a9a6d1ea63", "ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe", "creative_id":"c1e6e929-acec-466f-b023-852b8cacc18f", "name": "Ad One", "type": "SNAP_AD", "status": "ACTIVE", "third_party_paid_impression_tracking_urls": ["https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.222222222;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"],"third_party_on_swipe_tracking_urls": ["https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.333333333;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"]}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "58bb7c5000ff06616e9fa0e86e0001737e616473617069736300016275696c642d33333562626234342d312d35302d330001013d",
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "ebb64f61-0e12-4f3c-a55c-71a9a6d1ea63",
"updated_at": "2017-03-18T00:16:17.690Z",
"created_at": "2017-03-18T00:16:17.690Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"third_party_paid_impression_tracking_urls": [
{
"trackingUrlMetadata": null,
"expandedTrackingUrl": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.222222222;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?",
"tracking_url": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.222222222;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"
}
],
"third_party_on_swipe_tracking_urls": [
{
"trackingUrlMetadata": null,
"expandedTrackingUrl": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.33333333;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?",
"tracking_url": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.33333333;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"
}
],
"status": "PAUSED",
"type": "SNAP_AD",
"review_status": "APPROVED"
}
}
]
}
Additional Ad Attributes
Attribute | Description | Required |
---|---|---|
third_party_on_swipe_tracking_urls | Third-party swipe tags, executed on swipe of attachment | O |
third_party_paid_impression_tracking_urls | Third-party impression tags, executed on ad impression | O |
DEPRECATED, Use attribute third_party_on_swipe_tracking_urls |
- | |
DEPRECATED, Use attribute third_party_paid_impression_tracking_urls |
- |
Approved Third Party Tracking URL domains
URL | Description |
---|---|
secure-gl.imrworldwide.com | |
ad.doubleclick.net | |
pixel.adsafeprotected.com | |
DEPRECATED, Use AdSquad level tracking activation |
How to get tags
DCM and IAS: Refer to your DCM/IAS Account Manager to request tags or generate them using the campaign management tools.
mDAR: Clients should request their Snapchat Account Manager to provide a tag.
Notes
- Ensure all tags are secure and use https
- Choose standard type 1x1 pixel and not Javascript or iframe
- Make sure cachebusting parameter is ~.~TIMESTAMP~.~ and not [timestamp]
URL Macros
There are several dynamic placeholder macros that can be used within the URL that are replaced on-the-fly:
Macro | Description |
---|---|
~.~SERVER_ORG_ID~.~ | Organization ID |
~.~SERVER_AD_ACCOUNT_ID~.~ | Ad Account ID |
~.~SERVER_CAMPAIGN_ID~.~ | Campaign ID |
~.~SERVER_AD_SQUAD_ID~.~ | Ad Squad ID |
~.~SERVER_CREATIVE_ID~.~ | Creative ID |
~.~SERVER_AD_ID~.~ | Ad ID |
~.~SERVER_MOAT_PRODUCT_TYPE~.~ | Ad Product Type |
~.~TIMESTAMP~.~ | Timestamp |
Media
Media is a single video that can be used to construct Creative. Media objects are owned by an Ad Account and can be used by multiple Creatives simultaneously.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
download_link | URL to Media File | READ-ONLY | |
media_status | Media Status | READ-ONLY | PENDING_UPLOAD, READY |
name | Media name | R | |
type | Media Type | R | VIDEO, IMAGE, LENS_PACKAGE |
lens_package_metadata | Metadata for lens media created by Lens Studio | READ-ONLY |
Create Media
curl -X POST \
-d '{"media": [{"name":"Media A - Video", "type":"VIDEO","ad_account_id":"{ad_account_id}"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/media
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b00d1900ff08a0dae50ab27a0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010b",
"media": [
{
"sub_request_status": "success",
"media": {
"id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"updated_at": "2016-08-14T06:18:01.855Z",
"created_at": "2016-08-14T06:18:01.855Z",
"name": "Media A - Video",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "VIDEO",
"media_status": "PENDING_UPLOAD"
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/media
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Upload Media - Video
Name | Description | Dimensions | File size | File type | Length seconds |
---|---|---|---|---|---|
Top Snap | Used as Top Snap video in Snap Ads, Top Snap specs | 1080 x 1920 px | 32MB max size , up to 1 GB allowed using chunked upload | mp4, mov | min 3 seconds, max 180 seconds |
Long form video | Used for Long form video attachment, Long Form video attachment specs | min width 1080 px | 32MB max size , up to 1 GB allowed using chunked upload | mp4, mov | min 15 seconds |
curl -X POST -H 'content-type: multipart/form-data' -F 'file=@"/files/MOV_1808.mov";filename="MOV_1808.mov"' \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/media/a7bee653-1865-41cf-8cee-8ab85a205837/upload
The above command returns JSON structured like this:
{
"result": {
"id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"updated_at": "2016-08-14T06:24:28.378Z",
"created_at": "2016-08-14T06:23:37.086Z",
"name": "Media A - Video",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "VIDEO",
"media_status": "READY",
"file_name": "sample.mov"
},
"request_status": "success",
"request_id": "57b00e9a00ff0ccb4293400c840001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010103"
}
This endpoint receives the actual video data for the media. Snap Inc. hosts all media on behalf of the advertiser.
HTTP Request
POST https://adsapi.snapchat.com/v1/media/{media_id}/upload
Parameters
Parameter | Default | Description |
---|---|---|
media_id | Media ID |
Upload Media - Image
Media of the type IMAGE can be used in various different types of Creatives.
Name | Description | Dimensions | File size | File type |
---|---|---|---|---|
Top Snap Image | Used as Top Snap in Snap Ads, IMAGE type top snaps are converted into 5 sec videos and rendered on the client as videos, Top Snap specs | min 1080 x 1920 px | 5 MB max size | PNG, JPG |
App Icon (Snap Ads) | Icon used for Snap Ad with App Install attachment or Deep Link attachment, image shouldn’t have any borders or padding, App Install attachment specs , Deep Link attachment specs | aspect ratio 1:1 (square), min 200 x 200 px, max 2000 x 2000 px | - | PNG |
App Icon (Lens) | Icon used specifically for the Lens Creatives LENS_APP_INSTALL and LENS_DEEP_LINK, image shouldn’t have any borders or padding | 256 x 256 px | - | PNG |
Preview Image | Used as Thumbnail in Story Ad Creatives, Story Ad specs | aspect ratio 3:5, min 360 x 600 px | 2 MB max size | PNG |
Logo Image | Used as Logo overlaid on Thumbnail in Story Ad Creatives, Story Ad specs | 993 x 284 px | 2 MB max size | PNG |
Audience Filter | Used as Filter, at least 50% of the image must be transparent, Filter specs | 1080 x 2340 px | 300kb or less | PNG |
Supported Optimization goals for ads using IMAGE type media are: IMPRESSIONS, SWIPES, APP_INSTALLS
curl -X POST -H 'content-type: multipart/form-data' -F 'file=@"/files/app_icon.png";filename="app_icon.png"' \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/media/8adc3db7-8148-4fbf-999c-8d2266369d75/upload
The above command returns JSON structured like this:
{
"result": {
"id": "77062ed3-4abf-49a8-ac3f-8157cf14cb41",
"updated_at": "2017-04-14T19:39:05.969Z",
"created_at": "2017-04-14T19:19:59.708Z",
"name": "IMAGE media",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d75",
"type": "IMAGE",
"media_status": "READY",
"file_name": "app_icon.png",
"download_link": "https://storage.googleapis.com/ad-manager-creatives-production/77062ed3-4abf-49a8-ac3f-8157cf14cb41/7d935b22-eb12-41b8-9e34-713b64f2e3b3.png"
},
"request_status": "SUCCESS",
"request_id": "58f1255800ff0d03cc7c0c03380001737e616473617069736300016275696c642d64373565633561632d312d35382d3100010"
}
HTTP Request
POST https://adsapi.snapchat.com/v1/media/{media_id}/upload
Parameters
Parameter | Default | Description |
---|---|---|
media_id | Media ID |
Upload Large Media (Chunked)
This endpoint receives the actual video data for the media. Snapchat hosts all media on behalf of the advertiser.
Files larger than 32MB need to be uploaded in chunks.
- Split the large file
- Initialize a chunked upload request
- Get the “add_path”, “finalize_path” and “upload_id” from the response, these will be unique to your upload
- Upload all parts of the file using the “add_path” , you will need to prepend it with https://adsapi.snapchat.com
- Finalize the chunked upload request using the “finalize_path”, you will need to prepend it with https://adsapi.snapchat.com
Request and Parameters for INIT
POST https://adsapi.snapchat.com/v1/media/{media_id}/multipart-upload-v2?action=INIT
Parameter | Description |
---|---|
action | INIT (query param) |
file_name | File Name |
file_size | Total file size in bytes (cannot exceed 1GB) |
number_of_parts | Number of parts to expect |
Request and Parameters for ADD
POST https://adsapi.snapchat.com + add_path
Parameter | Description |
---|---|
file | File Part |
part_number | File part number, used during re-assembly of file |
upload_id | Chunked Upload ID from INIT |
Request and Parameters for FINALIZE
POST https://adsapi.snapchat.com + finalize_path
Parameter | Description |
---|---|
upload_id | Chunked Upload ID from INIT |
1. Split the large file
Example: split -b 2m lfv.mov split_lfv.
2. Initialize a chunked upload request
curl -X POST -H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: multipart/form-data" \
-F "file_name=lfv.mov" \
-F "file_size=4887527" \
-F "number_of_parts=3" \
"https://adsapi.snapchat.com/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=INIT"
3. Extract upload_id, add_path and finalize_path from response:
{
"request_status":"SUCCESS",
"request_id":"57e56c0b00ff0e1b43229b96350001737e616473617069736300016275696c642d62646338336131372d312d31352d3100010109",
"upload_id":"cffc3975-f2b3-40d2-bf81-f0e7d97b9af5",
"add_path":"/us/v1/media/7bd44f53-5de7-41c4-90c7-50633e5dbb7e/multipart-upload-v2?action=ADD",
"finalize_path":"/v1/media/7bd44f53-5de7-41c4-90c7-50633e5dbb7e/multipart-upload-v2?action=FINALIZE"
}
4. Upload all parts using the add_path prepended with https://adsapi.snapchat.com:
curl -X POST -H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: multipart/form-data" \
-F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
-F "file=@split_lfv.aa" \
-F "part_number=1" \
"https://adsapi.snapchat.com/us/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=ADD"
curl -X POST -H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: multipart/form-data" \
-F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
-F "file=@split_lfv.ab" \
-F "part_number=2" \
"https://adsapi.snapchat.com/us/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=ADD"
curl -X POST -H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: multipart/form-data" \
-F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
-F "file=@split_lfv.ac" \
-F "part_number=3" \
"https://adsapi.snapchat.com/us/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=ADD"
5. Finalize the chunked upload request using finalize_path prepended with https://adsapi.snapchat.com
curl -X POST -H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: multipart/form-data" \
-F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
"https://adsapi.snapchat.com/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=FINALIZE"
The above command returns JSON structured like this:
{
"result": {
"id": "7536bbc5-0074-4dc4-b654-5ba9cd9f9441",
"updated_at": "2016-09-23T17:59:23.826Z",
"created_at": "2016-09-23T17:51:07.799Z",
"name": "Media Chunked - Video",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "VIDEO",
"media_status": "READY",
"file_name": "lfv.mov",
"download_link": "https://storage.googleapis.com/ad-manager-creatives-production-us/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/b195bd7c-aa7b-44c4-83a5-2c12e77a8784.mov"
},
"request_status": "SUCCESS",
"request_id": "57e56d7a00ff0b82bd232ea3d40001737e616473617069736300016275696c642d62646338336131372d312d31352d3100010134"
}
Get All Media
curl "https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/media" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b00ee800ff0a7e553a9389710001737e616473617069736300016275696c642d35396264653638322d312d31312d37000100",
"media": [
{
"sub_request_status": "success",
"media": {
"id": "7f65f9ff-63d8-41e7-991a-06b95a1ffbde",
"updated_at": "2016-08-12T20:39:57.029Z",
"created_at": "2016-08-12T20:39:57.029Z",
"name": "Media 2",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "VIDEO",
"media_status": "PENDING_UPLOAD"
}
},
{
"sub_request_status": "success",
"media": {
"id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"updated_at": "2016-08-14T06:24:28.378Z",
"created_at": "2016-08-14T06:23:37.086Z",
"name": "Media A - Video",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "VIDEO",
"media_status": "READY",
"file_name": "sample.mov"
}
},
{
"sub_request_status": "success",
"media": {
"id": "ab32d7e5-1f80-4e1a-a76b-3c543d2b28e4",
"updated_at": "2016-08-12T17:38:01.918Z",
"created_at": "2016-08-12T17:36:59.740Z",
"name": "App Icon",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "IMAGE",
"media_status": "READY",
"file_name": "Mobile Strike.png"
}
}
]
}
This endpoint retrieves all media entities associated with an ad account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/media
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Get a Specific Media
curl "https://adsapi.snapchat.com/v1/media/a7bee653-1865-41cf-8cee-8ab85a205837" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b00f5f00ff0bd6909e4148c30001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010102",
"media": [
{
"sub_request_status": "success",
"media": {
"id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"updated_at": "2016-08-14T06:24:28.378Z",
"created_at": "2016-08-14T06:23:37.086Z",
"name": "Media A - Video",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "VIDEO",
"media_status": "READY",
"file_name": "sample.mov"
}
}
]
}
This endpoint retrieves a specific media entity.
HTTP Request
GET https://adsapi.snapchat.com/v1/media/{media_id}
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the media to retrieve |
Get Preview for a Specific Media
curl "https://adsapi.snapchat.com/v1/media/8e781365-ce4c-4336-8c53-f6a1f7c50af1/preview" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5aa8450b00ff00ff741e879aff00580001737e816473617069736300016275696x642d37633033663563332d312d3134392d310001015e",
"expires_at": "2018-03-14T21:39:23.303Z",
"link": "https://adsapisc.appspot.com/media/video_preview?media_id=8e781365-ce4c-4336-8c53-f6a1f7c50af1&expires_at=1521063563303&signature=MGQCMA1DRI6uBax3GSq93E8hp5b3P2Ebg0lIlPa8iGML9rs1B9WFmPeHH6ttvx_rmDG5AgIwY0pjIvEEpwOXM8o3h9Hst60DjRN9Mw7am7OmkdrBGfoI4IiHBflv0XpK87Tnb_BE"
}
This endpoint retrieves the preview for a specific media, this request only works on Media which is of the type VIDEO/IMAGE.
HTTP Request
GET https://adsapi.snapchat.com/v1/media/{media_id}/preview
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the media to retrieve, can only be of type VIDEO/IMAGE |
Get Thumbnail for a Specific Media
curl "https://adsapi.snapchat.com/v1/media/095a4a6d-01a0-4f6a-8901-41ea38c7a540/thumbnail" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b99772a00ff06928d3e31e94b0001737e616473617069736300016275696c642d33346634346232622d312d3230302d3200010154",
"expires_at": "2018-09-13T20:29:30.555Z",
"link": "https://adsapisc.appspot.com/media/video_thumbnail?media_id=095a4a6d-01b0-4f6c-8901-41ee38c7b540&expires_at=1536870570555&signature=MGQCMBQ_NfJM0yZCrdyLiEon4Lkbei0zFJF2HpLiHa2NvSLV2JyOVhLqHfQgqbDWUuzaCQIwHzPj_ZFtPNk688SoFiKWUIFEKKBMhSm8t4moy9xlfgnoSv-8LMQ1omM_P8QCj7O9"
}
This endpoint retrieves a thumbnail for media of the type VIDEO Thumbnails cannnot be fetched for other Media types (IMAGE, LENS_PACKAGE).
HTTP Request
GET https://adsapi.snapchat.com/v1/media/{media_id}/thumbnail
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the media (type VIDEO) to retrieve a thumbnail from |
Creatives
A Creative is the combination of one or more pieces of media. Creative is owned by an Ad Account and can be used by multiple Ads simultaneously.
See dedicated sections for examples on how to set up and launch FILTER and LENS creatives.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | max length: 32 characters |
call_to_action | Call to Action | O | Please refer to the Creative type to CTA mapping table |
headline | Headline (displayed under brand name) | R | max length: 34 characters |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | max length: 375 characters |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | SNAP_AD, APP_INSTALL, WEB_VIEW, DEEP_LINK, AD_TO_LENS, AD_TO_CALL, AD_TO_MESSAGE, PREVIEW, COMPOSITE, LENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK, COLLECTION, LEAD_GENERATION |
forced_view_eligibility | Indicates whether Creative can be used as a Commercial | O | FULL_DURATION, SIX_SECONDS, NONE |
preview_creative_id | ID of the preview creative | R (For Story Ads) | |
ad_product | Type of Ad Product | Required only for R&F creatives | SNAP_AD (default), LENS, FILTER |
profile_properties | Contains the profile ID to be associated with the creative | R | { profile_id: 72cf5c50-8343-48d3-a0a7-3ed45b75faaa } |
** LENS type will be available soon with Reach and Frequency buying. Please check Reach and Frequency guide for more details.
Creative Types and attachments
Creative Types
Name | Creative type | Description |
---|---|---|
Snap Ad | SNAP_AD | A Snap Ad comprised of a Top Snap only, latest Video/Image specs |
Snap Ad with attachment | APP_INSTALL, WEB_VIEW, DEEP_LINK, AD_TO_LENS, AD_TO_CALL, AD_TO_MESSAGE | See below for list of all attachments |
Story Ad | COMPOSITE | Story Ad Creatives require a PREVIEW creative |
Collection Ad | COLLECTION | |
Lens | LENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK | See section on Lens creatives for specs and references |
A basic Snap Ad is comprised of a top snap only. Snap Ads can be enhanced by using one of the following attachments:
Creative Type to Call To Actions Mapping
Creative type | Call To Actions |
---|---|
APP_INSTALL | BOOK_NOW, DONATE, DOWNLOAD, GET_NOW, INSTALL_NOW, ORDER_NOW, PLAY, SHOP_NOW, SIGN_UP, TRY, USE_APP, WATCH, VOTE, DIRECTIONS, PLAY_GAME |
LENS_APP_INSTALL | BOOK_NOW, DONATE, DOWNLOAD, GET_NOW, INSTALL_NOW, ORDER_NOW, PLAY, SHOP_NOW, SIGN_UP, TRY, USE_APP, WATCH, PLAY_GAME |
DEEP_LINK | DONATE, PLAY, SHOP_NOW, SIGN_UP, USE_APP, MORE, OPEN_APP, TRY, WATCH, VIEW_PROFILE, VOTE, DIRECTIONS, PRE_REGISTER, PLAY_GAME, DOWNLOAD |
LEAD_GENERATION | APPLY_NOW, MORE, BOOK_NOW, GET_NOW, SIGN_UP, TEST_DRIVE, REQUEST_APPOINTMENT, REQUEST_QUOTE, FREE_TRIAL, CLAIM_SAMPLE, GET_COUPON |
LENS_DEEP_LINK | DONATE, PLAY, SHOP_NOW, SIGN_UP, USE_APP, MORE, OPEN_APP, TRY, WATCH, VIEW_PROFILE, VOTE, DIRECTIONS, VIEW_MENU, PRE_REGISTER, PLAY_GAME |
WEB_VIEW | APPLY_NOW, MORE, ORDER_NOW, PLAY, READ, SHOP_NOW, SHOW, SIGN_UP, VIEW, SHOW, WATCH, DONATE, DOWNLOAD, APPLY_NOW, ORDER_NOW, RESPOND, BUY_TICKETS, SHOWTIMES, BOOK_NOW, GET_NOW, LISTEN, TRY, VOTE, VIEW_MENU, PRE_REGISTER, PLAY_GAME |
LENS_WEB_VIEW | APPLY_NOW, MORE, ORDER_NOW, PLAY, READ, SHOP_NOW, SHOW, SIGN_UP, VIEW, SHOW, WATCH, DONATE, DOWNLOAD, APPLY_NOW, ORDER_NOW, RESPOND, BUY_TICKETS, SHOWTIMES, BOOK_NOW, GET_NOW, LISTEN, TRY, VOTE, DIRECTIONS, VIEW_MENU, PRE_REGISTER, PLAY_GAME |
AD_TO_LENS | PLAY, TRY, SHOP_NOW, VOTE |
AD_TO_MESSAGE | MESSAGE_NOW, OPEN_APP |
AD_TO_CALL | CALL_NOW, OPEN_APP |
AD_TO_PLACE | SEE_PLACE, DIRECTIONS, VIEW_MENU |
Attachments
Name | Creative type | Description |
---|---|---|
Lead Generation attachment | LEAD_GENERATION | Creative requires lead_generation_properties |
Web View attachment | WEB_VIEW | Creative requires web_view_properties |
App Install attachment | APP_INSTALL | Creative requires app_install_properties |
Deep Link attachment | DEEP_LINK | Creative requires deep_link_properties |
Lens attachment | AD_TO_LENS | Creative requires ad_to_lens_properties |
Call attachment | AD_TO_CALL | Creative requires ad_to_call_properties |
Text attachment | AD_TO_MESSAGE | Creative requires ad_to_message_properties |
Create a Snap Ad
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 32 characters max |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | SNAP_AD |
forced_view_eligibility | Indicates whether Creative can be used as a Commercial, see Commercials section for instructions on how to determine and set this value | O | FULL_DURATION, SIX_SECONDS, NONE |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837", "name": "Creative Creative", "type": "SNAP_AD", "brand_name": "Maxiumum Brand", "headline": "Healthy Living", "shareable": true}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0136f00ff085e3d63d358a20001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010108",
"creatives": [
{
"sub_request_status": "success",
"creative": {
"id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"updated_at": "2016-08-14T06:45:04.300Z",
"created_at": "2016-08-14T06:45:04.300Z",
"name": "Creative Creative",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "SNAP_AD",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE"
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap Ad with App Install attachment
App Install attachments allow users to swipe up and download the advertised app.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 32 characters max |
call_to_action | Call to Action | O | Please refer to the Creative type to CTA mapping table |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | APP_INSTALL |
forced_view_eligibility | Indicates whether Creative can be used as a Commercial, see Commercials section for instructions on how to determine and set this value | O | FULL_DURATION, SIX_SECONDS, NONE |
Additional Attributes
The following attributes should be added to the basic creative under the property app_install_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
app_name | App name | R | 30 characters max |
ios_app_id | iOS App ID | R | |
android_app_url | Google Play Store ID | R | (eg “com.x.y”) |
icon_media_id | Icon Media ID | R | |
product_page_id | Custom product page ID from iOS App Store. Only set when using a Custom Product Page | O | 45812c9b-c296-43d3-c6a0-c5a02f74bf6e |
Icon Media specifications
- Minimum 200 x 200 px, Maximum 2000 x 2000 px
- Must be PNG format
- The image should be square
- The image should not have any borders or padding
Mobile Measurement Partners - Setup Details
curl -X POST \
-d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837", "name": "Creative App Install", "type": "APP_INSTALL", "shareable": true, "call_to_action": "INSTALL_NOW", "app_install_properties": {"app_name": "Cool App Yo", "ios_app_id": "447188370", "android_app_url": "com.snapchat.android", "icon_media_id": "ab32d7e5-1f80-4e1a-a76b-3c543d2b28e4"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0163000ff05bee93989450c0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010107",
"creatives": [
{
"sub_request_status": "success",
"creative": {
"id": "1c7065c2-ad9f-41cc-b2c5-d48d9810439b",
"updated_at": "2016-08-14T06:56:48.631Z",
"created_at": "2016-08-14T06:56:48.631Z",
"name": "Creative App Install",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "APP_INSTALL",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "INSTALL_NOW",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"app_install_properties": {
"app_name": "Cool App Yo",
"ios_app_id": "447188370",
"android_app_url": "com.snapchat.android",
"icon_media_id": "ab32d7e5-1f80-4e1a-a76b-3c543d2b28e4"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap Ad with Web View attachment
Web View attachments allow users to swipe up to view a web page, you have the option of preloading the website as directed by the block_preload attribute
. You can see more details on preloading and recommendations for optimizations here.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 32 characters max |
call_to_action | Call to Action | O | Please refer to the Creative type to CTA mapping table |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | WEB_VIEW |
forced_view_eligibility | Indicates whether Creative can be used as a Commercial, see Commercials section for instructions on how to determine and set this value | O | FULL_DURATION, SIX_SECONDS, NONE |
Additional Attributes
The following attributes should be added to the basic creative under the property web_view_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
url | Web view URL | R | The following macros are supported:
|
block_preload | Block Snapchat from preloading the web page | O | true/false (default) |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837", "name": "Creative WV", "type": "WEB_VIEW", "shareable": true, "call_to_action": "VIEW", "web_view_properties": {"url": "http://snapchat.com/ads"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0168400ff06efecfdcdc8da0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010c",
"creatives": [
{
"sub_request_status": "success",
"creative": {
"id": "67e4296c-486b-4bf3-877b-f34e8eeb173c",
"updated_at": "2016-08-14T06:58:12.768Z",
"created_at": "2016-08-14T06:58:12.768Z",
"name": "Creative WV",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "WEB_VIEW",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "VIEW",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"web_view_properties": {
"url": "http://snapchat.com/ads"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap Ad with Deep Link attachment
The Deep Link attachment allows users who have the app installed to be directed to the location defined in the deep_link_properties
, users who do not have the app installed will be directed to the App store to install the app.
If you have a web view with deep links there is no need to specify the deep links in a separate field on the Creative. The deep links inside the web view will be auto detected.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 32 characters max |
call_to_action | Call to Action | O | Please refer to the Creative type to CTA mapping table |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | DEEP_LINK |
Additional Attributes
The following attributes should be added to the basic creative under the property deep_link_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
deep_link_uri | Deep Link URL | R | |
app_name | App name | R | 30 characters max |
ios_app_id | iOS App ID | Optional but one of ios_app_id or android_app_url is required | |
android_app_url | Google Play Store ID | Optional but one of ios_app_id or android_app_url is required | |
icon_media_id | Icon Media ID | R | |
fallback_type | Type of fallback to be used when user doesn’t have the app | O | APP_INSTALL (default), WEB_SITE |
web_view_fallback_url | Fallback web url to be used | O | |
product_page_id | Custom product page ID from iOS App Store. Only set when using a Custom Product Page | O |
Icon Media specifications
- Minimum 200 x 200 px, Maximum 2000 x 2000 px
- Must be PNG format
- The image should be square
- The image should not have any borders or padding
curl -X POST \
-d '{"creatives": [{"name": "Deep Link test","ad_account_id": "{{ad_account_id}}","type": "DEEP_LINK","shareable": true,"headline": "some headline","brand_name": "some brand name","top_snap_media_id": "{{media_id}}","top_snap_crop_position": "MIDDLE","call_to_action": "{{cta}}","deep_link_properties": {"deep_link_uri":"spotify://somelink","ios_app_id": "1234","android_app_url": "com.snapchat.android","app_name": "not hotdog app","icon_media_id": "{{app_icon_media_id}}"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0168400ff06efecfdcdc8da0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010c",
"creatives": [
{
"sub_request_status": "success",
"creative": {
"id": "67e4296c-486b-4bf3-877b-f34e8eeb173c",
"updated_at": "2016-08-14T06:58:12.768Z",
"created_at": "2016-08-14T06:58:12.768Z",
"name": "Deep Link test",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "DEEP_LINK",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "VIEW",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"deep_link_properties": {
"deep_link_uri":"spotify://somelink",
"ios_app_id": "1234",
"android_app_url": "com.snapchat.android",
"app_name": "not hotdog app",
"icon_media_id": "{{app_icon_media_id}}"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap Ad with Lens attachment
The lens attachment will open up an AR Lens upon swipe up
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 32 characters max |
call_to_action | Call to Action | O | Please refer to the Creative type to CTA mapping table |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | AD_TO_LENS |
forced_view_eligibility | Indicates whether Creative can be used as a Commercial, see Commercials section for instructions on how to determine and set this value | O | FULL_DURATION, SIX_SECONDS, NONE |
Additional Attributes
The following attributes should be added to the basic creative under the property ad_to_lens_properties.
Attribute | Description | Required |
---|---|---|
lens_media_id | The Media ID of the lens to be opened upon swipe up | R |
Lens Media file for a Lens Creative is not uploaded via the API, it’s instead created in Snapchat Lens Studio or Lens Web Builder and then transferred to the Ad Account in question via Lens Studio.
curl -X POST \
-d '{"creatives": [{"name":"Swipe to Lens","ad_account_id":"0b5176e0-9d5e-467c-8275-c1b619bd87d1","type":"AD_TO_LENS","shareable":true,"headline":"Headline Headline","brand_name":"Best Brand","call_to_action":"TRY","top_snap_media_id":"77f0c0a5-3374-4196-ac71-eb9fce49a5f3","top_snap_crop_position":"MIDDLE","ad_product":"SNAP_AD","ad_to_lens_properties":{"lens_media_id":"708ba95f-74e4-4e95-b443-21ccd2091a96"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b52250700ff0c3438c927b7db0001737e616473617069736300016275696c642d31393039356634322d312d3138352d310001011b",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "0df4bc92-00c8-4a6d-af89-533def1e5750",
"updated_at": "2018-07-20T14:32:09.102Z",
"created_at": "2018-07-20T14:29:44.160Z",
"name": "Swipe to lens",
"ad_account_id": "0b5176e0-9d5e-467c-8275-c1b619bd87d1",
"type": "AD_TO_LENS",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Headline Healine",
"brand_name": "Best Brand",
"call_to_action": "TRY",
"top_snap_media_id": "77f0c0a5-3374-4196-ac71-eb9fce49a5f3",
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"ad_to_lens_properties": {
"lens_media_id": "708ba95f-74e4-4e95-b443-21ccd2091a96"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Swipe to Call/Text - Phone number verification
All Phone Numbers used in Swipe to Call/Text Creatives need to be Verified via Snap Ads Manager as we use 2 factor authentication. You can do this by using Snap Ads Manager to set up a first Swipe to Call/Text Creative in your account, this set up will include adding a phone number and verifying it, see this guide for more details on how to verify your phone number.
After successful verification of the phone number you will be able to retrieve a phone number ID for the number in question.
This type of Ad is currently only available in the United States, France, Qatar, Saudi Arabia, Egypt, Kuwait and the United Arab Emirates.
curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/phone_numbers" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e6fb44400ff098283dd16a12e0001737e616473617069736300016275696c642d31636430373832652d312d3333342d300001010a",
"paging": {},
"phone_numbers": [
{
"sub_request_status": "SUCCESS",
"phone_number": {
"id": "d85758e1-4aac-435d-9660-de29e9b97548",
"updated_at": "2020-02-06T22:10:46.573Z",
"created_at": "2020-02-06T22:10:37.609Z",
"name": "Phone number - Pizza",
"country_code": "us",
"numerical_country_code": "1",
"phone_number": "1111333444",
"verification_status": "VERIFIED"
}
},
{
"sub_request_status": "SUCCESS",
"phone_number": {
"id": "dab10be9-6147-4ef4-9ad5-328f39777625",
"updated_at": "2020-02-06T22:07:40.452Z",
"created_at": "2020-02-06T22:07:26.553Z",
"name": "Phone number - Chicken",
"country_code": "us",
"numerical_country_code": "1",
"phone_number": "1111222333",
"verification_status": "VERIFIED"
}
}
]
}
This endpoint retrieves all verified phone numbers for an Ad Account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/phone_numbers
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap ad with Swipe to Call attachment
Call attachments allow users to swipe up to initiate a call.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 32 characters max |
call_to_action | Call to Action | O | Please refer to the Creative type to CTA mapping table |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | AD_TO_CALL |
Additional Attributes
The following attributes should be added to the basic creative under the property ad_to_call_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
phone_number_id | ID of the phone number to be used | R |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "497979f0-ed17-4971-8288-054883f1cbca","name" : "A new AD_TO_CALL Creative","type": "AD_TO_CALL","top_snap_media_id": "2fbaa906-d2d2-423d-b8e3-9535f1281998","ad_product": "SNAP_AD","headline": "Order your meal now","brand_name": "Honey Foods","call_to_action": "OPEN_APP","ad_to_call_properties": {"phone_number_id": "715b6ee0-357c-41d2-9246-feb09c199fc9"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e6fb51900ff040ef4db1db40b0001737e616473617069736300016275696c642d31636430373832652d312d3333342d300001010a",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "dbf052de-139c-4860-9f29-9dc4fa580620",
"updated_at": "2020-03-16T17:19:24.063Z",
"created_at": "2020-03-16T17:19:24.063Z",
"name": "A new AD_TO_CALL Creative",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2",
"type": "AD_TO_CALL",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Order your meal now",
"brand_name": "Honey Foods",
"call_to_action": "OPEN_APP",
"render_type": "STATIC",
"top_snap_media_id": "2fbaa906-d2d2-423d-b8e3-9535f1281998",
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"ad_to_call_properties": {
"phone_number_id": "715b6ee0-357c-41d2-9246-feb09c199fc9",
"message": null
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap Ad with Swipe to Text attachment
Text attachments allow users to swipe up to initiate a text message.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 32 characters max |
call_to_action | Call to Action | O | Please refer to the Creative type to CTA mapping table |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | AD_TO_MESSAGE |
Additional Attributes
The following attributes should be added to the basic creative under the property ad_to_message_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
phone_number_id | ID of the phone number to be used | R | |
message | A pre-populated message for the user to send, max 160 characters | O |
curl -X PUT \
-d '{"creatives":[{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2","name" : "A new AD_TO_MESSAGE Creative","type": "AD_TO_MESSAGE","top_snap_media_id": "2fbaa906-d2d2-423d-b8e3-9535f1281998","ad_product": "SNAP_AD","headline": "Honey Dating","brand_name": "Dating for honey bears","call_to_action": "OPEN_APP","ad_to_message_properties": {"phone_number_id": "715b6ee0-357c-41d2-9246-feb09c199fc9","message": "Please send me details of Single Polar Bears"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e6fb51900ff040ef4db1db40b0001737e616473617069736300016275696c642d31636430373832652d312d3333342d300001010a",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "48c1a68d-782c-48af-8dba-ceef18d22a3c",
"updated_at": "2020-03-16T17:19:24.250Z",
"created_at": "2020-03-16T17:19:24.250Z",
"name": "A new AD_TO_MESSAGE Creative",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2",
"type": "AD_TO_MESSAGE",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Honey Dating",
"brand_name": "Dating for honey bears",
"call_to_action": "OPEN_APP",
"render_type": "STATIC",
"top_snap_media_id": "2fbaa906-d2d2-423d-b8e3-9535f1281998",
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"ad_to_message_properties": {
"phone_number_id": "715b6ee0-357c-41d2-9246-feb09c199fc9",
"message": "Send me details of Single Polar Bears"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Story Ad Creative
The Story Ad Creative comes in two different variants, the full variant includes a Preview Creative and a Composite Creative, this type of Story Ad can run in the Stories Tab and also in between User stories and Curated stories.
The second variant of the Story Ad Creative uses only a Composite Creative, this type of Story Ad Creative can only run between User stories and Curated stories.
The Preview Creative is used to display the thumbnail within the Stories tab of the app, the Composite Creative is used to define the individual Snap Ads that make up the story. When the Story Ad runs in between User stories and Curated stories the Preview Creative is not used.
Create the Preview Creative
Additional Attributes
The following attributes should be added to the basic creative under the property preview_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
preview_media_id | Image that is the preview for Story Ads | R | |
logo_media_id | Logo shown on the tile for Story Ads | R | |
preview_headline | Preview Headline shown on the tile for Story Ads | R | 55 Character limit, emoji unicode characters allowed |
Preview Image Specifications - Resolution 3:5 - Minimum dimensions: 360 x 600 px - Maximum file size: 2MB - File Type: png
Logo Specifications - Dimensions: 993 x 284 px - Maximum file size: 2MB - File Type: png
curl -X POST \
-d '{"creatives": [{"ad_account_id": "0cf0aace-39d4-4502-8656-8f42daa473c7", "name": "Story Ad Preview", "type": "PREVIEW", "preview_properties": {"preview_media_id": "00a76e9f-186c-4ed4-87d7-d58a7dd06749", "logo_media_id": "6d54643b-e6e1-4c50-ab9a-a1f05965bf33", "preview_headline": "test preview headline"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/0cf0aace-39d4-4502-8656-8f42daa473c7/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ae7ac0a00ff09a390a9b9b4d60001737e616473617069736300016275696c642d36393364326336352d312d3136322d3400010101",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "62537bbc-1a3a-4a40-b46f-43d181eac8ee",
"updated_at": "2018-04-30T23:51:40.466Z",
"created_at": "2018-04-30T23:51:40.466Z",
"name": "Story Ad Preview",
"ad_account_id": "0cf0aace-39d4-4502-8656-8f42daa473c7",
"type": "PREVIEW",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"top_snap_crop_position": "MIDDLE",
"preview_properties": {
"preview_media_id": "00a76e9f-186c-4ed4-87d7-d58a7dd06749",
"logo_media_id": "6d54643b-e6e1-4c50-ab9a-a1f05965bf33",
"preview_headline": "test preview headline"
}
}
}
]
}
Create the Composite Creative
Additional Attributes
The following attributes should be added to the basic creative under the property composite_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
creative_ids | List of creative ids that make up composite creative | R (For Story Ads) | Creative types SNAP_AD, APP_INSTALL, WEB_VIEW and DEEP_LINK are supported |
Composite creation guidelines
- Story Ad Creatives use 1-20 individual Creatives within a Composite creative
- The Creative types listed in creative_ids
attribute can be mixed as long as they are of the supported type listed above
- Creatives are shown to the user in the order listed at creation
- The order of the Creatives is immutable once created
- The shareable attribute on the composite overrides the shareable value of the individual creatives
curl -X POST \
-d '{"creatives": [{"ad_account_id": "0cf0aace-39d4-4502-8656-8f42daa473c7", "name": "First Composite Creative", "type": "COMPOSITE", "headline": "Test headline", "brand_name": "Test brand name",*", "shareable": true, "preview_creative_id": "62537bbc-1a3a-4a40-b46f-43d181eac8ee", "composite_properties": {"creative_ids": ["2cc52fce-855e-40aa-bb4b-016c2befd8ab", "f9a4b56c-ece0-4da4-bc9d-08c29ef941a2", "9c4b3882-addc-48d9-8503-22f7d03d6309"]}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ae7b4cb00ff05f9646ae5a400ff0001737e616473617069736300016275696c642d36393364326336352d312d3136322d3400010155",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "d3f4b7a5-e8dc-4e85-8d05-52094e3e3708",
"updated_at": "2018-05-01T00:28:59.816Z",
"created_at": "2018-05-01T00:28:59.816Z",
"name": "First Composite Creative",
"ad_account_id": "0cf0aace-39d4-4502-8656-8f42daa473c7",
"type": "COMPOSITE",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Test headline",
"brand_name": "Test brand name",
"top_snap_crop_position": "MIDDLE",
"composite_properties": {
"creative_ids": [
"2cc52fce-855e-40aa-bb4b-016c2befd8ab",
"f9a4b56c-ece0-4da4-bc9d-08c29ef941a2",
"9c4b3882-addc-48d9-8503-22f7d03d6309"
]
},
"preview_creative_id": "62537bbc-1a3a-4a40-b46f-43d181eac8ee"
}
}
]
}
Create a Lens Creative
Lens Creatives can run both in regular auction and in Reach and Frequency, for creation of Lens creatives see the Lens Section.
curl -X POST \
-d '{"creatives": [{"name":"Lens Creative","ad_account_id":"0b5176e0-9d5e-467c-8275-c1b619bd87d1","type":"LENS","shareable":true,"headline":"Headline Headline","brand_name":"Best Brand", "top_snap_media_id":"77f0c0a5-3374-4196-ac71-eb9fce49a5f3","ad_product":"LENS"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b52250700ff0c3438c927b7db0001737e616473617069736300016275696c642d31393039356634322d312d3138352d310001011b",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "0df4bc92-00c8-4a6d-af89-533def1e5750",
"updated_at": "2018-07-20T14:32:09.102Z",
"created_at": "2018-07-20T14:29:44.160Z",
"name": "Lens Creative",
"ad_account_id": "0b5176e0-9d5e-467c-8275-c1b619bd87d1",
"type": "LENS",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Headline Healine",
"brand_name": "Best Brand",
"top_snap_media_id": "77f0c0a5-3374-4196-ac71-eb9fce49a5f3",
"top_snap_crop_position": "MIDDLE",
"ad_product": "LENS"
}
}
]
}
Create a Lens Creative with Attachment
You can create a Lens Creative with any of the following attachments and the corresponding field then becomes required. The attachment unit will behave in the same way as it would in a Snap Ad. For measurement, you can also use the Snap Pixel with the attachment if it is a webview, make sure to associate the pixel_id at the Adsquad level. For attributes and examples, see the Lens Section.
Attachment For Lens | Creative Type | Required Field |
---|---|---|
WEB_VIEW | LENS_WEB_VIEW | web_view_properties |
APP_INSTALL | LENS_APP_INSTALL | app_install_properties |
DEEP_LINK | LENS_DEEP_LINK | deep_link_properties |
Lens Creatives are also available for Reach and Frequency Campaigns.
curl -X POST \
-d '{"creatives": [{"name":"Lens Creative","ad_account_id":"0b5176e0-9d5e-467c-8275-c1b619bd87d1","type":"LENS_WEB_VIEW","shareable":true,"headline":"Headline Headline","brand_name":"Best Brand", "top_snap_media_id":"77f0c0a5-3374-4196-ac71-eb9fce49a5f3","ad_product":"LENS", "web_view_properties": {"url": "http://snapchat.com/ads"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b52250700ff0c3438c927b7db0001737e616473617069736300016275696c642d31393039356634322d312d3138352d310001011b",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "0df4bc92-00c8-4a6d-af89-533def1e5750",
"updated_at": "2018-07-20T14:32:09.102Z",
"created_at": "2018-07-20T14:29:44.160Z",
"name": "Lens Creative",
"ad_account_id": "0b5176e0-9d5e-467c-8275-c1b619bd87d1",
"type": "LENS_WEB_VIEW",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Headline Healine",
"brand_name": "Best Brand",
"top_snap_media_id": "77f0c0a5-3374-4196-ac71-eb9fce49a5f3",
"top_snap_crop_position": "MIDDLE",
"ad_product": "LENS",
"web_view_properties": {
"url": "http://snapchat.com/ads"
}
}
}
]
}
Create a Collection Ad Creative
Additional Attributes
The following attributes should be added to the basic creative under the property collection_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
interaction_zone_id | ID of the interaction zone to be used | R | |
default_fallback_interaction_type | The interation type when user swipes up on the full unit | R | WEB_VIEW, DEEP_LINK (must match the interaction type of the creative elements in the collection) |
web_view_properties | Web View properties | Required if default_fallback_interaction_type=WEB_VIEW | Same as web_view_properties for Web View Creative |
deep_link_properties | Deep Link properties | Required if default_fallback_interaction_type=DEEP_LINK | Same as deep_link_properties for Creative with deep links |
For Collection Ad creatives, call_to_action
must be set to null, and the headline
property of the interaction zone is used instead.
curl -X POST \
-d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74","name" : "Collection Ad creative","type": "COLLECTION","top_snap_media_id": "a871dcfd-3970-4917-a44a-b251220ce731","headline": "Collection Ad headline","brand_name": "My brand","collection_properties":{"interaction_zone_id":"a218dc8b-7a79-4da6-9a1c-e5a581c7bd44","default_fallback_interaction_type":"WEB_VIEW","web_view_properties":{"url":"https://snapchat.com"}}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5bef549b00ff07105bd7e8604d0001737e616473617069736300016275696c642d61353965373533332d312d3232302d3100010144",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "e6ef3dea-0a5a-438e-928d-56726343d121",
"updated_at": "2018-11-16T23:37:01.555Z",
"created_at": "2018-11-16T23:37:01.555Z",
"name": "Collection Ad creative",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "COLLECTION",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Collection Ad headline",
"brand_name": "My brand",
"top_snap_media_id": "a871dcfd-3970-4917-a44a-b251220ce731",
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"collection_properties": {
"interaction_zone_id": "a218dc8b-7a79-4da6-9a1c-e5a581c7bd44",
"default_fallback_interaction_type": "WEB_VIEW",
"web_view_properties": {
"url": "https://snapchat.com",
"deep_link_urls": [],
"block_preload": false
}
}
}
}
]
}
Update a Creative
curl -X PUT \
-d '{
"creatives": [
{
"ad_account_id": "12325ba6-7559-4000-9663-bace8adff5f2",
"brand_name": "Example Inc",
"id": "7772efab-028d-40ec-aa9d-7eb8f065c10a",
"headline": "For all Citrus Fans",
"web_view_properties":
{
"url": "https://www.example.com/intro?utm_source=snapchat&utm_medium=paidsocial&utm_campaign=2019_citrus",
"block_preload": true
},
"type": "WEB_VIEW",
"ad_product": "SNAP_AD",
"top_snap_media_id": "647e6398-7e44-4ae5-a19d-c400b93bce32",
"top_snap_crop_position": "MIDDLE",
"name": "Citrus Creative",
"call_to_action": "LISTEN",
"shareable": true,
"profile_properties":
{
"profile_id": "62cf5c50-8343-48d3-a0a7-3ed45b75fa10"
}
}]
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/12325ba6-7559-4000-9663-bace8adff5f2/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5c3008ed00ff04a89c4d5c66150001737e616473617069736300016275696c642d31326365666331382d312d3232362d3000000003",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "7772efab-028d-40ec-aa9d-7eb8f065c10a",
"updated_at": "2019-01-11T21:21:50.991Z",
"created_at": "2018-12-05T16:04:09.772Z",
"name": "Citrus Creative",
"ad_account_id": "12325ba6-7559-4000-9663-bace8adff5f2",
"type": "WEB_VIEW",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "For all Citrus Fans",
"brand_name": "Example Inc",
"call_to_action": "LISTEN",
"top_snap_media_id": "647e6398-7e44-4ae5-a19d-c400b93bce32",
"top_snap_crop_position": "MIDDLE",
"web_view_properties": {
"url": "https://www.example.com/intro?utm_source=snapchat&utm_medium=paidsocial&utm_campaign=2019_citrus",
"deep_link_urls": [],
"block_preload": true
},
"ad_product": "SNAP_AD",
"profile_properties":
{
"profile_id": "62cf5c50-8343-48d3-a0a7-3ed45b75fa10"
}
}
}
]
}
This endpoint will update the specified Creative. Making changes to a creative will impact all ads associated with the creative. These changes will trigger re-review of associated ads and the ads will be paused. Once the ads are re-approved, they will start delivering again.
Attributes that can be updated
Italicized attributes cannot be updated once a Creative is part of an Ad that has started serving.
Attribute | Required |
---|---|
brand_name | R |
call_to_action | R |
headline | R |
shareable | R |
name | R |
top_snap_media_id | R |
preview_creative_id | O |
forced_view_eligibility | O |
web_view_properties | Required |
---|---|
url | R |
block_preload | R |
app_install_properties | Required |
---|---|
app_name | R |
ios_app_id | R |
android_app_url | R |
icon_media_id | R |
product_page_id | O |
deep_link_properties | Required |
---|---|
deep_link_uri | R |
app_name | R |
ios_app_id | R |
android_app_url | R |
icon_media_id | R |
web_view_fallback_url | R |
fallback_type | R |
product_page_id | O |
preview_properties | Required |
---|---|
preview_media_id | R |
logo_media_id | R |
preview_headline | R |
composite_properties | Required |
---|---|
creative_ids | R |
ad_to_lens_properties | Required |
---|---|
lens_media_id | R |
Get All Creatives
curl "https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0171900ff0c73f50d5bd2f10001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010106",
"creatives": [
{
"sub_request_status": "success",
"creative": {
"id": "184fe3d0-ff80-4388-8d5f-05c340eff231",
"updated_at": "2016-08-14T06:54:38.229Z",
"created_at": "2016-08-14T06:54:38.229Z",
"name": "Creative LFV",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "LONGFORM_VIDEO",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "WATCH",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"longform_video_properties": {
"video_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837"
}
}
},
{
"sub_request_status": "success",
"creative": {
"id": "1c7065c2-ad9f-41cc-b2c5-d48d9810439b",
"updated_at": "2016-08-14T06:56:48.631Z",
"created_at": "2016-08-14T06:56:48.631Z",
"name": "Creative App Install",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "APP_INSTALL",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "INSTALL_NOW",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"app_install_properties": {
"app_name": "Cool App Yo",
"ios_app_id": "447188370",
"android_app_url": "com.snapchat.android",
"icon_media_id": "ab32d7e5-1f80-4e1a-a76b-3c543d2b28e4"
}
}
},
{
"sub_request_status": "success",
"creative": {
"id": "313e8415-6294-47d6-b064-5a0d9f21d224",
"updated_at": "2016-08-14T06:54:52.107Z",
"created_at": "2016-08-14T06:54:52.107Z",
"name": "Creative LFV 2",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "LONGFORM_VIDEO",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "WATCH",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"longform_video_properties": {
"video_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837"
}
}
},
{
"sub_request_status": "success",
"creative": {
"id": "67e4296c-486b-4bf3-877b-f34e8eeb173c",
"updated_at": "2016-08-14T06:58:12.768Z",
"created_at": "2016-08-14T06:58:12.768Z",
"name": "Creative WV",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "WEB_VIEW",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "VIEW_MORE",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"web_view_properties": {
"url": "http://snapchat.com/ads"
}
}
},
{
"sub_request_status": "success",
"creative": {
"id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"updated_at": "2016-08-14T06:45:04.300Z",
"created_at": "2016-08-14T06:45:04.300Z",
"name": "Creative Creative",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "SNAP_AD",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE"
}
}
]
}
This endpoint retrieves all creatives associated with an ad account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Get a Specific Creative
curl "https://adsapi.snapchat.com/v1/creatives/c1e6e929-acec-466f-b023-852b8cacc18f" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b017a400ff057ca1dcf703da0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010101",
"creatives": [
{
"sub_request_status": "success",
"creative": {
"id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"updated_at": "2016-08-14T06:45:04.300Z",
"created_at": "2016-08-14T06:45:04.300Z",
"name": "Creative Creative",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "SNAP_AD",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE"
}
}
]
}
This endpoint retrieves a specific Creative.
HTTP Request
GET https://adsapi.snapchat.com/v1/creatives/{creative_id}
URL Parameters
Parameter | Description |
---|---|
creative_id | The ID of the creative to retrieve |
Get Snapcode preview for a Creative
curl "https://adsapi.snapchat.com/v1/creatives/c1e6e929-acec-466f-b023-852b8cacc54f/snapcode" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5aa15e8000ff03acde535d9a200001737e616473617069736300016275696c642d62633562363761342d312d3134372d3600013326",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc54f",
"expires_at": "2018-03-09T15:51:33.248Z",
"snapcode_link": "https://adsapisc.appspot.com/snapcodeimage/c1e6e929-acec-466f-b023-852b8cacc54f/352a899e-4a9d-3fdf-8efe-9bac9b8a0a21"
}
This endpoint generates a snapcode preview for a specific creative, the lifetime of the snapcode is 7 days. The attribute expires_at
defines the time that the snapcode will stop functioning.
HTTP Request
GET https://adsapi.snapchat.com/v1/creatives/{creative_id}/snapcode
URL Parameters
Parameter | Description |
---|---|
creative_id | The ID of the creative to retrieve |
Associate Public Profiles with Creatives
To associate Public Profiles you can include the profile_properties
property to the creative during create or update. Then use the Sharing Policies API on the Business API to list all shared Public Profiles for an ad account or external organization.
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
'https://adsapi.snapchat.com/v1/adaccounts/12325ba6-7559-4000-9663-bace8adff5f2/creatives' \
-D '{
"creatives": [{
"ad_account_id": "12325ba6-7559-4000-9663-bace8adff5f2",
"brand_name": "Example Inc",
"id": "7772efab-028d-40ec-aa9d-7eb8f065c10a",
"headline": "For all Citrus Fans",
"web_view_properties":
{
"url": "https://www.example.com/intro?utm_source=snapchat&utm_medium=paidsocial&utm_campaign=2019_citrus",
"block_preload": true
},
"type": "WEB_VIEW",
"ad_product": "SNAP_AD",
"top_snap_media_id": "647e6398-7e44-4ae5-a19d-c400b93bce32",
"top_snap_crop_position": "MIDDLE",
"name": "Citrus Creative",
"call_to_action": "LISTEN",
"shareable": true,
"profile_properties":
{
"profile_id": "62cf5c50-8343-48d3-a0a7-3ed45b75fa10"
}
}]
}'
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5c3008ed00ff04a89c4d5c66150001737e616473617069736300016275696c642d31326365666331382d312d3232362d3000000003",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative":
{
"id": "7772efab-028d-40ec-aa9d-7eb8f065c10a",
"updated_at": "2019-01-11T21:21:50.991Z",
"created_at": "2018-12-05T16:04:09.772Z",
"name": "Citrus Creative",
"ad_account_id": "12325ba6-7559-4000-9663-bace8adff5f2",
"type": "WEB_VIEW",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "For all Citrus Fans",
"brand_name": "Example Inc",
"call_to_action": "LISTEN",
"top_snap_media_id": "647e6398-7e44-4ae5-a19d-c400b93bce32",
"top_snap_crop_position": "MIDDLE",
"web_view_properties":
{
"url": "https://www.example.com/intro?utm_source=snapchat&utm_medium=paidsocial&utm_campaign=2019_citrus",
"deep_link_urls": [],
"block_preload": true
},
"ad_product": "SNAP_AD",
"profile_properties":
{
"profile_id": "62cf5c50-8343-48d3-a0a7-3ed45b75fa10"
}
}
}]
}
HTTP Request
You can associate a profile during create or update
POST/PUT https://adsapi.snapchat.com/v1/creatives/{creative_id}/snapcode
URL Parameters
Parameter | Description |
---|---|
creative_id | The ID of the creative to retrieve |
HTTP Request
You can associate a profile during create or update
POST/PUT https://adsapi.snapchat.com/v1/creatives/{creative_id}/snapcode
URL Parameters
Parameter | Description |
---|---|
creative_id | The ID of the creative to retrieve |
HTTP Request
You can associate a profile during create or update
POST/PUT https://adsapi.snapchat.com/v1/creatives/{creative_id}/snapcode
URL Parameters
Parameter | Description |
---|---|
creative_id | The ID of the creative to retrieve |
Commercials
Commercials are non-skippable video Snap Ads that allow you to drive awareness within Snap’s high-quality premium content.
A commercial is not a separate entity in the API, rather Creatives are eligible to be used as commercials given that they match a set of criteria including the length of the top snap video and the Creative type.
When this type of Creative is used in an Ad and targeted at Snap’s premium content bundles it will automatically run as a commercial within that content.
Commercials can currently target the following countries: AE, AU, AT, BH, CA, CH, DE, DK, FR, IQ, IE, JO, KW, NL, NZ, NO, OM, QA, SA, SE, UK, US.
Media requirements
The Media entity used as top snap in the Creative needs to be of the type
VIDEO, the length of the video along with the Creative type will then determine if the Creative can be used as a Commercial or not.
Video media with duration_in_seconds
of a minimum of 3 seconds are eligible to be used in a Creative with the intent of running as a Commercial.
Media of the type
IMAGE are not eligible to be used as Commercials.
Media Attribute | Value |
---|---|
type | VIDEO |
duration_in_seconds | 3 second minimum |
Creative requirements
Only Snap Ads can run as Commercials, the only allowed attachments are Webview and AR Lens.
Creative attribute | Value |
---|---|
type | AD_TO_LENS, SNAP_AD, WEB_VIEW |
The attribute forced_view_eligibility
needs to be set on the Creative entity, this indicates whether a Creative is eligible to be used as a Commerical or not, and for how long the Creative will be unskippable.
The forced_view_eligibility
is based on the lengh of the Media entity used as top_snap_media_id
and the intended Creative type.
Creatives classified as FULL_DURATION qualify to run as Commercials and will be unskippable for the full length of the Video, Creatives classified as SIX_SECONDS qualify to run as Commercials and will be unskippable for the first six seconds of the video, the rest of the video will be skippable.
Creatives of any other type than AD_TO_LENS, SNAP_AD, WEB_VIEW are not eligible to run as commercials and should have the forced_view_eligibility
set to NONE.
Top Snap Video length | Creative type | forced_view_eligibility value | Description |
---|---|---|---|
3 - 6 seconds | AD_TO_LENS, SNAP_AD, WEB_VIEW | FULL_DURATION | The full length of the video will be unskippable |
7 seconds or longer | AD_TO_LENS, SNAP_AD, WEB_VIEW | SIX_SECONDS | The first six seconds of the video will be unskippable |
any | APP_INSTALL, DEEP_LINK, PREVIEW, COMPOSITE, LENS, COLLECTION, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK | NONE | Creative type is not eligible to run as a Commercial |
AdSquad Targeting
Commercials can only be used in AdSquads that targets one of the following country codes: ae
, au
, at
, bh
, ca
, ch
, de
, dk
, fr
, iq
, ie
, jo
, kw
, nl
, nz
, no
, om
, qa
, sa
, se
, uk
, us
.
Additionally the AdSquad needs to specify either INSTREAM in snapchat_positions
and the premium_content_bundle_ids
targeted, this specifies the content that the Commercials are shown in.
placement_v2 attribute | Value |
---|---|
config | CUSTOM |
platforms | SNAPCHAT |
snapchat_positions | INSTREAM |
inclusion | premium_content_bundle_ids |
Premium Content Bundles
The premium content bundles represent the content where commercials can be shown, the bundles are meant to be used in a mutually exclusive manner, if you target multiple bundles you will run Commercials on all targeted content.
ID | Description |
---|---|
c7e251af-3606-4f03-91f1-98456161655d | Run of Lifestyle, Sports Shows (no News) Only |
1856c724-7cec-4139-a8a8-b87fc609f13e | Run of Shows (including News) Only |
Fetching a Media entity to inspect type and duration_in_seconds
curl "https://adsapi.snapchat.com/v1/media/5f186aa6-51e4-4c86-95fc-f273e33247e4" \
-H "Authorization: Bearer meowmeowmeow"
If the Media entity type is VIDEO and the duration_in_seconds is 3 seconds or longer it can be used in a Creative intended to run as a Commercial.
In this case the duration_in_seconds is 5.25 seconds meaning this Media can be used to set up a Creative with the forced_view_eligibility
attribute set to FULL_DURATION
.
The above request returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5db307d500ff0113ad83cc14370001737e616473617069736300016275696c642d63396263633066392d312d3239392d3100010161",
"media": [
{
"sub_request_status": "SUCCESS",
"media": {
"id": "5f186aa6-51e4-4c86-95fc-f273e33247e1",
"updated_at": "2017-10-17T12:32:09.493Z",
"created_at": "2017-10-17T12:31:19.069Z",
"name": "6569282748022784.mp4",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
"type": "VIDEO",
"media_status": "READY",
"file_name": "6569282748022784.mp4",
"download_link": "https://storage.googleapis.com/rsp-ads-prod/22225ba6-7559-4000-9663-bace8adff5f2/6569282748022784.mp4",
"duration_in_seconds": 6.72,
"video_metadata": {
"width_px": 1080,
"height_px": 1920,
"rotation": null,
"integrated_loudness": -18.2,
"true_peak": -8.1
},
"file_size_in_bytes": 6061140,
"is_demo_media": false,
"hash": "3WQFkg=="
}
}
]
}
Create a Creative with the attribute forced_view_eligibility
curl -X POST \
-d '{
"creatives": [
{
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
"name" : "Honey Badger - Webview - Commercial - FULL_TIME",
"type": "WEB_VIEW",
"headline": "Honey Badger Motion Picture",
"brand_name": "Honey Badger Movies",
"shareable": false,
"forced_view_eligibility": "FULL_DURATION",
"call_to_action": "WATCH",
"top_snap_media_id": "5f186aa6-51e4-4c86-95fc-f273e33247e1",
"web_view_properties": {
"url": "http://snapchat.com/ads"
}
}
]
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/creatives
Having checked the type and duration_in_seconds
of the Media used in top_snap_media_id
we know we can set the attribute forced_view_eligibility
to the value FULL_DURATION, this will allow the Creative to be used as a Commercial which is unskippable for it’s full duration.
The above request returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5db309da00ff04a2bcf03681950001737e616473617069736300016275696c642d63396263633066392d312d3239392d3100010106",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "2edef461-6998-4dd6-9afe-2ee2bf0d5b6c",
"updated_at": "2019-10-25T14:42:35.810Z",
"created_at": "2019-10-25T14:42:35.810Z",
"name": "Honey Badger - Webview - Commercial - FULL_TIME",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
"type": "WEB_VIEW",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": false,
"forced_view_eligibility": "FULL_DURATION",
"headline": "Honey Badger Motion Picture",
"brand_name": "Honey Badger Movies",
"call_to_action": "WATCH",
"render_type": "STATIC",
"top_snap_media_id": "5f186aa6-51e4-4c86-95fc-f273e33247e4",
"top_snap_crop_position": "MIDDLE",
"web_view_properties": {
"url": "http://snapchat.com/ads",
"allow_snap_javascript_sdk": false,
"use_immersive_mode": false,
"deep_link_urls": [],
"block_preload": false
},
"ad_product": "SNAP_AD"
}
}
]
}
Creating an AdSquad that targets premium bundles
curl -X POST \
-d '{
"adsquads":[
{
"campaign_id":"44f535d7-fde6-4b72-b76d-2d8ccf03f591",
"name":"Ad Squad - Commercial test",
"type":"SNAP_ADS",
"placement":"SNAP_ADS",
"optimization_goal":"IMPRESSIONS",
"daily_budget_micro":1000000000,
"billing_event":"IMPRESSION",
"auto_bid":true,
"target_bid":false,
"targeting":{
"regulated_content":false,
"geos":[
{
"country_code":"uk"
}
]
},
"placement_v2":{
"config":"CUSTOM",
"platforms":[
"SNAPCHAT"
],
"snapchat_positions":[
"INSTREAM"
],
"inclusion":{
"premium_content_bundle_ids":[
"31b1a5e4-2193-4542-affe-9ce62b7b17b8"
]
}
},
"start_time":"2019-10-27T13:08:53.873Z",
"pixel_id":"5eda10b7-a5fe-4ac6-80f4-417e68d748fb",
"delivery_constraint":"DAILY_BUDGET",
"pacing_type":"STANDARD"
}
]
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/campaigns/44f535d7-fde6-4b72-b76d-2d8ccf03f591/adsquads
In the placement_v2 we specify the bundle id 31b1a5e4-2193-4542-affe-9ce62b7b17b8 , this represents content made up of Lifestyle and Sports Shows (no News shows). The geo targeting country_code
attribute is restricted to the following countries: ae
, au
, at
, bh
, ca
, ch
, de
, dk
, fr
, iq
, ie
, jo
, kw
, nl
, nz
, no
, om
, qa
, sa
, se
, uk
, us
The above request returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5db063be00ff00ffff004124e334240001737e616473617069736300016275696c642d30623936353833662d312d3239382d3500010111",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "e711d041-184d-4fd8-a3df-d957c83699d4",
"updated_at": "2019-10-23T14:29:19.252Z",
"created_at": "2019-10-23T14:29:19.252Z",
"name": "Ad Squad - Commercial test",
"status": "ACTIVE",
"campaign_id": "44f535d7-fde6-4b72-b76d-2d8ccf03f591",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"geos": [
{
"country_code": "uk"
}
]
},
"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"INSTREAM"
],
"inclusion": {
"premium_content_bundle_ids": [
"31b1a5e4-2193-4542-affe-9ce62b7b17b8"
]
}
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"daily_budget_micro": 1000000000,
"start_time": "2019-10-27T13:08:53.873Z",
"optimization_goal": "IMPRESSIONS",
"pixel_id": "5eda10b7-a5fe-4ac6-80f4-417e68d748fb",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD"
}
}
]
}
Create an Ad using the Creative
curl -X POST \
-d '{
"ads": [
{
"ad_squad_id": "e711d041-184d-4fd8-a3df-d957c83699d1",
"creative_id": "2edef461-6998-4dd6-9afe-2ee2bf0d5b61",
"name": "Honey Badger Motion Picture - Ad - Commercial - FULL_DURATION",
"type": "REMOTE_WEBPAGE",
"status": "ACTIVE"
}
]
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/e711d041-184d-4fd8-a3df-d957c83699d4/ads
Finally we set up an Ad using the Creative that is eligible to serve as a Commercial and set the Ad to the AdSquad that targets premium content bundles, there are no other Commercial specific requirements for the Ad entity.
The above request returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5db3155c00ff01f1ce6a554ee80001737e616473617069736300016275696c642d63396263633066392d312d3239392d3100010152",
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "586e41db-54cd-481c-a512-e8852e74df3b",
"updated_at": "2019-10-25T15:31:40.646Z",
"created_at": "2019-10-25T15:31:40.646Z",
"name": "Honey Badger Motion Picture - Ad - Commercial - FULL_DURATION",
"ad_squad_id": "e711d041-184d-4fd8-a3df-d957c83699d1",
"creative_id": "2edef461-6998-4dd6-9afe-2ee2bf0d5b61",
"status": "ACTIVE",
"type": "REMOTE_WEBPAGE",
"render_type": "STATIC",
"review_status": "PENDING"
}
}
]
}
Creative Elements
A Creative Element is an individual unit that is combined with other Creative Elements to create a Collection Ad Creative.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
name | Creative Element name | R | |
type | Creative Type | R | BUTTON |
interaction_type | Type of interaction to be used on the element | R | WEB_VIEW, DEEP_LINK |
description | Description of the creative element | O | |
title | Title of the creative element | O | |
button_properties | Properties of the button like the image to be shown | R (for type=BUTTON) | |
web_view_properties | Properties of the web view to be used | R (if interaction_type=WEB_VIEW) | |
deep_link_properties | Properties of the deep link to be used | R (if interaction_type=DEEP_LINK) |
Additional Attributes
button_properties object must contain the following attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
button_overlay_media_id | The image to be used for the button tile | R | See MediaMust be at least 120 X 120px. Max size: 2MB |
web_view_properties object must contain the following attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
url | Web view URL | R | |
allow_snap_javascript_sdk | Allow Snapchat Javascript SDK to autofill form fields | O | true/false |
block_preload | Block Snapchat from preloading the web page | O | true/false |
deep_link_properties object must contain the following attributes
Attribute | Description | Required |
---|---|---|
deep_link_uri | Deep Link URL | R |
app_name | App name | R |
ios_app_id | iOS App ID | Optional but one of ios_app_id or android_app_url is required |
android_app_url | Google Play Store ID | Optional but one of ios_app_id or android_app_url is required |
icon_media_id | Icon Media ID | R |
fallback_type | Type of fallback to be used when user doesn’t have the app | O |
web_view_fallback_url | Fallback web url to be used | O |
product_page_id | Custom product page ID from iOS App Store. Only set when using a Custom Product Page | O |
Create a Creative Element
curl -X POST \
-d '{"creative_elements": [{"name":"Product 1 button", "type":"BUTTON", "description": "Product 1", "interaction_type":"WEB_VIEW", "title":"Best title", "button_properties":{"button_overlay_media_id":"008a5ae9-bcc1-4c2e-a3f1-7e924d582019"},"web_view_properties":{"url":"https://snapchat.com"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creative_elements
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5bee332000ff06b565385cab550001737e616473617069736300016275696c642d33373039663463642d312d3232302d3000010145",
"creative_elements": [
{
"sub_request_status": "SUCCESS",
"creative_element": {
"id": "f63bb5f5-471c-404f-8f0d-e5c1a003e4d9",
"updated_at": "2018-11-16T03:01:52.907Z",
"created_at": "2018-11-16T03:01:52.907Z",
"name": "Product 1 button",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "BUTTON",
"interaction_type": "WEB_VIEW",
"title": "Best title",
"description": "Product 1",
"button_properties": {
"button_overlay_media_id": "008a5ae9-bcc1-4c2e-a3f1-7e924d582019"
},
"web_view_properties": {
"url": "https://snapchat.com",
"allow_snap_javascript_sdk": false,
"use_immersive_mode": false,
"deep_link_urls": [],
"block_preload": false
}
}
}
]
}
Create Multiple Creative Elements
curl -X POST \
-d '{"creative_elements": [{"name":"Product 1 button", "type":"BUTTON", "description": "Product 1", "interaction_type":"WEB_VIEW", "title":"Best title", "button_properties":{"button_overlay_media_id":"008a5ae9-bcc1-4c2e-a3f1-7e924d582019"},"web_view_properties":{"url":"https://snapchat.com"}}, {"name":"Product 2 button", "type":"BUTTON", "description": "Product 2", "interaction_type":"WEB_VIEW", "title":"Best title", "button_properties":{"button_overlay_media_id":"008a5ae9-bcc1-4c2e-a3f1-7e924d582012"},"web_view_properties":{"url":"https://snapchat2.com"}}, {"name":"Product 3 button", "type":"BUTTON", "description": "Product 3", "interaction_type":"WEB_VIEW", "title":"Best title", "button_properties":{"button_overlay_media_id":"008a5ae9-bcc1-4c2e-a3f1-7e924d582013"},"web_view_properties":{"url":"https://snapchat3.com"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creative_elements
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5bee33f200ff057a031dfee6af0001737e616473617069736300016275696c642d33373039663463642d312d3232302d300001011a",
"creative_elements": [
{
"sub_request_status": "SUCCESS",
"creative_element": {
"id": "70debf44-cb4b-4b5f-8828-bd2b68b9f0ca",
"updated_at": "2018-11-16T03:05:23.241Z",
"created_at": "2018-11-16T03:05:23.241Z",
"name": "Product 1 button",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "BUTTON",
"interaction_type": "WEB_VIEW",
"title": "Best title",
"description": "Product 1",
"button_properties": {
"button_overlay_media_id": "008a5ae9-bcc1-4c2e-a3f1-7e924d582019"
},
"web_view_properties": {
"url": "https://snapchat.com",
"allow_snap_javascript_sdk": false,
"use_immersive_mode": false,
"deep_link_urls": [],
"block_preload": false
}
}
},
{
"sub_request_status": "SUCCESS",
"creative_element": {
"id": "a2d1c8a0-0466-4924-b769-7a7e6ed5be3d",
"updated_at": "2018-11-16T03:05:23.241Z",
"created_at": "2018-11-16T03:05:23.241Z",
"name": "Product 2 button",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "BUTTON",
"interaction_type": "WEB_VIEW",
"title": "Best title",
"description": "Product 2",
"button_properties": {
"button_overlay_media_id": "008a5ae9-bcc1-4c2e-a3f1-7e924d582012"
},
"web_view_properties": {
"url": "https://snapchat.com",
"allow_snap_javascript_sdk": false,
"use_immersive_mode": false,
"deep_link_urls": [],
"block_preload": false
}
}
},
{
"sub_request_status": "SUCCESS",
"creative_element": {
"id": "4091233e-3351-405d-8684-a97e70c3b5da",
"updated_at": "2018-11-16T03:05:23.242Z",
"created_at": "2018-11-16T03:05:23.242Z",
"name": "Product 3 button",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "BUTTON",
"interaction_type": "WEB_VIEW",
"title": "Best title",
"description": "Product 3",
"button_properties": {
"button_overlay_media_id": "008a5ae9-bcc1-4c2e-a3f1-7e924d582013"
},
"web_view_properties": {
"url": "https://snapchat.com",
"allow_snap_javascript_sdk": false,
"use_immersive_mode": false,
"deep_link_urls": [],
"block_preload": false
}
}
}
]
}
Create an Interaction Zone
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
name | Creative Element name | R | |
headline | Headline for the interaction zone | R | Same as all allowed call_to_action values for Web View Creative |
creative_elements | Array of Creative Element IDs | R | Must have at least 4 creative elements. |
curl -X POST \
-d '{"interaction_zones": [{"name": "First Interaction Zone", "creative_element_ids": ["d28427e5-0604-406c-8f23-167b211a3317","dc80a56f-800c-499b-846b-78e74bd39a9d","75a98c65-1e62-4507-97fe-50cbc523523a","faefe7cd-567d-4647-bb1d-b918fb0ac98a", "f63bb5f5-471c-404f-8f0d-e5c1a003e4d9"], "headline":"MORE"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/interaction_zones
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5bee38df00ff00ff5858a22dbc9f0001737e616473617069736300016275696c642d33373039663463642d312d3232302d3000010154",
"interaction_zones": [
{
"sub_request_status": "SUCCESS",
"interaction_zone": {
"id": "a218dc8b-7a79-4da6-9a1c-e5a581c7bd46",
"updated_at": "2018-11-16T03:26:23.130Z",
"created_at": "2018-11-16T03:26:23.130Z",
"name": "First Interaction Zone",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"headline": "MORE",
"creative_element_ids": [
"70debf44-cb4b-4b5f-8828-bd2b68b9f0cf",
"a2d1c8a0-0466-4924-b769-7a7e6ed5be3b",
"4091233e-3351-405d-8684-a97e70c3b5dc",
"f63bb5f5-471c-404f-8f0d-e5c1a003e4d9"
]
}
}
]
}
Targeting
The API offers a variety of Targeting options to allow an advertiser to find the right user at the right time.
There are a variety of endpoints offered that expose the available targeting options.
Targeting Spec
The targeting spec should be constructed based on the possible dimensions outlined below.
Attribute | Description | Required | Note |
---|---|---|---|
app_install_states | Defines whether targeted user has App installed or not | O | For usage see App Install states |
demographics | List of Demographic Targets | O | Required when using Multi-country targeting |
devices | List of Device Targets | O | |
geos | List of Geo/Location Targets | R | Multi-country targeting is allowed from 1st April 2020, each country needs to be placed in a geos entry, a targeting spec that uses multi-country targeting needs to also include a demographics entry that incorporates a single languages entry |
interests | List of Interest Targets | O | |
locations | List of Location categories/Circles | O | |
regulated_content | Flag to mark content within the Ad Squad as Regulated Content | O | FALSE (default), TRUE |
segments | List of Customer List segment targets | O | |
auto_expansion_options | This option allows Snapchat to expand the targeting based on selected interest targeting and/or selected custom audiences, by default both of these options are enabled on creation | O | For usage see Targeting auto-expansion |
General Guidance
In general, dimensions that are grouped within the same JSON object is in AND relation. JSON objects within a JSON array are in OR relation. The exception to this is EXCLUDE, which is always AND and applied last.
Targeting Inclusion / Exclusion
Category | Type | Support | Description |
---|---|---|---|
app_install_states | app installation state | See App Install states | Defines whether targeted user has App installed or not |
demographics | gender, languages, age_group, min_age, max_age, DLXD | INCLUDE | Gender, Language, Age Groups, Age Range, Advanced Demographics |
devices | connection_type, os_type, os_version, carrier, marketing_name | INCLUDE | Connection type, OS Type, OS Version, Carrier, Make |
geos | country | INCLUDE/EXCLUDE | Multi-country targeting is allowed from 1st April 2020, each country needs to be placed in a geos entry, a targeting spec that uses multi-country targeting needs to also include a demographics entry that incorporates a single languages entry |
geos | region | INCLUDE/EXCLUDE | Region/State |
geos | metro | INCLUDE/EXCLUDE | Metro/DMA |
geos | postal_code | INCLUDE/EXCLUDE | Zipcode/Post code |
interests | SLC | INCLUDE/EXCLUDE | Snap Lifestyle Categories |
interests | DLX, DLXS, DLXC, NLN, PLC, VAC | INCLUDE | Oracle Datalogix DLX/DLXS/DLXC Interest Targeting, Nielsen Interest Targeting NLN, Placed Visitation PLC, Snap Visitation VAC |
locations | categories_loi, circles | INCLUDE | Location Categories, Location Point Radius |
segments | segment_id | INCLUDE/EXCLUDE | Customer List, Pixel Custom Audiences, Mobile Audiences, Engagement Audiences |
Targeting auto-expansion
The auto_expansion_options
object contains two attribures that will expand the targeting of the Ad Squad based on similar qualities and characteristics used in the existing targeting. These two attributes are both enabled by default on creation of the Ad Squad.
Ad Squads that form part of a Campaign advertising Housing, Credit or Employment, should always have auto-expansion disabled.
Name | Description | Possible Values |
---|---|---|
interest_expansion_option.enabled | Expands targeting based on interest targeting | true (default),false |
custom_audience_expansion_option.enabled | Expands targeting based on selected custom audiences | true (default),false |
Targeting auto-expansion usage examples
Example 1
Example 1 - Expand targeting based both on interest and custom audiences:
"auto_expansion_options":
{
"interest_expansion_option":
{
"enabled": true
},
"custom_audience_expansion_option":
{
"enabled": true
}
}
This configuration will expand the targeting based both on interest and custom audiences.
Example 2
Example 2 - Expand targeting based on interest targeting only:
"auto_expansion_options":
{
"interest_expansion_option":
{
"enabled": true
},
"custom_audience_expansion_option":
{
"enabled": false
}
}
This configuration will expand the targeting based on interest targeting only.
Example 3 - Housing, Credit or Employment
Example 3 - Do not expand targeting:
"auto_expansion_options":
{
"interest_expansion_option":
{
"enabled": false
},
"custom_audience_expansion_option":
{
"enabled": false
}
}
No targeting expansion, this configuration should be used for Campaigns advertising Housing, Credit or Employment.
App Install states
App Install states targeting can be used with the Creative types APP_INSTALL and DEEP_LINK and allows you to target a user given the user’s install state for a specific App that you own. Using App Install state targeting comes with two prerequisites:
- A Snap App ID for the App needs to be set up in order to verify your app setting up your Snap App ID.
- The Ad Squad needs to have the
event_sources
attribute set up, the Snap App ID used inevent_sources
should match the Snap App ID used in theapp_install_states
App Install state targeting can be applied in two different scenarios:
- When using the Optimization Goal APP_REENGAGE_OPEN or APP_REENGAGE_PURCHASE, see targeting example
- When using Dynamic Product Ads and
product_audiences
, see below table and targeting example
App Install state / Optimization Goals
Ad type | Install state | Optimization goals | Description |
---|---|---|---|
APP_INSTALL | NOT_INSTALLED | IMPRESSIONS, SWIPES, APP_INSTALL, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGNUP | Targets users that don’t have the app installed |
DEEP_LINK | INSTALLED | IMPRESSIONS, SWIPES, APP_REENGAGE_OPEN, APP_REENGAGE_PURCHASE | Targets users that have the app installed |
DEEP_LINK | NOT_INSTALLED | IMPRESSIONS, SWIPES, APP_INSTALLS, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGN_UP | Targets users that don’t have the app installed |
DEEP_LINK | ALL | IMPRESSIONS, SWIPES | All users targeted |
App Install state / Product Audience
Ad type | Product Audience | Install state | Optimization goals |
---|---|---|---|
APP_INSTALL | Prospecting | NOT_INSTALLED | IMPRESSIONS, SWIPES, APP_INSTALL, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGNUP |
DEEP_LINK | Retargeting | INSTALLED | IMPRESSIONS, SWIPES, APP_REENGAGE_OPEN, APP_REENGAGE_PURCHASE |
DEEP_LINK | Prospecting | NOT_INSTALLED | IMPRESSIONS, SWIPES, APP_INSTALLS, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGN_UP |
DEEP_LINK | Prospecting | ALL | IMPRESSIONS, SWIPES |
Targeting Dimensions
All targeting dimensions will now have a deprecated boolean flag that will show whether the targeting dimension is deprecated. If a dimension has deprecated=true you will no longer be able to use it in the targeting_spec of an Ad Squad.
Targeting Type Support by Country
curl "https://adsapi.snapchat.com/v1/targeting/v1/options?country_code=us" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "86fd4602-89cd-46d4-a843-05d45dab484f",
"targeting_option": {
"snap_ads": [
"demographics:advanced_demographics",
"demographics:age_groups",
"demographics:age_min_max",
"demographics:gender",
"demographics:languages",
"devices:carrier",
"devices:connection_type",
"devices:marketing_name",
"devices:os_type",
"geos:country",
"geos:electoral",
"geos:metro",
"geos:postal_code",
"geos:region",
"interests:dlxc",
"interests:dlxs",
"interests:i360",
"interests:nln",
"interests:plc",
"interests:slc",
"interests:tgst",
"interests:vac",
"locations:chain_packages",
"locations:circles",
"locations:lois",
"regulated_content",
"segments:ab_segments",
"segments:engagement",
"segments:first_party",
"segments:fti",
"segments:lookalike",
"segments:mobile",
"segments:pixel"
]
}
}
This endpoint retrieves all targeting options available for the specified country code.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/v1/options
Parameters
Parameter | Required | Possible values | Description |
---|---|---|---|
country_code | R | ISO ALPHA-2 Country Code (lowercase) | |
is_intl_vac_enabled | O | true, false (default) | This parameter should be used to produce valid VAC options for countries outside of the US |
Example #1 Targeting Support for Germany
curl "https://adsapi.snapchat.com/v1/targeting/v1/options?country_code=de&is_intl_vac_enabled=true" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "f41d20fa-5ec2-45c9-8afd-a90efaaf764c",
"targeting_option": {
"snap_ads": [
"demographics:age_groups",
"demographics:age_min_max",
"demographics:gender",
"demographics:languages",
"devices:carrier",
"devices:connection_type",
"devices:marketing_name",
"devices:os_type",
"geos:country",
"geos:metro",
"geos:postal_code",
"geos:region",
"interests:slc",
"interests:vac",
"locations:chain_packages",
"locations:circles",
"regulated_content",
"segments:ab_segments",
"segments:engagement",
"segments:first_party",
"segments:fti",
"segments:lookalike",
"segments:mobile",
"segments:pixel"
]
}
}
This example retrieves all targeting options available for Germany.
Demographics
Demographics targeting allows an advertiser to find a user based on a variety of criteria.
Demographics - Age Groups
Get Age Group Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/demographics/age_group" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "57d1cb6900ff0c21bb32e920a00001737e616473617069736300016275696c642d66333735626434642d312d31332d3700010111",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"age_group": {
"name": "13-17",
"id": "13"
}
},
{
"sub_request_status": "SUCCESS",
"age_group": {
"name": "18-20",
"id": "18"
}
},
{
"sub_request_status": "SUCCESS",
"age_group": {
"name": "21-24",
"id": "21"
}
},
{
"sub_request_status": "SUCCESS",
"age_group": {
"name": "25-34",
"id": "25"
}
},
{
"sub_request_status": "SUCCESS",
"age_group": {
"name": "35+",
"id": "35"
}
}
]
}
This endpoint retrieves the list of age group targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/demographics/age_group
Demographics - Age Range
You can target ages using “min_age” and “max_age” attributes without using predefined age groups. Leaving out “max_age” from the targeting_spec will result in no age cap. Leaving out “min_age” will target 13 as the minimum age.
Attribute | Description | Possible values |
---|---|---|
min_age | 35+ is deprecated but may be found in existing ad squads | 35+ |
min_age | integer, defines the minimum age targeted | 13 - 35 |
max_age | integer, defines the maximum age targeted. If you want no maximum cap, do not set a max_age | 13 - 49 |
See the Targeting Spec Examples for usage examples.
Demographics - Gender
Get Gender Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/demographics/gender" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "57d1cb8800ff01f6194d8f9a100001737e616473617069736300016275696c642d66333735626434642d312d31332d370001010f",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"gender": {
"name": "MALE",
"id": "1"
}
},
{
"sub_request_status": "SUCCESS",
"gender": {
"name": "FEMALE",
"id": "2"
}
},
{
"sub_request_status": "SUCCESS",
"gender": {
"name": "OTHER",
"id": "3"
}
}
]
}
This endpoint retrieves the list of gender targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/demographics/gender
Demographics - Language
Get Language Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/demographics/languages" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "591e4d8c00ff065b2527b9753e0001737e616473617069736300016275696c642d31616566313737632d312d36382d3000010156",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"languages": {
"id": "ar",
"name": "Arabic"
}
},
{
"sub_request_status": "SUCCESS",
"languages": {
"id": "en",
"name": "English"
}
},
{
"sub_request_status": "SUCCESS",
"languages": {
"id": "es",
"name": "Spanish"
}
},
{
"sub_request_status": "SUCCESS",
"languages": {
"id": "zh",
"name": "Chinese"
}
}
]
}
This endpoint retrieves the list of language targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/demographics/languages
Demographics - Advanced Demographics
Get Advanced Demographics Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/demographics/advanced_demographics" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "57d1cb6900ff0c21bb32e920a00001737e616473617069736300016275696c642d66333735626434642d312d31332d3700010111",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"advanced_demographics": {
"name": "College Graduates",
"id": "DLXD_100"
}
},
{
"sub_request_status": "SUCCESS",
"advanced_demographics": {
"name": "Married People",
"id": "DLXD_300"
}
}
]
}
This endpoint retrieves the list of Advanced Demographics targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/demographics/advanced_demographics
Device
Device targeting allows an advertiser to find a user based on a variety of criteria regarding the user’s mobile device.
Device - Connection Type
Get Connection Type Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/device/connection_type"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"status": "success",
"request_id": "57abbd65000543a87d7116e2",
"targeting_dimensions": [
{
"sub_request_status": "success",
"connection_type": {
"name": "WIFI",
"id": "1"
}
},
{
"sub_request_status": "success",
"connection_type": {
"name": "CELL",
"id": "2"
}
}
]
}
This endpoint retrieves the list of device connection type targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/device/connection_type
Device - OS Type
Get Device OS Type Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/device/os_type"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"status": "success",
"request_id": "57abbe48000da048b37f6ddc",
"targeting_dimensions": [
{
"sub_request_status": "success",
"os_type": {
"name": "iOS",
"id": "1"
}
},
{
"sub_request_status": "success",
"os_type": {
"name": "ANDROID",
"id": "2"
}
}
]
}
This endpoint retrieves the list of device OS type targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/device/os_type
Device - OS Version
Get Device OS Version Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/device/iOS/os_version"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5913bd1900ff0878f97f6fb40f0001737",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"os_version": {
"id": "1970324836974592",
"name": "7.0"
}
},
{
"sub_request_status": "SUCCESS",
"os_version": {
"id": "1970333426909184",
"name": "7.0.2"
}
},
[[snip]]
{
"sub_request_status": "SUCCESS",
"os_version": {
"id": "2818056891924480",
"name": "10.3.2"
}
}
]
}
This endpoint retrieves the list of device OS version targeting options. These OS versions can then be used in targeting as os_version_min and os_version_max.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/device/{{OS_TYPE}}/os_version
Parameter | Possible Values |
---|---|
OS_TYPE | iOS, ANDROID |
Device - Carrier
Get Device Carrier Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/device/carrier"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5833291400ff098fc49db751b80001737e616473617069736300016275696c642d32663033323832622d646d612d63617272696572320001011e",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"carrier": {
"id": "US_ATT",
"name": "AT&T",
"valid_country": "us"
}
},
{
"sub_request_status": "SUCCESS",
"carrier": {
"id": "US_BOOSTMOBILE",
"name": "Boost Mobile",
"valid_country": "us"
}
},
{
"sub_request_status": "SUCCESS",
"carrier": {
"id": "US_CSPIRE",
"name": "C Spire",
"valid_country": "us"
}
}
]
}
This endpoint retrieves the list of device carrier targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/device/carrier
Device - Make
Get Device Make Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/device/marketing_name"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5964167200ff0255988362e6420001737e616473617069736300016275696c642d32353936663565632d312d38312d3100010126",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"marketing_name": {
"id": "Acer/",
"name": "Acer"
}
},
{
"sub_request_status": "SUCCESS",
"marketing_name": {
"id": "Apple/",
"name": "Apple"
}
},
{
"sub_request_status": "SUCCESS",
"marketing_name": {
"id": "Apple/iPad (3rd Gen)/",
"name": "Apple > iPad (3rd Gen)"
}
},
[[[snip]]]
{
"sub_request_status": "SUCCESS",
"marketing_name": {
"id": "Xiaomi/Redmi Note 4/",
"name": "Xiaomi > Redmi Note 4"
}
},
{
"sub_request_status": "SUCCESS",
"marketing_name": {
"id": "ZTE/",
"name": "ZTE"
}
},
{
"sub_request_status": "SUCCESS",
"marketing_name": {
"id": "ZTE/Zmax Pro/",
"name": "ZTE > Zmax Pro"
}
}
]
}
This endpoint retrieves the list of device make targeting options. Please note that specifying a parent level make option like “Apple/” in the targeting spec will include all devices of the kind “Apple/*” like “Apple/iPad (3rd Gen)/”, “Apple/iPhone 4/”, “Apple/iPhone 7 Plus/” etc.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/device/marketing_name
Geolocation
Geolocation targeting is based on the device’s location at the time the ad is served.
Geolocation - Country
Get Country Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/geo/country"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"status": "success",
"request_id": "57abb71f00067458450ddec8",
"targeting_dimensions": [
{
"sub_request_status": "success",
"country": {
"lat": 0,
"lon": 0,
"continent": {
"id": "3",
"name": "au"
},
"country": {
"id": "166",
"name": "cocos (keeling) islands",
"code": "cck",
"code2": "cc"
}
}
},
{
"sub_request_status": "success",
"country": {
"lat": 0,
"lon": 0,
"continent": {
"id": "5",
"name": "eu"
},
"country": {
"id": "246",
"name": "finland",
"code": "fin",
"code2": "fi"
}
}
},
[[[ snip ]]]
{
"sub_request_status": "success",
"country": {
"lat": 0,
"lon": 0,
"continent": {
"id": "3",
"name": "au"
},
"country": {
"id": "334",
"name": "heard and mc donald islands",
"code": "hmd",
"code2": "hm"
}
}
},
{
"sub_request_status": "success",
"country": {
"lat": 0,
"lon": 0,
"continent": {
"id": "1",
"name": "af"
},
"country": {
"id": "454",
"name": "malawi",
"code": "mwi",
"code2": "mw"
}
}
}
]
}
This endpoint retrieves the list of country targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/geo/country
Geolocation - Region / State
Get Region / State Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/geo/us/region"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"status": "success",
"request_id": "57abb9ac000caa30eb4ac303",
"targeting_dimensions": [
{
"sub_request_status": "success",
"region": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "usa",
"code2": "us"
},
"region": {
"id": "16",
"code": "ia",
"name": "iowa"
}
}
},
{
"sub_request_status": "success",
"region": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "usa",
"code2": "us"
},
"region": {
"id": "21",
"code": "md",
"name": "maryland"
}
}
},
[[[ snip ]]]
{
"sub_request_status": "success",
"region": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "usa",
"code2": "us"
},
"region": {
"id": "31",
"code": "nj",
"name": "new jersey"
}
}
},
{
"sub_request_status": "success",
"region": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "usa",
"code2": "us"
},
"region": {
"id": "22",
"code": "ma",
"name": "massachusetts"
}
}
},
{
"sub_request_status": "success",
"region": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "usa",
"code2": "us"
},
"region": {
"id": "48",
"code": "wa",
"name": "washington"
}
}
}
]
}
This endpoint retrieves the list of region/state targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/geo/{country_code}/region
Parameters
Parameter | Default | Description |
---|---|---|
country_code | ISO ALPHA-2 Country Code (lowercase) |
Geolocation - Metro / DMA
Get Metro / DMA Options
curl "https://adsapi.snapchat.com/v1/targeting/geo/us/metro"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5848879d00ff0ade2a482631b50001737e616473617069736300016275696c642d39323764616530622d312d32372d330001010c",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"metro": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "us",
"code2": "us"
},
"metro": {
"id": "557",
"name": "knoxville",
"regions": "ky/tn"
}
}
},
{
"sub_request_status": "SUCCESS",
"metro": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "us",
"code2": "us"
},
"metro": {
"id": "641",
"name": "san antonio",
"regions": "tx"
}
}
},
[[[ snip ]]]
{
"sub_request_status": "SUCCESS",
"metro": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "us",
"code2": "us"
},
"metro": {
"id": "717",
"name": "quincy-hannibal-keokuk",
"regions": "ia/il/mo"
}
}
},
{
"sub_request_status": "SUCCESS",
"metro": {
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "us",
"code2": "us"
},
"metro": {
"id": "546",
"name": "columbia, sc",
"regions": "sc"
}
}
}
]
}
This endpoint retrieves the list of metro/dma targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/geo/{country_code}/metro
Parameters
Parameter | Default | Description |
---|---|---|
country_code | ISO ALPHA-2 Country Code (lowercase) |
Zipcode
Get Zipcode Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/geo/us/postal_code?cursor=0&limit=500"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "594db13f00ff05364288a100ff4b0001737e616473617069736300016275696c642d36356130306562372d312d37382d3100010121",
"paging": {
"next_link": "https://adsapisc.appspot.com/v1/targeting/geo/us/postal_code?limit=500&cursor=1"
},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"postal_code": {
"postalCode": "13024",
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "us",
"code2": "us"
},
"region": {
"id": "33",
"code": "ny",
"name": "new york"
},
"city": {
"id": "4587",
"name": "auburn"
}
}
},
[[snip]
{
"sub_request_status": "SUCCESS",
"postal_code": {
"postalCode": "94927",
"lat": 0,
"lon": 0,
"continent": {
"id": "6",
"name": "na"
},
"country": {
"id": "840",
"name": "united states",
"code": "us",
"code2": "us"
},
"region": {
"id": "5",
"code": "ca",
"name": "california"
},
"city": {
"id": "2370",
"name": "rohnert park"
}
}
}
]
}
This endpoint retrieves the list of zipcode targeting options.
This endpoint supports pagination. Specify the number of entries to be returned using the limit paramter. The paging object in the response will include next_link which indicates the next url to be fetched.
Please note that United Arab Emirates do not use zip codes.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/geo/{country_code}/postal_code?cursor=0&limit=500
Parameters
Parameter | Default | Description |
---|---|---|
country_code | ISO ALPHA-2 Country Code (lowercase) | |
cursor | cursor/page number | |
limit | Page size. the number of entries to be retrieved in one page. Can be between 10-10000 |
Interests
Interest targeting allows an advertiser to find a user based on Snap Lifestyle Categories , Oracle Datalogix (DLX) Interests, Placed Visitation Segments and Snap Visitation Segments.
The availability of interest targeting will vary from country to country, you should also take into account if the Campaign is targeting Housing, Credit or Employment in which case the interest categories may look different.
Interests - Snap Lifestyle Categories
curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/scls?country_code=us"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "490744c7-a663-4e9c-95b9-edc947cb6ce6",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_1",
"name": "Adventure Seekers",
"path": "/Adventure Seekers",
"parent_id": "SLC_0",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10",
"name": "Do-It-Yourselfers",
"path": "/Do-It-Yourselfers",
"parent_id": "SLC_0",
"source": "SNAPCHAT"
}
},
<<snip>>
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_97",
"name": "Cricket Fans",
"path": "/Sports Fans/Cricket Fans",
"parent_id": "SLC_67",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_98",
"name": "Crime & Mystery Genre Fans",
"path": "/Film & TV Fans/Crime & Mystery Genre Fans",
"parent_id": "SLC_12",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_99",
"name": "Indie & Foreign Film Fans",
"path": "/Film & TV Fans/Indie & Foreign Film Fans",
"parent_id": "SLC_12",
"source": "SNAPCHAT"
}
}
]
}
This endpoint retrieves the list of Snap Lifestyle Categories targeting options by the specified country code.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/v1/interests/scls
Parameters
Parameter | Default | Description |
---|---|---|
country_code | ISO ALPHA-2 Country Code (lowercase) | |
is_hec | true | optional parameter, returns interest targeting that is safe to use when advertising Housing, Credit and Employment |
limit | integer, min 50, max 1000 |
Interests - SCLS example
curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/scls?country_code=us&is_hec=true"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "40b06393-59de-46e7-b84a-f01d0708d3c6",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10002",
"name": "Arts & Culture Mavens - HEC",
"path": "/Arts & Culture Mavens - HEC",
"parent_id": "SLC_0",
"source": "SNAPCHAT",
"is_hec": true
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10004",
"name": "Beachgoers & Surfers - HEC",
"path": "/Beachgoers & Surfers - HEC",
"parent_id": "SLC_0",
"source": "SNAPCHAT",
"is_hec": true
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10009",
"name": "Comics & Animation Fans - HEC",
"path": "/Comics & Animation Fans - HEC",
"parent_id": "SLC_0",
"source": "SNAPCHAT",
"is_hec": true
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10012",
"name": "Film & TV Fans - HEC",
"path": "/Film & TV Fans - HEC",
"parent_id": "SLC_0",
"source": "SNAPCHAT",
"is_hec": true
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10015",
"name": "Cordcutters - HEC",
"path": "/Film & TV Fans - HEC/Cordcutters - HEC",
"parent_id": "SLC_10012",
"source": "SNAPCHAT",
"is_hec": true
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10016",
"name": "Drama Genre Fans - HEC",
"path": "/Film & TV Fans - HEC/Drama Genre Fans - HEC",
"parent_id": "SLC_10012",
"source": "SNAPCHAT",
"is_hec": true
}
},
<<snip>>
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10220",
"name": "Console Gamers - HEC",
"path": "/Gamers - HEC/Console Gamers - HEC",
"parent_id": "SLC_10033",
"source": "SNAPCHAT",
"is_hec": true
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10221",
"name": "PC Gamers - HEC",
"path": "/Gamers - HEC/PC Gamers - HEC",
"parent_id": "SLC_10033",
"source": "SNAPCHAT",
"is_hec": true
}
}
]
}
Example of retrieving Snap Lifestyle Categories for use a campaign promoting Housing, Credit or Employment.
Interests - First Party Visitation Segments
Interest targeting based on visitation segments that are provided by Snap.
Get First Party Visitation Segments
curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/vac?country_code=us"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "cc492ca5-33cd-4c23-949d-b869d6e0e2d5",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_1",
"name": "Arts & Entertainment",
"path": "/Arts & Entertainment",
"parent_id": "VAC_0",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_100",
"name": "Chipotle Restaurants",
"path": "/Dining & Nightlife/Fast Casual Restaurants/Chipotle Restaurants",
"parent_id": "VAC_99",
"source": "SNAPCHAT"
}
},
<snip>
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_97",
"name": "Ice Cream Shops",
"path": "/Dining & Nightlife/Sweet & Dessert Shops/Ice Cream Shops",
"parent_id": "VAC_96",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_99",
"name": "Fast Casual Restaurants",
"path": "/Dining & Nightlife/Fast Casual Restaurants",
"parent_id": "VAC_53",
"source": "SNAPCHAT"
}
}
]
}
This endpoint retrieves a list of targeting options for First Party Visitation Segments.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/v1/interests/vac
Parameters
Parameter | Possible values | Description |
---|---|---|
country_code | ISO ALPHA-2 Country Code (lowercase) | |
is_hec | true, false (default) | optional parameter, returns interest targeting that is safe to use when advertising Housing, Credit and Employment (only available for US) |
limit | integer, min 50, max 1000 |
Interests - VAC example #1 United States
curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/vac?is_hec=true&country_code=us"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "913bdce1-8dbf-4dce-a224-cf7ca1edc538",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_10001",
"name": "Arts & Entertainment - HEC",
"path": "/Arts & Entertainment - HEC",
"parent_id": "VAC_0",
"source": "SNAPCHAT",
"is_hec": true
}
},
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_10008",
"name": "Movie Theaters - HEC",
"path": "/Arts & Entertainment - HEC/Movie Theaters - HEC",
"parent_id": "VAC_10001",
"source": "SNAPCHAT",
"is_hec": true
}
},
<snip>
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_10291",
"name": "Theme Parks - HEC",
"path": "/Travel - HEC/Theme Parks - HEC",
"parent_id": "VAC_10265",
"source": "SNAPCHAT",
"is_hec": true
}
},
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_10292",
"name": "Disney Parks and Hotels - HEC",
"path": "/Travel - HEC/Theme Parks - HEC/Disney Parks and Hotels - HEC",
"parent_id": "VAC_10291",
"source": "SNAPCHAT",
"is_hec": true
}
}
]
}
Example of retrieving First Party Visitation Segments for use with an Ad Set promoting Housing, Credit or Employment, targeting the United States.
Interests - VAC example #2 Germany
curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/vac?country_code=de"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "8a22cbcd-8f4b-423b-87d0-f0528399ffb7",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_1",
"name": "Arts & Entertainment",
"path": "/Arts & Entertainment",
"parent_id": "VAC_0",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_100",
"name": "Chipotle Restaurants",
"path": "/Dining & Nightlife/Fast Casual Restaurants/Chipotle Restaurants",
"parent_id": "VAC_99",
"source": "SNAPCHAT"
}
},
<snip>
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_97",
"name": "Ice Cream Shops",
"path": "/Dining & Nightlife/Sweet & Dessert Shops/Ice Cream Shops",
"parent_id": "VAC_96",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"vac": {
"id": "VAC_99",
"name": "Fast Casual Restaurants",
"path": "/Dining & Nightlife/Fast Casual Restaurants",
"parent_id": "VAC_53",
"source": "SNAPCHAT"
}
}
]
}
Example of retrieving First Party Visitation Segments for use with an Ad Set targeting Germany.
Interests - First Party Shopper Segments
Interest targeting based on shopper segments that are provided by Snap.
Get First Party Shopper Segments
curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/shp?country_code=us&limit=50"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "576f7f3a-c58b-407d-bdbf-21802c8b61b9",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"shp": {
"id": "SHP_73",
"name": "Amusement Parks Buyers",
"path": "/Amusement Parks Buyers",
"parentId": "SHP_0",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"shp": {
"id": "SHP_99",
"name": "Disney Parks",
"path": "/Amusement Parks Buyers/Disney Parks",
"parentId": "SHP_73",
"source": "SNAPCHAT"
}
},
<snip>
{
"sub_request_status": "SUCCESS",
"shp": {
"id": "SHP_37",
"name": "Hotel & Motel Buyers",
"path": "/Travel Services Buyers/Hotel & Motel Buyers",
"parentId": "SHP_15",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"shp": {
"id": "SHP_122",
"name": "eCommerce Buyers",
"path": "/eCommerce Buyers",
"parentId": "SHP_0",
"source": "SNAPCHAT"
}
}
]
}
This endpoint retrieves a list of targeting options for First Party Shopper Segments.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/v1/interests/shp
Parameters
Parameter | Default | Description | Possible values |
---|---|---|---|
country_code | ISO ALPHA-2 Country Code (lowercase) | us | |
limit | integer, min 50, max 1000 |
Interests - Oracle Datalogix (DLX)
Interest targeting can also be based on Oracle Datalogix (DLX) Interests.
Get Oracle Datalogix DLXS Interest Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/interests/dlxs"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57acea61000484407b52009b",
"targeting_dimensions": [
{
"sub_request_status": "success",
"dlxs": {
"name": "Apparel Shoppers",
"id": "DLXS_1"
}
},
{
"sub_request_status": "success",
"dlxs": {
"name": "Small & Mid-size SUV Shoppers",
"id": "DLXS_100"
}
}
]
}
This endpoint retrieves the list of Oracle Datalogix DLXS Interests targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/interests/dlxs
Get Oracle Datalogix DLXC Interest Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/interests/dlxc"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57acea61000484407b52009b",
"targeting_dimensions": [
{
"sub_request_status": "success",
"dlxc": {
"name": "Home Movie Viewers (Action)",
"id": "DLXC_101"
}
},
{
"sub_request_status": "success",
"dlxc": {
"name": "TV Viewers (Variety Shows)",
"id": "DLXC_133"
}
}
]
}
This endpoint retrieves the list of Oracle Datalogix DLXC targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/interests/dlxc
Get Oracle Datalogix DLXP Interest Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/interests/dlxp"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "590850dd00ff05d022b1d7a5c50001737e616473617069736300016275696c642d62663930383438312d312d36322d320001013e",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"dlxp": {
"id": "DLXP_107",
"name": "Ford Dealers"
}
},
{
"sub_request_status": "SUCCESS",
"dlxp": {
"id": "DLXP_108",
"name": "Foreign Vehicle Dealers"
}
},
{
"sub_request_status": "SUCCESS",
"dlxp": {
"id": "DLXP_109",
"name": "Honda Dealers"
}
}
]
}
This endpoint retrieves the list of Oracle Datalogix DLXP targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/interests/dlxp
Get Nielsen Interest Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/interests/nln"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b3426d900ff072f79188f4fe20001737e616473617069736300016275696c642d38666335393665372d312d3137392d",
"paging": {
"next_link": "https://adsapisc.appspot.com/v1/targeting/interests/nln?cursor=1&limit=999"
},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"nln": {
"id": "NLN_1000",
"name": "Apparel Buyers",
"path": "/Apparel Buyers",
"source": "Nielsen"
}
},
{
"sub_request_status": "SUCCESS",
"nln": {
"id": "NLN_10000",
"name": "Pet Product Buyers",
"path": "/Pet Product Buyers",
"source": "Nielsen"
}
},
{
"sub_request_status": "SUCCESS",
"nln": {
"id": "NLN_10001",
"name": "Pet Store Buyers",
"parent_id": "NLN_10000",
"path": "/Pet Product Buyers/Pet Store Buyers",
"source": "NBI"
}
}
]
}
This endpoint retrieves the list of Nielsen interest targeting options. The response is paginated and contains a link to the next page of the response. To fetch all categories please keep issuing a GET request to next_link contained in the paging parameter in the response, until paging returns nothing.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/interests/nln
Location
Location targeting allows an advertiser to target users based on their location.
Location - Categories
Get Location Categories Targeting Options
curl "https://adsapi.snapchat.com/v1/targeting/location/categories_loi"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
Response:
{
"request_status": "SUCCESS",
"request_id": "5a01027200ff0e853c41a9d4810001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d33356139343261632d6c6f632d6c6f6900010106",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"categories_loi": {
"id": "LOI_1000",
"name": "Arts & Entertainment",
"path":"/Arts & Entertainment"
}
},
{
"sub_request_status": "SUCCESS",
"categories_loi": {
"id": "LOI_1001",
"name": "Comedy Clubs",
"parent_id": "LOI_1000",
"path":"/Arts & Entertainment/Comedy Clubs"
}
},
{
"sub_request_status": "SUCCESS",
"categories_loi": {
"id": "LOI_1002",
"name": "Galleries & Museums",
"parent_id": "LOI_1000",
"path":"/Arts & Entertainment/Galleries & Museums"
}
},
{
"sub_request_status": "SUCCESS",
"categories_loi": {
"id": "LOI_1003",
"name": "Movie Theaters",
"parent_id": "LOI_1000",
"path":"/Arts & Entertainment/Movie Theaters"
}
},
... // etc
]
}
This endpoint retrieves the list of location categories.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/location/categories_loi
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
proximity | Proximity to selected location categories | R | |
proximity_unit | Unit to be used for radius | R | METERS (default), KILOMETERS, FEET, MILES |
Location - Point Radius
"targeting": {
"regulated_content": "false",
"demographics": [
{
"age_groups": [
"21-24"
]
}
],
"geos": [
{
"country_code": "us"
}
],
"locations": [
{
"circles": [
{
"latitude": 47.612447,
"longitude": -122.336751,
"radius": 500
},
{
"latitude": 47.617102,
"longitude": -122.203961,
"radius": 50,
"unit": "KILOMETERS"
}
],
"operation": "INCLUDE"
}
]
}
Using point radius targeting advertisers can pass in lists of latitude, longitude, and radius “circles” for location targeting. You can add up to 500 circles in the targeting spec.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
latitude | Latitude in decimal degrees | R | |
longitude | Longitude in decimal degrees | R | |
radius | Radius in meters (minimum 96 meters and maximum 100000 meters) | R | |
unit | Unit to be used for radius | O | METERS (default), KILOMETERS, FEET, MILES |
Targeting Specs - Greater than 500 rows
Any Ad Squad that contains more than 500 targeting criteria will have its targeting specifications broken out into a separate sub resource called targeting_specs and will be replaced by a property called separated_types. Any further updates or reads to the targeting spec will need to be performed on the new targeting_spec sub resource and not in the Ad Squad resource. This new resource is also described below.
Please note that before the deprecation date, you can use the below query parameter to test and build against the changes. targeting_spec_response_scope=AD_SQUAD_ONLY
Create Ad Squad
The create API call remains mostly the same, except if it contains more than 500 targeting criteria, in which case the targeting will be broken out into a new targeting sub resource. The response will contain the new separated_types attribute, indicating that this breakout has been performed.
HTTP Request
POST https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{
"adsquads": [
{
"name": "Badger Supplies 2000 US Postcode Targeting",
"status": "ACTIVE",
"campaign_id": "51334977-d500-4f6a-bb5c-e6d4c2e00067",
"type": "SNAP_ADS",
"targeting":
{
"regulated_content": false,
"geos": [
{
"country_code": "us",
"postal_code": [
"20001"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"20009"
],
"operation": "INCLUDE"
},
...
},
{
"country_code": "us",
"postal_code": [
"08903"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"08906"
],
"operation": "INCLUDE"
}
],
"devices": [
{}],
"auto_expansion_options":
{
"interest_expansion_option":
{
"enabled": true
},
"custom_audience_expansion_option":
{
"enabled": true
}
}
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-09-16T11:22:31.894Z",
"optimization_goal": "SWIPES",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD"
}
]
}' \
"https://adsapi.snapchat.com/v1/campaigns/51334977-d500-4f6a-bb5c-e6d4c2e00067/adsquads"
The above command returns JSON structured like this:
Response:
{
"request_status": "SUCCESS",
"request_id": "616edbf700ff0cbfe2f0d990390001737e7465616d6b6f363139000161646d616e616765722d6170693a6b702d726176360001010f",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad":
{
"id": "a4a40858-c794-432b-aaca-71314e019a86",
"updated_at": "2021-10-19T14:53:56.773Z",
"created_at": "2021-10-19T14:53:56.270Z",
"effective_status": "PAUSED",
"name": "Badger Supplies 2000 US Postcode Targeting",
"status": "ACTIVE",
"campaign_id": "51334977-d500-4f6a-bb5c-e6d4c2e00067",
"type": "SNAP_ADS",
"targeting":
{
"regulated_content": false,
"separated_types": [
"GEO"
],
"devices": [
{}],
"auto_expansion_options":
{
"interest_expansion_option":
{
"enabled": true
},
"custom_audience_expansion_option":
{
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement": "SNAP_ADS",
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-09-16T11:22:31.894Z",
"optimization_goal": "SWIPES",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED",
"delivery_status": [
"INVALID_EFFECTIVE_INVALID",
"INVALID_NOT_EFFECTIVE_ACTIVE"
],
"skadnetwork_properties":
{
"status": "NEVER_ENROLLED"
}
}
}]
}
GET Ad Squad:
The GET endpoint remains the same, except in the case that there are more than 500 targeting criteria, in which case it will not return any targeting spec in the response and will return a separated_types property. To retrieve the targeting spec you must call the targeting sub resource.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
"https://adsapi.snapchat.com/v1/adsquads/a4a40858-c794-432b-aaca-71314e019a86?return_placement_v2=true"
The above command returns JSON structured like this:
Response:
{
"request_status": "SUCCESS",
"request_id": "616ee96a00ff06b0b1557b48670001737e7465616d6b6f363139000161646d616e616765722d6170693a6b702d7261763600010131",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad":
{
"id": "a4a40858-c794-432b-aaca-71314e019a86",
"updated_at": "2021-10-19T14:53:56.773Z",
"created_at": "2021-10-19T14:53:56.270Z",
"effective_status": "PAUSED",
"name": "Badger Supplies US Post Code Targeting II",
"status": "ACTIVE",
"campaign_id": "51334977-d500-4f6a-bb5c-e6d4c2e00067",
"type": "SNAP_ADS",
"targeting":
{
"regulated_content": false,
"separated_types": [
"GEO"
],
"devices": [
{}],
"auto_expansion_options":
{
"interest_expansion_option":
{
"enabled": true
},
"custom_audience_expansion_option":
{
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement_v2":
{
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"INTERSTITIAL_USER",
"INTERSTITIAL_CONTENT",
"INSTREAM"
]
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-09-16T11:22:31.894Z",
"optimization_goal": "SWIPES",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED",
"delivery_status": [
"INVALID_EFFECTIVE_INVALID",
"INVALID_NOT_EFFECTIVE_ACTIVE"
],
"skadnetwork_properties":
{
"status": "NEVER_ENROLLED"
}
}
}]
}
Update Ad Squad
The update will work the same, except in the situation where there are more than 500 targeting criteria. In this case you can no longer use the Ad Squad endpoint to update the targeting criteria and doing so will return an error. You may continue to use the Ad Squad endpoint to update other fields. To update the targeting criteria, you must use the targeting resource.
HTTP Request
PUT https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{
"adsquads": [
{
"id": "a4a40858-c794-432b-aaca-71314e019a86",
"updated_at": "2021-10-19T14:53:56.773Z",
"created_at": "2021-10-19T14:53:56.270Z",
"effective_status": "PAUSED",
"name": "Badger Supplies US Postcode Targeting",
"status": "ACTIVE",
"campaign_id": "51334977-d500-4f6a-bb5c-e6d4c2e00067",
"type": "SNAP_ADS",
"targeting":
{
"regulated_content": false,
"geos": [
{
"country_code": "us",
"postal_code": [
"20001"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"20009"
],
"operation": "INCLUDE"
},
...
{
"country_code": "us",
"postal_code": [
"08903"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"08906"
],
"operation": "INCLUDE"
},
{
"country_code": "ca",
"operation": "INCLUDE"
}
],
"devices": [
{}],
"auto_expansion_options":
{
"interest_expansion_option":
{
"enabled": true
},
"custom_audience_expansion_option":
{
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement_v2":
{
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"INTERSTITIAL_USER",
"INTERSTITIAL_CONTENT",
"INSTREAM"
]
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-09-16T11:22:31.894Z",
"optimization_goal": "SWIPES"
}]
}' \
"https://adsapi.snapchat.com/v1/campaigns/51334977-d500-4f6a-bb5c-e6d4c2e00067/adsquads"
The above command returns JSON structured like this:
Response:
{
"request_status": "SUCCESS",
"request_id": "617035ff0000ff07f6b7ff00b0ef310001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d38393135316663392d312d3438382d3000010148",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad":
{
"id": "a4a40858-c794-432b-aaca-71314e019a86",
"updated_at": "2021-10-20T15:30:16.952Z",
"created_at": "2021-10-19T14:53:56.270Z",
"effective_status": "PAUSED",
"name": "Badger Supplies US Postcode Targeting",
"status": "ACTIVE",
"campaign_id": "51334977-d500-4f6a-bb5c-e6d4c2e00067",
"type": "SNAP_ADS",
"targeting":
{
"regulated_content": false,
"separated_types": [
"GEO"
],
"devices": [
{}],
"auto_expansion_options":
{
"interest_expansion_option":
{
"enabled": true
},
"custom_audience_expansion_option":
{
"enabled": true
}
}
},
"targeting_reach_status": "VALID",
"placement_v2":
{
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"INTERSTITIAL_USER",
"INTERSTITIAL_CONTENT",
"INSTREAM"
]
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-09-16T11:22:31.894Z",
"optimization_goal": "SWIPES",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED",
"delivery_status": [
"INVALID_EFFECTIVE_INVALID",
"INVALID_NOT_EFFECTIVE_ACTIVE"
],
"skadnetwork_properties":
{
"status": "NEVER_ENROLLED"
},
"delivery_properties_version": 1634743816283
}
}]
}
GET all targeting specs under Ad Squad
This request retrieves all Targeting Specs under the specified Ad Squad, currently there can only be one Targeting Spec for an Ad Squad. If the response consists of an empty array it means the Ad Squad does not have an associated Targeting Spec.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/targeting_specs
URL Parameters
Attribute | Description |
---|---|
ad_squad_id | The ID of the Ad Squad under which the Targeting Spec is being created |
curl -X GET \
-H "Authorization: Bearer meowmeowmeow" \
"https://adsapi.snapchat.com/v1/adsquads/a4a40858-c794-432b-aaca-71314e019a86/targeting_specs"
The above command returns JSON structured like this:
Response:
{
"request_status": "SUCCESS",
"request_id": "6170522400ff065868237e7ebf0001737e7465616d6b6f363139000161646d616e616765722d6170693a776e75636b6f6c73746573740001012f",
"paging":
{},
"targeting_specs": [
{
"sub_request_status": "SUCCESS",
"targeting_spec":
{
"id": "7ba7b1f3-2eb7-471d-a143-dd9c4b60cda7",
"updated_at": "2021-10-20T15:30:16.704Z",
"created_at": "2021-10-19T14:53:57.161Z",
"container_kind": "AdSquads",
"container_id": "a4a40858-c794-432b-aaca-71314e019a86",
"type": "GEO",
"geos": [
{
"country_code": "us",
"postal_code": [
"20001"
],
"operation": "EXCLUDE"
},
{
"country_code": "us",
"postal_code": [
"20009"
],
"operation": "EXCLUDE"
},
...
{
"country_code": "us",
"postal_code": [
"08903"
],
"operation": "INCLUDE"
},
{
"country_code": "ca",
"postal_code": [
"08906"
],
"operation": "INCLUDE"
}
]
}
}]
}
GET a specific targeting spec
This request retrieves a specific Targeting Spec.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting_specs/{targeting_spec_id}
URL Parameters
Attribute | Description |
---|---|
targeting_spec_id | The ID of the Targeting Spec you wish to retrieve |
curl -X GET \
-H "Authorization: Bearer meowmeowmeow" \
"https://adsapi.snapchat.com/v1/targeting_specs/{targeting_spec_id}"
The above command returns JSON structured like this:
Response:
{
"request_status": "SUCCESS",
"request_id": "617069bf00ff0a62999d01b8160001737e7465616d6b6f363139000161646d616e616765722d6170693a776e75636b6f6c737465737400010128",
"targeting_specs": [
{
"sub_request_status": "SUCCESS",
"targeting_spec":
{
"id": "7ba7b1f3-2eb7-471d-a143-dd9c4b60cda7",
"updated_at": "2021-10-20T15:30:16.704Z",
"created_at": "2021-10-19T14:53:57.161Z",
"container_kind": "AdSquads",
"container_id": "a4a40858-c794-432b-aaca-71314e019a86",
"type": "GEO",
"geos": [
{
"country_code": "us",
"postal_code": [
"20001"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"20009"
],
"operation": "INCLUDE"
},
...
{
"country_code": "us",
"postal_code": [
"08903"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"08906"
],
"operation": "INCLUDE"
},
{
"country_code": "ca",
"operation": "INCLUDE"
}
]
}
}]
}
Updating a Targeting Spec
This request will update a Targeting Spec, note that the Targeting Spec has a maximum limit of 4,000 targeting criteria.
HTTP Request
PUT https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/targeting_specs
URL Parameters
Attribute | Description |
---|---|
ad_squad_id | The ID of the Ad Squad under which the Targeting Spec is being created |
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
id | The ID of the Targeting Spec you wish to update | R | |
type | The type of targeting, currently only GEO | R | GEO |
geos | An array containing a valid targeting spec for geos | R |
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{
"targeting_specs": [
{
"id": "7ba7b1f3-2eb7-471d-a143-dd9c4b60cda7",
"type": "GEO",
"geos": [
{
"country_code": "us",
"postal_code": [
"20001"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"20009"
],
"operation": "INCLUDE"
},
...
{
"country_code": "us",
"postal_code": [
"08903"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"08906"
],
"operation": "INCLUDE"
},
{
"country_code": "ca",
"operation": "INCLUDE"
},
{
"country_code": "ie",
"operation": "INCLUDE"
}
]
}]
}' \
"https://adsapi.snapchat.com/v1/adsquads/a4a40858-c794-432b-aaca-71314e019a86/targeting_specs"
The above command returns JSON structured like this:
Response:
{
"request_status": "SUCCESS",
"request_id": "61706cea00ff0bc60d6308beaf0001737e7465616d6b6f363139000161646d616e616765722d6170693a776e75636b6f6c737465737400010140",
"targeting_specs": [
{
"sub_request_status": "SUCCESS",
"targeting_spec":
{
"id": "7ba7b1f3-2eb7-471d-a143-dd9c4b60cda7",
"updated_at": "2021-10-20T19:24:41.668Z",
"created_at": "2021-10-19T14:53:57.161Z",
"container_kind": "AdSquads",
"container_id": "a4a40858-c794-432b-aaca-71314e019a86",
"type": "GEO",
"geos": [
{
"country_code": "us",
"postal_code": [
"20001"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"20009"
],
"operation": "INCLUDE"
},
...
{
"country_code": "us",
"postal_code": [
"08903"
],
"operation": "INCLUDE"
},
{
"country_code": "us",
"postal_code": [
"08906"
],
"operation": "INCLUDE"
},
{
"country_code": "ca",
"operation": "INCLUDE"
},
{
"country_code": "ie",
"operation": "INCLUDE"
}
]
}
}]
}
Customer Lists
Customer Lists allow an advertiser to use first-party data to create an Audience Segment. The segment can be used to target or exclude a specific group of users.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
description | Audience Segment Description | O | |
name | Audience Segment name | R | 375 characters max |
retention_in_days | # of days to retain audience members | R | (Default retention is lifetime represented as 9999) |
source_type | Data source type | R | FIRST_PARTY, ENGAGEMENT, PIXEL, MOBILE, FOOT_TRAFFIC_INSIGHTS |
approximate_number_users | Approximate # of users in the segment | Read Only | |
status | Status of the segment | Read Only | ACTIVE |
upload_status | Upload status of the segment | Read Only | NO_UPLOAD, PROCESSING, COMPLETE |
targetable_status | Status of whether this segment can be targeted | Read Only | NOT_READY, TOO_FEW_USERS, READY |
Create an Audience Segment
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"segments": [{"name": "all the sams in the world", "description": "all the sams in the world", "source_type": "FIRST_PARTY", "retention_in_days": 180, "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74"}]}' \
"https://adsapi.snapchat.com/v1/adaccounts/{ad_acount_id}/segments"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57ae54d800ff0a4a5232b1a7210001737e616473617069736300016275696c642d35396264653638322d312d31312d37000100",
"segments": [
{
"sub_request_status": "success",
"segment": {
"updated_at": "2016-08-12T22:59:42.452Z",
"created_at": "2016-08-12T22:59:42.405Z",
"name": "all the sams in the world",
"id": "5677923948298240",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"description": "all the sams in the world",
"status": "PENDING",
"source_type": "FIRST_PARTY",
"retention_in_days": 180,
"approximate_number_users": 0
}
}
]
}
This endpoint will create a Customer List segment within a specified ad account.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/segments
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Segment Status
Upload Status | Description |
---|---|
NO_UPLOAD | Segment has been created but no uploads have been received yet |
PROCESSING | Not all uploads to this segment have been processed so audience size might change |
COMPLETE | All received uploads have been processed and matched. Audience size reflects segment size |
Targetable Status | Description |
---|---|
NOT_READY | This segment won’t work when used in targeting |
TOO_FEW_USERS | This segment doesn’t have enough users to target |
READY | Segment is ready to target |
Get All Audience Segments
curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/segments"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57ae554a00ff0487459c8ac85c0001737e616473617069736300016275696c642d34363138393265642d312d31312d3200010103",
"segments": [
{
"sub_request_status": "success",
"segment": {
"updated_at": "2016-08-12T21:11:01.325Z",
"created_at": "2016-08-12T21:11:01.196Z",
"name": "super duper sam 2",
"id": "5689640350646272",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"description": "all the sams in the world",
"status": "PENDING",
"source_type": "FIRST_PARTY",
"retention_in_days": 180,
"approximate_number_users": 0
}
},
{
"sub_request_status": "success",
"segment": {
"updated_at": "2016-08-12T20:58:16.098Z",
"created_at": "2016-08-12T20:58:16.036Z",
"name": "super duper sam",
"id": "5715031928864768",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"description": "all the sams in the world",
"status": "PENDING",
"source_type": "FIRST_PARTY",
"retention_in_days": 180,
"approximate_number_users": 0
}
}
]
}
This endpoint retrieves all Customer List segments within a specified ad account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/segments
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Get a specific Audience Segment
curl "https://adsapi.snapchat.com/v1/segments/{segment_id}"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b3116c800ff0cfbb4758de4670001737e616473617069736300016275696c642d32636336303266382d312d3137382d300001015d",
"segments": [
{
"sub_request_status": "SUCCESS",
"segment": {
"id": "5701023945457664",
"updated_at": "2018-06-25T02:13:52.956Z",
"created_at": "2018-03-09T00:57:57.462Z",
"name": "Lookalike - Balance - hashed_emails_old_groupB",
"ad_account_id": "3f539865-c001-4f5e-bd31-5ae129a4550a",
"status": "ACTIVE",
"targetable_status": "READY",
"upload_status": "COMPLETE",
"source_type": "LOOKALIKE",
"retention_in_days": 180,
"approximate_number_users": 11487000,
"creation_spec": {
"seed_segment_id": "5749764677173248",
"country": "US",
"type": "BALANCE"
}
}
}
]
}
This endpoint retrieves the Snap Audience Segment with the corresponding segment id.
HTTP Request
GET https://adsapi.snapchat.com/v1/segments/{segment_id}
Parameters
Parameter | Default | Description |
---|---|---|
segment_id | Segment ID |
Update an Audience Segment
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"segments":[{"id":"5603670370513719","name":"Honey Bear Segment 2019","organization_id":"1fdeefec-f502-4ca8-9a84-6411e0a51052","description":"A list of Honey bear lovers across the globe","retention_in_days":"60"}]}'
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/segments
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5dc3096800ff0c266ebe6eeaac0001737e616473617069736300016275696c642d65653836646631392d312d3330322d300001013a",
"segments": [
{
"sub_request_status": "SUCCESS",
"segment": {
"id": "5603670370513719",
"updated_at": "2019-11-06T17:56:57.053Z",
"created_at": "2019-03-28T14:47:17.956Z",
"name": "Honey Bear Segment 2019",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
"organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51052",
"description": "A list of Honey bear lovers across the globe",
"status": "PAUSED",
"targetable_status": "TOO_FEW_USERS",
"upload_status": "COMPLETE",
"source_type": "FIRST_PARTY",
"retention_in_days": 60,
"approximate_number_users": 500000,
"visible_to": [
"AdAccountEntity_22225ba6-7559-4000-9663-bace8adff5f1"
]
}
}
]
}
This endpoint updates the Snap Audience Segment.
Attributes that can be updated
Attribute | Required |
---|---|
name | R |
description | O |
retention_in_days | R |
HTTP Request
PUT https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/segments
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Adding Users
Users can be added to a segment at any time. The API supports matching via email, phone number or mobile identifier.
This endpoint will add users to the specified Customer List segment using either a single key/identifier per user. We do not accept multiple type of schemas in one request, you need to pass only one schema type with the request, but this needs to happen via a LIST
Identifiers should be grouped in batches of a maximum of 100,000 identifiers/request.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
id^ | Segment ID | O | |
schema | List of one type of Schema | R | EMAIL_SHA256, MOBILE_AD_ID_SHA256, PHONE_SHA256 |
data | List of hashed identifiers | R | max 100,000 identifiers/request |
^This field is here for legacy reasons and should be skipped for new implmentations
HTTP Request
POST https://adsapi.snapchat.com/v1/segments/{segment_id}/users
Parameters
Parameter | Default | Description |
---|---|---|
segment_id | Segment ID |
Normalizing & Hashing
Each raw identifier (plain text email or mobile identifier) must be normalized before being hashed.
Normalizing Identifiers
- Normalize email addresses by trimming leading and trailing whitespace and converting all characters to lowercase before hashing
- Normalize mobile advertiser id by using all lowercase. Do not remove hyphens.
- Normalize phone numbers by including the country code, remove any double 0 in front of the country code, if the number itself begins with a 0 this should be removed. Also exclude any non-numeric characters such as whitespace, parentheses, ‘+’, or ‘-’.
Phone normalization example | Before normalization | After normalization | Action |
---|---|---|---|
US phone number example | 001-234-567-8910 | 12345678910 | 00 of country code and ‘-’ characters removed |
UK phone number example | +44 844 412 4653 | 448444124653 | Initial 0 of number, whitespaces and ‘+’ character removed |
Hashing Identifiers
Hash raw identifiers with lowercase hex SHA256 format.
Adding Users (Single-Key)
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"users":[{ "schema":["EMAIL_SHA256"],"data":[["c3a75685a45a565954512a7f006b691b5e06c0efe6ac28bd5c09e84bbe022b55"],["5b5fbfe6a42915ca4d0f11620e76abd1a4ac621bcca95395ce3b6b11ec01bef6"]]}]}' \
"https://adsapi.snapchat.com/v1/segments/{segment_id}/users"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "57c4d34700ff0d538b8ba40ed90001737e7465616d6b6f363139000173616d2d68616f6d696e672d757365722d746573740001010c",
"users": [
{
"sub_request_status": "SUCCESS",
"user": {
"number_uploaded_users": 2
}
}
]
}
This example uses a single key/identifier per user.
Removing Users
Users can also be removed from the segment at any time. The API supports matching via email, phone number or mobile identifier. You can send a maximum of 100,000 identifiers / request.
This endpoint will remove users from the specified Customer List segment using a single key/identifier per user. We do not accept multiple type of schemas in one request, you need to pass only one schema type with the request , but this needs to happen via a LIST.
Identifiers should be grouped in batches of a maximum of 100,000 identifiers/request.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
id | Segment ID | R | |
schema | List of one type of Schema | R | EMAIL_SHA256, MOBILE_AD_ID_SHA256, PHONE_SHA256 |
data | List of hashed identifiers | R | max 100,000 identifiers/request |
HTTP Request
DELETE https://adsapi.snapchat.com/v1/segments/{segment_id}/users
Parameters
Parameter | Default | Description |
---|---|---|
segment_id | Segment ID |
Removing Users (Single-Key)
curl -X DELETE \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"users":[{"id": "5132209967071232", "schema":["EMAIL_SHA256"],"data":[["c3a75685a45a565954512a7f006b691b5e06c0efe6ac28bd5c09e84bbe022b55"],["5b5fbfe6a42915ca4d0f11620e76abd1a4ac621bcca95395ce3b6b11ec01bef6"]]}]}' \
"https://adsapi.snapchat.com/v1/segments/{segment_id}/users"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "57c4d34700ff0d538b8ba40ed90001737e7465616d6b6f363139000173616d2d68616f6d696e672d757365722d746573740001010c",
"users": [
{
"sub_request_status": "SUCCESS",
"user": {
"number_uploaded_users": 2
}
}
]
}
This example uses a single key/identifier per user.
Remove All Users from a Segment
This endpoint allows you to remove all the users from a specified Customer List segment
HTTP Request
DELETE https://adsapi.snapchat.com/v1/segments/{segment_id}/all_users
Parameters
Parameter | Default | Description |
---|---|---|
segment_id | Segment ID |
Remove All Users
curl -X DELETE \
-H "Authorization: Bearer meowmeowmeow" \
"https://adsapi.snapchat.com/v1/segments/{segment_id}/all_users"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "58af318900ff0cb66aa3a103dd0001737e616473617069736300016275696c642d61666139346564352d312d34342d3000010109",
"segments": [
{
"sub_request_status": "SUCCESS",
"segment": {
"id":"5769345128988888",
"updated_at":"2017-02-23T19:01:30.080Z",
"created_at":"2017-02-23T18:34:48.900Z",
"name":"super duper sam",
"ad_account_id":"8adc3db7-8148-4fbf-999c-8d1111111d11",
"description":"all the sams in the world",
"status":"ACTIVE",
"source_type":"FIRST_PARTY",
"retention_in_days":180,
"approximate_number_users":0
}
}
]
}
Delete an Audience Segment
curl -X DELETE \
-H "Authorization: Bearer meowmeowmeow" \
"https://adsapi.snapchat.com/v1/segments/{segment_id}"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b994e4900ff02dce52463d1020001737e616473617069736300016275696c642d33346634346232622d312d3230302d32000100",
"segments": []
}
This endpoint will delete the Audience Segment with the corresponding segment id.
HTTP Request
DELETE https://adsapi.snapchat.com/v1/segments/{segment_id}
Parameters
Parameter | Default | Description |
---|---|---|
segment_id | Segment ID |
Customer Lists - Lookalikes
A Lookalike segment can be created from a first-party seed Customer List segment. The segment can be used to target or exclude a specific group of users that “behave like” the seed audience segment.
If the original seed Segment has new identfiers added to it, the Lookalike segment will also be updated with new users.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
creation_spec | Lookalike Creation Spec dictionary | R | (see below) |
description | Audience Segment Description | O | |
name | Audience Segment name | R | |
retention_in_days | # of days to retain audience members | R | (Max 180) |
source_type | Data source type | R | LOOKALIKE |
Creation Spec Details
Attribute | Description | Required | Possible Values |
---|---|---|---|
seed_segment_id | Seed Audience Segment ID | R | |
type | The type of Lookalike to be created | O | BALANCE (default), SIMILARITY, REACH |
countries | List of ISO-2 Country Code | R | [“UK”, “US”] OR [“US”] etc |
country [Deprecated] | ISO-2 Country Code | R |
Create an Lookalike Segment
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"segments": [{"name": "lookalikes of all the sams in the world", "description": "similar to all the sams in the world", "source_type": "LOOKALIKE", "retention_in_days": 180, "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "creation_spec":{"seed_segment_id": "5677923948298240", "country": "US", "type": "REACH"}}]}' \
"https://adsapi.snapchat.com/v1/adaccounts/{ad_acount_id}/segments"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "57e18036000733c0f1abd670",
"segments": [
{
"sub_request_status": "SUCCESS",
"segment": {
"id": "5652536396611584",
"updated_at": "2016-09-20T11:30:15.448-07:00",
"created_at": "2016-09-20T11:30:15.429-07:00",
"name": "lookalikes of all the sams in the world",
"ad_account_id": "d47d2516-4f1f-46f0-a63c-31a46804c3aa",
"description": "similar to all the sams in the world",
"status": "ACTIVE",
"source_type": "LOOKALIKE",
"retention_in_days": 180,
"approximate_number_users": 0,
"creation_spec": {
"seed_segment_id": "5677923948298240",
"country": "US"
"type": "REACH"
}
}
}
]
}
This endpoint will create a Customer List Lookalike Segment within a specified ad account.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/segments
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Example Targeting Specs
Targeting Spec Examples for an Ad Squad
Example 1
United States, Male+Female, All Age Ranges
You can target both Male and Female by leaving out GENDER from the targeting spec.
{
"geos": [{
"country_code": "us"
}]
}
Example 2
United States, Male, Age Groups 21-34
{
"geos": [{
"country_code": "us"
}],
"demographics": [{
"age_groups": [
"21-24",
"25-34"
],
"gender": "MALE"
}]
}
Example 3
Canada, Female, 13-20, iOS
{
"demographics": [{
"min_age": 13,
"max_age": 20,
"gender": "FEMALE"
}],
"geos": [{
"country_code": "ca"
}],
"devices": [{
"os_type": "iOS"
}]
}
Example 4
UK, Male+Female, Age 25, WIFI Only
{
"demographics": [{
"min_age": 25,
"max_age": 25
}],
"geos": [{
"country_code": "uk"
}],
"devices": [{
"connection_type": "WIFI"
}]
}
Example 5
United States - All States Except Arizona or Texas, M+F, All Ages
{
"geos": [{
"country_code": "us",
"operation": "INCLUDE"
},
{
"country_code": "us",
"region_id": ["3"],
"operation": "EXCLUDE"
},
{
"country_code": "us",
"region_id": ["44"],
"operation": "EXCLUDE"
}]
}
Example 6
United States, Female, 18-34, “Fashion & Style Gurus” OR “Film & TV Fans”
{
"demographics": [{
"gender": "FEMALE",
"age_groups": [
"18-20",
"21-24",
"25-34"
]
}],
"interests": [{
"category_id": ["SLC_7", "SLC_8"]
}],
"geos": [{
"country_code": "us"
}]
}
Example 7
United States, All genders/ages, “Comedy Fans”
{
"interests": [{
"category_id": ["SLC_36"]
}],
"geos": [{
"country_code": "us"
}]
}
Example 8
United States, Male, 18-20, member of Customer List segment ID “12345”
{
"demographics": [{
"gender": "MALE",
"age_groups": [
"18-20"
]
}],
"geos": [{
"country_code": "us"
}],
"segments": [{
"segment_id": ["12345"]
}]
}
Example 9
United States, Male, 18-20, NOT a member of Customer List segment ID “98765”
{
"demographics": [{
"gender": "MALE",
"age_groups": [
"18-20"
]
}],
"geos": [{
"country_code": "us"
}],
"segments": [{
"segment_id": ["98765"],
"operation": "EXCLUDE"
}]
}
Example 10
United States, AT&T
{
"geos": [{
"country_code": "us"
}],
"devices": [{
"carrier_id": ["US_ATT"]
}]
}
Example 11
United States, 21-24, (College Graduates OR Married People), Apparel Shoppers
{
"regulated_content": "false",
"demographics": [{
"age_groups": [
"21-24"
],
"advanced_demographics": [
"DLXD_100",
"DLXD_300"
]
}],
"geos": [{
"country_code": "us"
}],
"interests": [{
"category_id": ["DLXS_1"]
}]
}
Example 12
United States, metros New York or Los Angeles only
{
"geos": [{
"country_code": "us",
"metro_id": ["501", "803"]
}]
}
Example 13
USA, Female, Spanish speaking, 13-17, iOS version 10.3.2
{
"demographics": [{
"age_groups": [
"13-17"
],
"gender": "FEMALE",
"languages": ["es"]
}],
"geos": [{
"country_code": "us"
}],
"devices": [{
"os_type": "iOS",
"os_version_min": "9.0",
"os_version_max": "10.3.2"
}]
}
Example 14
Zipcode Targeting
{
"geos": [{
"country_code": "us",
"postal_code": ["90291", "90026"]
}]
}
Example 15
Device Make: All iPhone 7 plus and iPhone 6s Plus users
{
"devices": [{
"marketing_name": ["Apple/iPhone 7 Plus/", "Apple/iPhone 6s Plus/"]
}]
}
Example 16
Location Categories: Targeting Sports Arenas, Fitness Centers
{
"locations": [
{
"location_type": [
"LOI_15004", // Sports Stadiums and Arenas
"LOI_15002" // Gyms and Fitness Centers
],
,
"proximity_unit": "MILES", // Proximity in miles
"proximity": 1
}
]
}
Example 17
Location Point Radius: Targeting 500 meter radius around Nordstrom locations in Seattle/Bellevue
{
"locations": [
{
"circles": [
{
"latitude": 47.612447,
"longitude": -122.336751,
"radius": 500
},
{
"latitude": 47.617102,
"longitude": -122.203961,
"radius": 50,
"unit": "KILOMETERS"
}
],
"operation": "INCLUDE"
}
]
}
Example 18
Multi-country targeting: Targeting the US and Canada
{
"geos": [
{
"country_code": "us",
"operation": "INCLUDE"
},
{
"country_code": "ca",
"operation": "INCLUDE"
}
]
}
Example 19
Snap Lifestyle Category inclusion of SLC_1, SLC_124 and exclusion of SLC_2
{
"interests": [
{
"category_id": [
"SLC_1",
"SLC_124"
],
"operation": "INCLUDE"
},
{
"category_id": [
"SLC_2"
],
"operation": "EXCLUDE"
}
]
}
Example 20
App Install State targeting using a Snap App ID
{
"app_install_states": [
{
"state": "INSTALLED",
"snap_app_ids": [
"85a0bfd4-2f0c-4797-bceb-b0a8375c5828"
]
}
]
}
App Install State targeting is required for Ad Squads that use the optimization goal APP_REENGAGE_OPEN or APP_REENGAGE_PURCHASE.
Example 21
App Install State targeting - Prospecting Product Audience
App Install State targeting in use with Dynamic Product Ads of the type APP_INSTALL
{
"product_audiences": [
{
"product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
"event_type": "PAGE_VIEW",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
},
{
"product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
"event_type": "ADD_CART",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
},
{
"product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
"event_type": "PURCHASE",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
},
{
"product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
"event_type": "VIEW_CONTENT",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
}
],
"app_install_states": [
{
"state": "NOT_INSTALLED",
"snap_app_ids": [
"2e1154ae-35fc-4b9e-8c40-4816dfb42038"
]
}
]
}
Example 22
App Install State targeting - Retargeting Product Audience
App Install State targeting in use with Dynamic Product Ads of the type DEEP_LINK
{
"product_audiences": [
{
"product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
"event_type": "PAGE_VIEW",
"retention_seconds": 1209600,
"operation": "INCLUDE"
},
{
"product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
"event_type": "ADD_CART",
"retention_seconds": 1209600,
"operation": "INCLUDE"
},
{
"product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
"event_type": "VIEW_CONTENT",
"retention_seconds": 1209600,
"operation": "INCLUDE"
},
{
"product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
"event_type": "PURCHASE",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
}
],
"app_install_states": [
{
"state": "INSTALLED",
"snap_app_ids": [
"85a0bfd4-2f0c-4797-bceb-b0a8375c5828"
]
}
]
}
Example 23
Visitation Audience Segments: Targeting users in the US who visited an ice cream shop
In this example, we target users who have visited an ice cream shop by using the First Party Visitation Segment, “VAC_97”, which contains users who have visited an ice cream shop.
{
"geos": [
{
"country_code": "us"
}
],
"interests": [
{
"category_id": [
"VAC_97"
],
"operation": "INCLUDE"
}
]
}
Example 24
Household income targeting: Targeting users in the US who have a household income of $200,000 or more
Here, we target users by using the advanced_demographics audience “DMG_4”, which is a collection of users who have a household income of $200,000 or more.
{
"demographics": [
{
"advanced_demographics": [
"DMG_4"
]
}
],
"geos": [
{
"country_code": "us"
}
]
}
Audience Insights
Get Audience Insights
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/targeting_insights
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | The Ad Account ID to be used |
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
base_spec | Valid targeting spec | R | Any valid spec described here |
targeting_spec | Valid targeting spec | R | Any valid spec described here |
Query Parameters
Parameter | Description | Required | Possible Values |
---|---|---|---|
dimension_category | The category to filter the output results | O | Can be one of: demo/geo/device/interest |
Example
curl -X POST \
-d '{"base_spec": {"interests": [{"category_id": ["SLC_36"]}],"geos": [{"country_code": "us"}]},"targeting_spec": {"interests": [{"category_id": ["SLC_37"]}],"geos": [{"country_code": "us"}]}}'\
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/139ee7a0-8225-4076-9048-4cb7d7b3a926/targeting_insights?dimension_category=demo
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b21985200ff0b57ca241c591c0001737e616473617069736300016275696c642d35336630363134382d312d3137352d3100010137",
"targeting_insights": {
"target_audience": {
"audience_size_minimum": "10500000",
"audience_size_maximum": "10800000"
},
"reference_audience": {
"audience_size_minimum": "1110000",
"audience_size_maximum": "1125000"
},
"categories": {
"demographics": {
"distribution": {
"age_groups": {
"key": "",
"insight": [
{
"value": "",
"count": 0,
"id": "35+",
"name": "35+",
"target_audience_percent": 10.3,
"reference_audience_percent": 11.9,
"target_index_to_reference": 0.9,
"metadata": {}
},
{
"value": "",
"count": 0,
"id": "18-20",
"name": "18-20",
"target_audience_percent": 21.2,
"reference_audience_percent": 16.9,
"target_index_to_reference": 1.3,
"metadata": {}
},
{
"value": "",
"count": 0,
"id": "21-24",
"name": "21-24",
"target_audience_percent": 17,
"reference_audience_percent": 20,
"target_index_to_reference": 0.8,
"metadata": {}
},
{
"value": "",
"count": 0,
"id": "13-17",
"name": "13-17",
"target_audience_percent": 30.6,
"reference_audience_percent": 18.9,
"target_index_to_reference": 1.6,
"metadata": {}
},
{
"value": "",
"count": 0,
"id": "25-34",
"name": "25-34",
"target_audience_percent": 20.9,
"reference_audience_percent": 32.3,
"target_index_to_reference": 0.6,
"metadata": {}
},
{
"value": "",
"count": 0,
"id": "UNKNOWN",
"name": "unknown",
"target_audience_percent": 0,
"reference_audience_percent": 0,
"target_index_to_reference": 0,
"metadata": {}
}
]
},
"gender": {
"key": "",
"insight": [
{
"value": "",
"count": 0,
"id": "MALE",
"name": "male",
"target_audience_percent": 46.4,
"reference_audience_percent": 55,
"target_index_to_reference": 0.8,
"metadata": {}
},
{
"value": "",
"count": 0,
"id": "GENDER_UNKNOWN",
"name": "gender_unknown",
"target_audience_percent": 0.2,
"reference_audience_percent": 0,
"target_index_to_reference": 0,
"metadata": {}
},
{
"value": "",
"count": 0,
"id": "FEMALE",
"name": "female",
"target_audience_percent": 53.4,
"reference_audience_percent": 45,
"target_index_to_reference": 1.2,
"metadata": {}
}
]
},
"languages": {
"key": "",
"insight": [
{
"value": "",
"count": 0,
"id": "AR",
"name": "ar",
"target_audience_percent": 0.1,
"reference_audience_percent": 0.2,
"target_index_to_reference": 0.7,
"metadata": {}
},
{
"value": "",
"count": 0,
"id": "FR",
"name": "fr",
"target_audience_percent": 0.2,
"reference_audience_percent": 0.1,
"target_index_to_reference": 1.4,
"metadata": {}
},
{
"value": "",
"count": 0,
"id": "ES",
"name": "es",
"target_audience_percent": 3.3,
"reference_audience_percent": 4.7,
"target_index_to_reference": 0.7,
"metadata": {}
},
{
"value": "",
"count": 0,
"id": "EN",
"name": "en",
"target_audience_percent": 99.1,
"reference_audience_percent": 98.6,
"target_index_to_reference": 1,
"metadata": {}
}
]
},
"advanced_demographics": {
"key": "",
"insight": [
{
"value": "",
"count": 0,
"id": "EXPD_307",
"name": "Household Income ($150,000-$174,999)",
"target_audience_percent": 2.9,
"reference_audience_percent": 3.4,
"target_index_to_reference": 0.9,
"metadata": {}
},
{
"value": "",
"count": 0,
"id": "DLXD_202",
"name": "HHI: 50k-75k",
"target_audience_percent": 17.7,
"reference_audience_percent": 18.7,
"target_index_to_reference": 0.9,
"metadata": {}
},
[[[snip]]]
{
"value": "",
"count": 0,
"id": "FEMALE_UNKNOWN",
"name": "female_unknown",
"target_audience_percent": 0,
"reference_audience_percent": 0,
"target_index_to_reference": 0,
"metadata": {
"gender": "FEMALE",
"age_groups": "unknown"
}
}
]
}
}
}
}
}
}
Audience Size
The Audience Size API returns an estimated range of potential reach for a given targeting spec.
By Ad Squad Spec
curl -X POST \
-H "Content-Type: application/json" \
-d '{"name": "App Install, United States, All Genders, 13-24", "status": "ACTIVE", "type": "SNAP_ADS", "targeting": {"geos": [{"country_code": "us"}],"demographics": [{"age_groups": ["13-17","18-20","21-24"]}]}, "placement": "CONTENT", "bid_micro": 6000000, "auto_bid": false, "daily_budget_micro": 50000000, "delivery_constraint": "DAILY_BUDGET", "optimization_goal": "APP_INSTALLS", "included_content_types": ["SCIENCE_TECHNOLOGY"]}' \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/d8c1e7e9-f119-4ed3-b77e-33b7eae13411/audience_size_v2
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5848847200ff049b9c18549b500001737e616473617069736300016275696c642d39323764616530622d312d32372d3300010124",
"audience_size": {
"audience_size_minimum": 15400000,
"audience_size_maximum": 21025000
}
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/audience_size_v2
URL Parameters
Parameter | Description |
---|---|
ad_account_id | Ad Account ID |
By Ad Squad ID
curl -X GET
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/c7b98952-4c6e-4f95-8cd1-cf0f17a77988/audience_size_v2
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "58474ee700ff017f0381aeb1a90001737e616473617069736300016275696c642d32356261313161372d312d32372d3100010120",
"audience_size": {
"ad_squad_id": "c7b98952-4c6e-4f95-8cd1-cf0f17a77988",
"audience_size_minimum": 16450000,
"audience_size_maximum": 19925000
}
}
This endpoint retrieves the estimated audience size for a specific ad squad.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/audience_size_v2
URL Parameters
Parameter | Description |
---|---|
ad_squad_id | Ad squad ID |
By Targeting Spec
curl -X POST \
-H "Content-Type: application/json" \
-d '{"geos":[{"country_code": "us"}], "demographics": [{"age_groups": ["21-24"]}]}' \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/d8c1e7e9-f119-4ed3-b77e-33b7eae13411/audience_size
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5848847200ff049b9c18549b500001737e616473617069736300016275696c642d39323764616530622d312d32372d3300010124",
"audience_size": {
"audience_size_minimum": 12400000,
"audience_size_maximum": 15025000
}
}
This endpoint retrieves the estimated audience size for a specific targeting spec, whether or not the targeting is in use by an ad squad.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/<ID>/audience_size
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the ad account |
Bid Estimate
The Bid Estimate API returns a bid estimate min and max for a given Ad Squad or Targeting Spec.
Bid Estimate is available for the following optimization goals.
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 |
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_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_PAGE_VIEW | Target Cost Per PAGE_VIEW 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 |
By Ad Squad
curl -X GET
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/c5995202-bfbc-45a0-9702-dd6841af52fe/bid_estimate
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57affee300ff0d91229fabb9710001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010110",
"bid_estimate": {
"ad_squad_id":"c5995202-bfbc-45a0-9702-dd6841af52fe",
"optimization_goal": "IMPRESSIONS",
"bid_estimate_minimum":8000000,
"bid_estimate_maximum":9000000
}
}
This endpoint retrieves the bid estimate for a specific ad squad.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/<ID>/bid_estimate
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the ad squad |
By Targeting Spec
curl -X POST \
-H 'Content-Type: application/json' \
-d '{"optimization_goal": "IMPRESSIONS", "targeting": {"geos": [{"country_code": "us"}],"demographics": [{"age_groups": ["21-24"],"gender": "MALE"}]}}' \
-H 'Authorization: Bearer meowmewmeow' \
https://adsapi.snapchat.com/v1/adaccounts/8abc3db7-8148-4fbf-999c-8d2266369d75/bid_estimate
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57affee300ff0d91229fabb9710001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010110",
"bid_estimate": {
"optimization_goal": "IMPRESSIONS",
"bid_estimate_minimum":8000000,
"bid_estimate_maximum":9000000
}
}
This endpoint retrieves the bid estimate for a specific targeting spec, whether or not the targeting is in use by an ad squad.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/<ID>/bid_estimate
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the ad account |
Attributes
Attribute | Description | Required | Note |
---|---|---|---|
optimization_goal | Optimization Goal | R | Available for all valid optimization goals |
targeting | A valid Targeting Spec | R |
Delivery Status
The delivery status provides details of an entity’s status given delivery within the Snap ad platform.
Attributes
Entity | Status | Description |
---|---|---|
Common | PENDING | Default |
VALID | Entity is valid for delivery | |
INVALID_NOT_ACTIVE | Entity status isn’t active | |
INVALID_NOT_EFFECTIVE_ACTIVE | Entity has a valid state and is active, but a parent entity has something wrong with it and is preventing this entity becoming active | |
INVALID_START_TIME | Start time is after the present time | |
INVALID_END_TIME | End time is before the present time | |
INVALID_EFFECTIVE_START_TIME | Effective start time is after the present time | |
INVALID_EFFECTIVE_END_TIME | Effective end time is before now | |
INVALID_EFFECTIVE_DELETED | Entity is effectively deleted, often due to parent | |
INVALID_EFFECTIVE_INVALID | Entity is effectively invalid, often due to parent | |
INVALID_START_TIME_AFTER_END_TIME | Effective start time is after effective end time | |
Organization | NOT_ACTIVE_ORGANIZATION | Organization state isn’t active |
NOT_ENTERPRISE_ORGANIZATION | Organization type isn’t enterprise | |
Ad Account | TEST_AD_ACCOUNT | Ad account is test account |
INVALID_REMAINING_AD_ACCOUNT_BUDGET | Remaining ad account budget is less or equal to 0 | |
INVALID_AD_ACCOUNT_LIFETIME_SPEND_CAP | Ad account has invalid lifetime spend cap | |
INVALID_OVER_BUDGET_AD_ACCOUNT_FINALIZED_LIFETIME_SPEND | Ad account finalized lifetime spend exceeds lifetime spend cap | |
INVALID_OVER_BUDGET_AD_ACCOUNT_REALTIME_LIFETIME_SPEND | Ad account realtime lifetime spend exceeds lifetime spend cap | |
Campaign | INVALID_CAMPAIGN_LIFETIME_SPEND_CAP | Campaign has invalid lifetime spend cap |
INVALID_OVER_BUDGET_CAMPAIGN_FINALIZED_LIFETIME_SPEND | Campaign finalized lifetime spend exceeds lifetime spend cap | |
INVALID_OVER_BUDGET_CAMPAIGN_REALTIME_LIFETIME_SPEND | Campaign realtime lifetime spend exceeds lifetime spend cap | |
INVALID_OVER_BUDGET_CAMPAIGN_DAILY_SPEND | Campaign daily spend exceeds daily spend cap | |
NO_VALID_AD_SQUAD | Campaign has no valid ad squad | |
INVALID_RF_FOR_RESERVED_BUY | Reach frequency is invalid for reserved buy | |
INVALID_UNKNOWN_FORECAST_ERROR | Unknown error from forecast | |
INVALID_CAMPAIGN_HAS_NO_ACTIVE_AD_SQUAD | Campaign has no active ad squad | |
INVALID_TEST_ACCOUNT | Test account is invalid | |
Ad Squad | INVALID_TARGETING_REACH_STATUS | AdSquad targeting reach status is invalid |
INVALID_PENDING_TARGETING_REACH_STATUS | AdSquad targeting reach status is pending | |
INVALID_AD_SQUAD_HAS_NO_ACTIVE_ADS | AdSquad doesn’t have any active ad | |
INVALID_AD_SQUAD_WIREOBJECT | Failed to convert ad squad entity to wire object | |
INVALID_INTERNAL_PLACEMENT | AdSquad has invalid internal placement v2 and non-empty ads | |
INVALID_AD_SQUAD_HAS_UNSUPPORTED_AD_TYPE | AdSquad has unsupported ad type | |
INVALID_UNSUPPORTED_AD_SQUAD_TYPE | AdSquad has an unsupported type | |
INVALID_AD_SQUAD_LIFETIME_SPEND_CAP | Ad squad has invalid lifetime spend cap | |
INVALID_OVER_BUDGET_AD_SQUAD_FINALIZED_LIFETIME_SPEND | Ad squad finalized lifetime spend exceeds lifetime spend cap | |
INVALID_OVER_BUDGET_AD_SQUAD_REALTIME_LIFETIME_SPEND | Ad squad realtime lifetime spend exceeds lifetime spend cap | |
INVALID_AD_SQUAD_DAILY_SPEND_CAP | Ad squad has invalid daily spend cap | |
INVALID_OVER_BUDGET_AD_SQUAD_DAILY_SPEND | Ad squad daily spend exceeds daily spend cap | |
INVALID_AD_SQUAD_RESERVED_STATUS_NOT_ACTIVE | Ad Squad reserved_status is non-ACTIVE | |
LEARNING PHASE | Ad Squad is in learning phase. | |
Ad | NOT_APPROVED_AD | Ad has non-approved review status |
INVALID_NOT_APPROVED_REVIEW_STATUS | The Ad has failed Ad review | |
INVALID_PENDING_REVIEW_STATUS | Ad review is still pending | |
INVALID_DYNAMIC_CONTENT_MARKUP | Creative has invalid dynamic content markup | |
INVALID_UNSUPPORTED_AD_TYPE | Ad type isn’t supported | |
INVALID_NO_CREATIVE_EFFECTIVE_ACTIVE | Ad has no effectively active Creative | |
INVALID_DYNAMIC_FILTER | Dynamic fields in Filter creator in Ads Manager have errors. Eg “Time of Day” or “Day of Week”. Filter Ad will not be published | |
INVALID_CREATIVE_PACKAGING_STATUS | Processsing of image/video asset failed | |
INVALID_SKOV_REQUIRES_SKAN | SKAN must be enabled on ad set if using SKOverlay |
Measurement
Measurement endpoints provides stats data that is updated approximately every 15 minutes.
All stats requests can be made with TOTAL, DAY, or HOUR granularity.
Request/Response Pattern
Stats endpoints have a consistent request and response pattern.
Request Pattern
Pattern:
GET /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}/stats
Example:
GET /v1/campaigns/ff869d1f-0923-4d28-8577-4c36291f0fca/stats
Response Pattern - TOTAL Granularity
Response pattern for TOTAL Granularity requests
{
"request_status": "success",
"request_id": "57ad1ad600076e58fa35e192",
"total_stats": [
{
"sub_request_status": "success",
"total_stat": {
"id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
}
]
}
Response Pattern - DAY Granularity
Response pattern for DAY Granularity requests
{
"request_status": "success",
"request_id": "57ad240f000756e8d435a6cd",
"timeseries_stats": [
{
"sub_request_status": "success",
"timeseries_stat": {
"id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
"type": "CAMPAIGN",
"granularity": "DAY",
"start_time": "2016-08-05T22:00:00.000-07:00",
"end_time": "2016-08-07T22:00:00.000-07:00",
"timeseries": [
{
"start_time": "2016-08-05T22:00:00.000-07:00",
"end_time": "2016-08-06T22:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
},
{
"start_time": "2016-08-06T22:00:00.000-07:00",
"end_time": "2016-08-07T22:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
]
}
}
]
}
Response Pattern - HOUR Granularity
Response pattern for HOUR Granularity requests
{
"request_status": "success",
"request_id": "57ad245a000e3c88bc33ea4e",
"timeseries_stats": [
{
"sub_request_status": "success",
"timeseries_stat": {
"id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
"type": "CAMPAIGN",
"granularity": "HOUR",
"start_time": "2016-08-05T18:00:00.000-07:00",
"end_time": "2016-08-06T18:00:00.000-07:00",
"timeseries": [
{
"start_time": "2016-08-05T18:00:00.000-07:00",
"end_time": "2016-08-05T19:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
},
{
"start_time": "2016-08-05T19:00:00.000-07:00",
"end_time": "2016-08-05T20:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
....
{
"start_time": "2016-08-06T16:00:00.000-07:00",
"end_time": "2016-08-06T17:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
},
{
"start_time": "2016-08-06T17:00:00.000-07:00",
"end_time": "2016-08-06T18:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
]
}
}
]
}
Request Parameters
Attribute | Description | Required | Possible Values |
---|---|---|---|
breakdown | Object-level breakdown | O | ad, adsquad [Only available on Campaign Stats endpoint], campaign [Only available on Ad Account Stats endpoint] |
fields | Metrics requested (comma-separated) | O | (see table below; default: impressions,spend) |
end_time | End Time (ISO 8601) | R* | |
start_time | Start Time (ISO 8601) | R* | |
granularity | Metrics granularity | R | TOTAL, DAY, HOUR, LIFETIME |
test | Return Sample (fake) Stats | O | false (default), true |
dimension | Insight-level breakdown | O | GEO, DEMO, INTEREST, DEVICE |
pivot | The pivot to be used for insights breakdown | O | country, region, dma, gender, age_bucket, interest_category_id, interest_category_name, operating_system, make, model |
action_report_time | Specifies the principle for conversion reporting | O | conversion (default), impression** |
swipe_up_attribution_window | Attribution window for swipe ups | O | 1_DAY, 7_DAY, 28_DAY (default) |
view_attribution_window | Attribution window for views | O | 1_HOUR, 3_HOUR, 6_HOUR, 1_DAY (default), 7_DAY, 28_DAY*** |
position_stats | Position metric breakdown for Snap Ads within a Story Ad | O | true |
omit_empty | Omits records with zero data for all metrics for a given date/entity. If there is data for any metric for a given date/entity, all metrics for that date/entity are returned | O | false (default), true |
conversion_source_types | Conversion source breakout by platform | O | web, app, offline**, total, total_off_platform, total_on_platform |
limit | The limit parameter specifies how many entities should be returned per page | O | integer, max 200 |
** offline conversion data source ( conversion_source_types=offline ) and impression based conversions ( action_report_time=impression ) are available from 1 May 2020 onwards.
*** 28_DAY view_attribution_window is deprecated, legacy data is available up until 1 March 2021
Response Parameters & Finalization
Attribute | Description |
---|---|
finalized_data_end_time | This attribute defines the time up until when non-conversion reporting metrics are finalized. You can query for all metrics before this time including uniques and reach and they will have the final numbers. For any time after the finalized_data_end_time the metrics are still undergoing de-duplication and finalization and may change accordingly. |
conversion_data_processed_end_time | This attribute defines the time up until when conversion metrics are finalized, for any time after the conversion_data_processed_end_time the conversion metrics are still undergoing processing and may change accordingly. Note that this attribute only covers conversion by time of conversion. |
paging | If you are using pagination the paging attribute will contain a next_link attribute which holds the API call to fetch the next page. |
Pagination
For calls that fetch stats for many entities we recommend that you use pagination. The limit parameter specifies how many entities should be returned per page. The maximum pagination limit is 200.
The returned result will contain a paging
attribute, this in turn holds a next_link
attribute which holds the API call to fetch the next page. Paginated calls are rdered by time of creation, non-paginated calls are unsorted.
Core Metrics
The following metrics are available for all Snap Ads.
Field Name | Description |
---|---|
impressions | Impression Count |
swipes | Swipe-Up Count |
view_time_millis | Use screen_time_millis instead. Total Time Spent on top Snap Ad (milliseconds) |
screen_time_millis | Total Time Spent on top Snap Ad (milliseconds) |
quartile_1 | Video Views to 25% |
quartile_2 | Video Views to 50% |
quartile_3 | Video Views to 75% |
view_completion | Video Views to completion |
spend | Amount Spent (micro-currency) |
video_views | The total number of impressions that meet the qualifying video view criteria of at least 2 seconds of consecutive watch time or a swipe up action on the Top Snap |
Additional Metrics
See the Metrics and supported granularities table for a breakdown of the reporting granularities available per Ad type. For LIFETIME granularity the data is only accessible as finalized data, available after 48-72 hours.
Field Name | Snap Ad Types | Description |
---|---|---|
android_installs | APP_INSTALL | # of Android App Installs |
attachment_avg_view_time_millis | Any Attachment | Average Attachment View Time (milli-seconds) |
attachment_frequency | Any Attachment | Average # of Attachment Views per User Reached |
attachment_quartile_1 | LONGFORM_VIDEO | Long Form Video Views to 25% |
attachment_quartile_2 | LONGFORM_VIDEO | Long Form Video Views to 50% |
attachment_quartile_3 | LONGFORM_VIDEO | Long Form Video Views to 75% |
attachment_total_view_time_millis | Any Attachment | Total Attachment View Time (milli-seconds) |
attachment_uniques | Any Attachment | # of unique attachment impressions |
attachment_view_completion | LONGFORM_VIDEO | Long Form Video Views to completion |
attachment_video_views | LONGFORM_VIDEO | Long Form Video Attachment Views, viewed for at least 10 consecutive seconds or reached 97% of the Long Form Video duration |
avg_view_time_millis | Any | Use avg_screen_time_millis instead. Average Top Snap view time per User Reached |
avg_screen_time_millis | Any | Average Top Snap view time across all impressions |
frequency | Any | Average # of Impressions per User Reached |
ios_installs | APP_INSTALL | # of iOS App Installs |
swipe_up_percent | Any Attachment | % of Impressions that Swiped-Up |
total_installs | APP_INSTALL | Total # of App Installs |
uniques | Any | # of unique impressions |
video_views_time_based | Any | The total number of impressions that meet the qualifying video view criteria of at least 2 seconds, not including swipe ups |
video_views_15s | Any | The total number of impressions that meet the qualifying video view criteria of at least 15 seconds, or 97% completion if it’s shorter than 15 seconds, or a swipe up action on the ad |
story_opens | STORY | # of times users tapped on the ad tile in the feed to view the Story Ad |
story_completes | STORY | # of times users viewed through to the last Snap of your Story Ad |
profile_clicks | Any | # of times users tapped the logo in the upper corner taking them to the profile page |
position_impressions | STORY | # the impression number for this story ad position |
position_screen_time_millis | STORY | # the total view time in milliseconds for this story ad position |
position_swipe_up_percent | STORY | # the swipe up rate for this story ad position |
avg_position_screen_time_millis | STORY | # the average view time for this story ad position |
shares | LENS, AD_TO_LENS, FILTER | # of times lens/filter was shared in a Chat or Story |
saves | LENS, AD_TO_LENS, FILTER | # of times lens/filter was saved to Memories |
paid_impressions | LENS, FILTER, AD_TO_LENS | The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter’s viewing session |
earned_impressions | LENS, FILTER, AD_TO_LENS | The number of times your ad was viewed after being shared by a Snapchatter via Chat or Stories |
total_impressions | LENS | The total number of impressions (Paid and Earned) |
play_time_millis | LENS | The total amount of time in where Snapchatters interacted with your Lens in the camera (milliseconds) |
total_reach | LENS | The number of unique Snapchatters who viewed your Lens ad, either by receiving a Paid or Earned Impression. |
earned_reach | LENS, FILTER, AD_TO_LENS | The number of unique Snapchatters who viewed the filter/lens |
native_leads | LEAD_GENERATION | Total number of Snapchat users that swipe up, fill out the required fields, and hit ‘Submit’ on Lead Form attachments. If a user swipes down or cancels before hitting ‘Submit,’ this action is not counted |
Apple Transparent Tracking (ATT) Reporting
All the users whose activity is tracked using the attribution and measurement services will be split into two categories. Please note that only conversion metrics are affected by the ATT updates.
User Category | Description | User groups in category |
---|---|---|
Fully Tracked group | These user groups are fully supported for the features listed below. | Android, iOS opted-in users |
Partially tracked group | These user groups are partially supported. | Snap Pixel, iOS opted out users and users reported via Conversions API |
Below is the list of all the reporting fields and API fields that are affected for each group.
Dimension/Granularity | Conversion Sources | |
---|---|---|
Fully Tracked Group - Android (in-app), iOS (opt-in) |
Partially tracked Group - Snap Pixel, iOS (opt-out), Conversion API |
|
Time of Conversion action_report_time=conversion |
Supported | Supported |
Time of Exposure action_report_time=impression |
Supported | Supported |
Event Source (web/app/offline) |
Supported | Supported |
Entity (campaign/ad set/ad) |
Supported | Supported |
Age | Supported | Supported |
Gender | Supported | Supported |
Age, Gender | Supported | Supported |
Country | Supported | Supported |
OS | Supported | Supported |
Platform (on/off snapchat) | Supported | Supported |
Region (US Only) | NOT Supported | NOT Supported |
DMA (US Only) | NOT Supported | NOT Supported |
Device Make | NOT Supported | NOT Supported |
SLC (lifestyle category) | NOT Supported | NOT Supported |
Product | NOT Supported | NOT Supported |
Hourly Conversions | Supported | NOT Supported |
Daily, Total, Lifetime Conversion | Supported | Supported |
Swipe Up Window: 1_DAY, 7_DAY, 28_DAY View Thru Window: 1_DAY, 7_DAY |
Supported | Supported |
View Through Window: 1_HOUR, 3_HOUR, 6_HOUR |
Supported | Supported |
View Through Window: 28_DAY* | NOT Supported | NOT Supported |
*This field is now effectively deprecated.
SKAd Network Reporting
Due to the attribution methodology of Apple’s SKAdNetwork there are some limitations when fetching reporting for Ad serving entities that are opted into SKAdNetwork tracking.
SKAdNetwork conversions reported at the Ad level or below may be modeled based on first party ad engagement signals using statistical methods. Modeling is only applied at the ad level. Please note that you should still take a patient approach to testing and optimization decisions including: waiting 48+ hours before adjusting Bids and Budgets, and starting with high Bids and Budgets to pass privacy thresholds. If you do not, you run the risk of prematurely pausing Ad creatives that may lead to strong performance.
The available granularities are DAY, TOTAL, and LIFETIME, HOUR granularity is not available.
The conversion window for a SKAd Network SWIPE (click) conversion is 30 day based on the time of conversion, all ad types support SWIPE conversions.
The conversion window for a SKAd Network VIEW conversion is 24 hours based on the time of conversion. A VIEW is defined as 3 seconds in length.
The ad types that currently support the VIEW conversion are; SNAP_AD, LONGFORM_VIDEO, APP_INSTALL, REMOTE_WEBPAGE, DEEP_LINK, COLLECTION
Reporting Insights are not available for SKAdNetwork metrics, the use of
report_dimension
is not possible.
SKAd Network Conversion Metrics
Conversion metrics for the SKAd Network are broken out by Swipe conversions, View conversions, and the total number of conversions.
SKAd Network Swipe Conversion Metrics
The following metrics return the SKAd Network SWIPE (click) conversions.
Name | Description |
---|---|
conversion_total_installs_sk_ad_network | Total App Installs tracked via SKAd Network |
conversion_ios_installs_sk_ad_network | Exact same metric as conversion_total_installs_sk_ad_network |
conversion_purchases_sk_ad_network | |
conversion_save_sk_ad_network | |
conversion_start_checkout_sk_ad_network | |
conversion_add_cart_sk_ad_network | |
conversion_view_content_sk_ad_network | |
conversion_add_billing_sk_ad_network | |
conversion_sign_ups_sk_ad_network | |
conversion_searches_sk_ad_network | |
conversion_level_completes_sk_ad_network | |
conversion_app_opens_sk_ad_network | |
conversion_page_views_sk_ad_network | |
conversion_subscribe_sk_ad_network | |
conversion_ad_click_sk_ad_network | |
conversion_ad_view_sk_ad_network | |
conversion_complete_tutorial_sk_ad_network | |
conversion_invite_sk_ad_network | |
conversion_login_sk_ad_network | |
conversion_share_sk_ad_network | |
conversion_reserve_sk_ad_network | |
conversion_achievement_unlocked_sk_ad_network | |
conversion_add_to_wishlist_sk_ad_network | |
conversion_spend_credits_sk_ad_network | |
conversion_rate_sk_ad_network | |
conversion_start_trial_sk_ad_network | |
conversion_list_view_sk_ad_network | |
custom_event_1_sk_ad_network | |
custom_event_2_sk_ad_network | |
custom_event_3_sk_ad_network | |
custom_event_4_sk_ad_network | |
custom_event_5_sk_ad_network | |
unknown_sk_ad_network | SkAdNetwork conversion events with unknown Conversion Values. |
conversion_assist_install_sk_ad_network | The number of times the SKAdNetwork campaign drove an App Install, but was not the last touch before the App Install occurred. |
conversion_null_sk_ad_network | The number of SKAdNetwork conversion events with “null” Conversion Values. This indicates the campaign did not generate enough daily SKAdNetwork conversions to pass Apple’s privacy threshold. |
SKAd Network View Conversion Metrics
The following metrics return the SKAd Network VIEW conversions.
Name | Description |
---|---|
conversion_total_installs_sk_ad_network_view | Total App Installs tracked via SKAd Network |
conversion_ios_installs_sk_ad_network_view | Exact same metric as conversion_total_installs_sk_ad_network_view |
conversion_purchases_sk_ad_network_view | |
conversion_save_sk_ad_network_view | |
conversion_start_checkout_sk_ad_network_view | |
conversion_add_cart_sk_ad_network_view | |
conversion_view_content_sk_ad_network_view | |
conversion_add_billing_sk_ad_network_view | |
conversion_sign_ups_sk_ad_network_view | |
conversion_searches_sk_ad_network_view | |
conversion_level_completes_sk_ad_network_view | |
conversion_app_opens_sk_ad_network_view | |
conversion_page_views_sk_ad_network_view | |
conversion_subscribe_sk_ad_network_view | |
conversion_ad_click_sk_ad_network_view | |
conversion_ad_view_sk_ad_network_view | |
conversion_complete_tutorial_sk_ad_network_view | |
conversion_invite_sk_ad_network_view | |
conversion_login_sk_ad_network_view | |
conversion_share_sk_ad_network_view | |
conversion_reserve_sk_ad_network_view | |
conversion_achievement_unlocked_sk_ad_network_view | |
conversion_add_to_wishlist_sk_ad_network_view | |
conversion_spend_credits_sk_ad_network_view | |
conversion_rate_sk_ad_network_view | |
conversion_start_trial_sk_ad_network_view | |
conversion_list_view_sk_ad_network_view | |
custom_event_1_sk_ad_network_view | |
custom_event_2_sk_ad_network_view | |
custom_event_3_sk_ad_network_view | |
custom_event_4_sk_ad_network_view | |
custom_event_5_sk_ad_network_view | |
unknown_sk_ad_network_view | SkAdNetwork conversion events with unknown Conversion Values. |
conversion_assist_install_sk_ad_network_view | The number of times the SKAdNetwork campaign drove an App Install, but was not the last touch before the App Install occurred. |
conversion_null_sk_ad_network_view | The number of SKAdNetwork conversion events with “null” Conversion Values. This indicates the campaign did not generate enough daily SKAdNetwork conversions to pass Apple’s privacy threshold. |
SKAd Network Total Conversion Metrics
The following metrics return the total sum of the SKAd Network SWIPE and VIEW conversions.
Name | Description |
---|---|
conversion_total_installs_sk_ad_network_total | Total App Installs tracked via SKAd Network |
conversion_ios_installs_sk_ad_network_total | Exact same metric as conversion_total_installs_sk_ad_network_total |
conversion_purchases_sk_ad_network_total | |
conversion_save_sk_ad_network_total | |
conversion_start_checkout_sk_ad_network_total | |
conversion_add_cart_sk_ad_network_total | |
conversion_view_content_sk_ad_network_total | |
conversion_add_billing_sk_ad_network_total | |
conversion_sign_ups_sk_ad_network_total | |
conversion_searches_sk_ad_network_total | |
conversion_level_completes_sk_ad_network_total | |
conversion_app_opens_sk_ad_network_total | |
conversion_page_views_sk_ad_network_total | |
conversion_subscribe_sk_ad_network_total | |
conversion_ad_click_sk_ad_network_total | |
conversion_ad_view_sk_ad_network_total | |
conversion_complete_tutorial_sk_ad_network_total | |
conversion_invite_sk_ad_network_total | |
conversion_login_sk_ad_network_total | |
conversion_share_sk_ad_network_total | |
conversion_reserve_sk_ad_network_total | |
conversion_achievement_unlocked_sk_ad_network_total | |
conversion_add_to_wishlist_sk_ad_network_total | |
conversion_spend_credits_sk_ad_network_total | |
conversion_rate_sk_ad_network_total | |
conversion_start_trial_sk_ad_network_total | |
conversion_list_view_sk_ad_network_total | |
custom_event_1_sk_ad_network_total | |
custom_event_2_sk_ad_network_total | |
custom_event_3_sk_ad_network_total | |
custom_event_4_sk_ad_network_total | |
custom_event_5_sk_ad_network_total | |
unknown_sk_ad_network_total | SkAdNetwork conversion events with unknown Conversion Values. |
conversion_assist_install_sk_ad_network_total | The number of times the SKAdNetwork campaign drove an App Install, but was not the last touch before the App Install occurred. |
conversion_null_sk_ad_network_total | The number of SKAdNetwork conversion events with “null” Conversion Values. This indicates the campaign did not generate enough daily SKAdNetwork conversions to pass Apple’s privacy threshold. |
SKAd Network Conversion Example
curl "https://adsapi.snapchat.com/v1/campaigns/5b483328-dfab-4321-be60-8ad2dfd63d35/stats?granularity=TOTAL&start_time=2021-01-21T00:00:00.000&end_time=2021-01-25T00:00:00.000&fields=impressions,spend,swipes,conversion_total_installs_sk_ad_network,conversion_purchases_sk_ad_network,conversion_add_cart_sk_ad_network"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "601d83ee00ff06ea9762c9c4f20001737e616473617069736300016275696c642d31323762373738342d312d3432302d3000010161",
"total_stats": [
{
"sub_request_status": "SUCCESS",
"total_stat": {
"id": "5b483328-dfab-4321-be60-8ad2dfd63d35",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"stats": {
"impressions": 61295,
"swipes": 4528,
"spend": 407129814,
"conversion_total_installs_sk_ad_network": 1199,
"conversion_purchases_sk_ad_network": 6637,
"conversion_add_cart_sk_ad_network": 7212
},
"start_time": "2021-01-20T16:00:00.000-08:00",
"end_time": "2021-01-24T16:00:00.000-08:00",
"finalized_data_end_time": "2021-02-05T03:00:00.000-08:00"
}
}
]
}
This example fetches three specific SKAd Network conversion metrics.
Conversion Reporting
The action_report_time parameter specifies the timing to use when requesting conversion reporting. Passing the value conversion will return conversions based on the time the user triggered the conversion event, passing the value impression will return conversions based on the time the ad impression took place.
Reporting for conversions based on ad impression (action_report_time=impression), are available from 1st May 2020 onwards.
Conversion Event Stats
The following conversion event metrics are available for ads that have been setup to track conversions through Snap Pixel.
Fields | Granularity | Description |
---|---|---|
conversion_purchases | Any | # of attributed “PURCHASE” conversion events |
conversion_purchases_value | Any | Value of attributed “PURCHASE” conversion events (microcurrency in Ad Account’s currency) |
conversion_save | Any | # of attributed “SAVE” conversion events |
conversion_save_value | Any | Value of attributed “SAVE” conversion events (microcurrency in Ad Account’s currency) |
conversion_start_checkout | Any | # of attributed “START_CHECKOUT” conversion events |
conversion_start_checkout_value | Any | Value of attributed “START_CHECKOUT” conversion events (microcurrency in Ad Account’s currency) |
conversion_add_cart | Any | # of attributed “ADD_CART” conversion events |
conversion_add_cart_value | Any | Value of attributed “ADD_CART” conversion events (microcurrency in Ad Account’s currency) |
conversion_view_content | Any | # of attributed “VIEW_CONTENT” conversion events |
conversion_view_content_value | Any | Value of attributed “VIEW_CONTENT” conversion events (microcurrency in Ad Account’s currency) |
conversion_add_billing | Any | # of attributed “ADD_BILLING” conversion events |
conversion_add_billing_value | Any | Value of attributed “ADD_BILLING” conversion events (microcurrency in Ad Account’s currency) |
conversion_sign_ups | Any | # of attributed “SIGN_UP” conversion events |
conversion_sign_ups_value | Any | Value of attributed “SIGN_UP” conversion events (microcurrency in Ad Account’s currency) |
conversion_searches | Any | # of attributed “SEARCH” conversion events |
conversion_searches_value | Any | Value of attributed “SEARCH” conversion events (microcurrency in Ad Account’s currency) |
conversion_level_completes | Any | # of attributed “LEVEL_COMPLETE” conversion events |
conversion_level_completes_value | Any | Value of attributed “LEVEL_COMPLETE” conversion events (microcurrency in Ad Account’s currency) |
conversion_app_opens | Any | # of attributed “APP_OPEN” conversion events |
conversion_app_opens_value | Any | Value of attributed “APP_OPEN” conversion events (microcurrency in Ad Account’s currency) |
conversion_page_views | Any | # of attributed “PAGE_VIEW” conversion events |
conversion_page_views_value | Any | Value of attributed “PAGE_VIEW” conversion events (microcurrency in Ad Account’s currency) |
conversion_subscribe | Any | # of attributed “SUBSCRIBE” conversion events |
conversion_subscribe_value | Any | Value of attributed “SUBSCRIBE” conversion events (microcurrency in Ad Account’s currency) |
conversion_ad_click | Any | # of attributed “AD_CLICK” conversion events |
conversion_ad_click_value | Any | Value of attributed “AD_CLICK” conversion events (microcurrency in Ad Account’s currency) |
conversion_ad_view | Any | # of attributed “AD_VIEW” conversion events |
conversion_ad_view_value | Any | Value of attributed “AD_VIEW” conversion events (microcurrency in Ad Account’s currency) |
conversion_complete_tutorial | Any | # of attributed “COMPLETE_TUTORIAL” conversion events |
conversion_complete_tutorial_value | Any | Value of attributed “COMPLETE_TUTORIAL” conversion events (microcurrency in Ad Account’s currency) |
conversion_invite | Any | # of attributed “INVITE” conversion events |
conversion_invite_value | Any | Value of attributed “INVITE” conversion events (microcurrency in Ad Account’s currency) |
conversion_login | Any | # of attributed “LOGIN” conversion events |
conversion_login_value | Any | Value of attributed “LOGIN” conversion events (microcurrency in Ad Account’s currency) |
conversion_share | Any | # of attributed “SHARE” conversion events |
conversion_share_value | Any | Value of attributed “SHARE” conversion events (microcurrency in Ad Account’s currency) |
conversion_reserve | Any | # of attributed “RESERVE” conversion events |
conversion_reserve_value | Any | Value of attributed “RESERVE” conversion events (microcurrency in Ad Account’s currency) |
conversion_achievement_unlocked | Any | # of attributed “ACHIEVEMENT_UNLOCKED” conversion events |
conversion_achievement_unlocked_value | Any | Value of attributed “ACHIEVEMENT_UNLOCKED” conversion events (microcurrency in Ad Account’s currency) |
conversion_add_to_wishlist | Any | # of attributed “ADD_TO_WISHLIST” conversion events |
conversion_add_to_wishlist_value | Any | Value of attributed “ADD_TO_WISHLIST” conversion events (microcurrency in Ad Account’s currency) |
conversion_spend_credits | Any | # of attributed “SPENT_CREDITS” conversion events |
conversion_spend_credits_value | Any | Value of attributed “SPENT_CREDITS” conversion events (microcurrency in Ad Account’s currency) |
conversion_rate | Any | # of attributed “RATE” conversion events |
conversion_rate_value | Any | Value of attributed “RATE” conversion events (microcurrency in Ad Account’s currency) |
conversion_start_trial | Any | # of attributed “START_TRIAL” conversion events |
conversion_start_trial_value | Any | Value of attributed “START_TRIAL” conversion events (microcurrency in Ad Account’s currency) |
conversion_list_view | Any | # of attributed “LIST_VIEW” conversion events |
conversion_list_view_value | Any | Value of attributed “LIST_VIEW” conversion events (microcurrency in Ad Account’s currency) |
conversion_visit | Any | # of attributed “VISIT” conversion events |
conversion_visit_value | Any | Value of attributed “VISIT” conversion events (microcurrency in Ad Account’s currency) |
custom_event_1 | Any | # of attributed “CUSTOM_EVENT_1” conversion events |
custom_event_1_value | Any | Value of attributed “CUSTOM_EVENT_1” conversion events (microcurrency in Ad Account’s currency) |
custom_event_2 | Any | # of attributed “CUSTOM_EVENT_2” conversion events |
custom_event_2_value | Any | Value of attributed “CUSTOM_EVENT_2” conversion events (microcurrency in Ad Account’s currency) |
custom_event_3 | Any | # of attributed “CUSTOM_EVENT_3” conversion events |
custom_event_3_value | Any | Value of attributed “CUSTOM_EVENT_3” conversion events (microcurrency in Ad Account’s currency) |
custom_event_4 | Any | # of attributed “CUSTOM_EVENT_4” conversion events |
custom_event_4_value | Any | Value of attributed “CUSTOM_EVENT_4” conversion events (microcurrency in Ad Account’s currency) |
custom_event_5 | Any | # of attributed “CUSTOM_EVENT_5” conversion events |
custom_event_5_value | Any | Value of attributed “CUSTOM_EVENT_5” conversion events (microcurrency in Ad Account’s currency) |
Conversion breakout
The parameter conversion_source_types provides a breakout of conversions based on where the conversions occurred.
Parameter | Description |
---|---|
total | All conversion events |
web | Events reported via the Snap Pixel SDK |
app | Events reported within an App |
offline | Events reported from an offline source (in-store) |
total | The combined events reported for web, app, offline, and on platform (Stores and Profiles) |
total_off_platform | The combined events reported for web, app, and offline |
total_on_platform | Events reported from a Snap platform source (Stores and Profiles) |
Conversion breakout example
curl "https://adsapi.snapchat.com/v1/adsquads/0b7e62aa-a8bc-48f6-a410-c65eee9cc9a7/stats?fields=conversion_purchases,impressions,spend,swipe_up_percent,swipes,view_completion&conversion_source_types=total,web,app"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5de004c100ff03ea1eeb1050430001737e616473617069736300016275696c642d61663733336133322d312d3330372d3000010103",
"total_stats": [
{
"sub_request_status": "SUCCESS",
"total_stat": {
"id": "0b7e62aa-a8bc-48f6-a410-c65eee9cc9a7",
"type": "AD_SQUAD",
"granularity": "TOTAL",
"stats": {
"impressions": 2337371,
"swipes": 14745,
"view_completion": 69506,
"swipe_up_percent": 0.0063,
"spend": 3449137066,
"conversion_purchases": 1141,
"conversion_purchases_web": 659,
"conversion_purchases_app": 482
},
"finalized_data_end_time": "2019-11-28T02:00:00.000-08:00"
}
}
]
}
This parameter breaks down conversions based on where the conversion occurred.
Omitting empty records example
curl "https://adsapi.snapchat.com/v1/campaigns/9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37/stats?granularity=DAY&start_time=2019-11-12T00%3A00%3A00-08%3A00&end_time=2019-11-16T00%3A00%3A00-08%3A00&&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&fields=conversion_purchases,impressions,swipes,spend&conversion_source_types=web,app,total"
-H "Authorization: Bearer meowmeowmeow"
An example not using omit_empty, this returns several day entries with no metrics.
{
"request_status": "SUCCESS",
"request_id": "5de0f99900ff02f49ea1540d1c0001737e616473617069736300016275696c642d61663733336133322d312d3330372d300001013c",
"timeseries_stats": [
{
"sub_request_status": "SUCCESS",
"timeseries_stat": {
"id": "9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37",
"type": "CAMPAIGN",
"granularity": "DAY",
"swipe_up_attribution_window": "28_DAY",
"view_attribution_window": "7_DAY",
"start_time": "2019-11-12T00:00:00.000-08:00",
"end_time": "2019-11-16T00:00:00.000-08:00",
"finalized_data_end_time": "2019-11-28T00:00:00.000-08:00",
"timeseries": [
{
"start_time": "2019-11-12T00:00:00.000-08:00",
"end_time": "2019-11-13T00:00:00.000-08:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"conversion_purchases": 0,
"conversion_purchases_web": 0,
"conversion_purchases_app": 0
}
},
{
"start_time": "2019-11-13T00:00:00.000-08:00",
"end_time": "2019-11-14T00:00:00.000-08:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"conversion_purchases": 0,
"conversion_purchases_web": 0,
"conversion_purchases_app": 0
}
},
{
"start_time": "2019-11-14T00:00:00.000-08:00",
"end_time": "2019-11-15T00:00:00.000-08:00",
"stats": {
"impressions": 599725,
"swipes": 3790,
"spend": 594736665,
"conversion_purchases": 62,
"conversion_purchases_web": 42,
"conversion_purchases_app": 20
}
},
{
"start_time": "2019-11-15T00:00:00.000-08:00",
"end_time": "2019-11-16T00:00:00.000-08:00",
"stats": {
"impressions": 670692,
"swipes": 4189,
"spend": 716170632,
"conversion_purchases": 125,
"conversion_purchases_web": 82,
"conversion_purchases_app": 43
}
}
]
}
}
]
}
curl "https://adsapi.snapchat.com/v1/campaigns/9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37/stats?granularity=DAY&start_time=2019-11-12T00%3A00%3A00-08%3A00&end_time=2019-11-16T00%3A00%3A00-08%3A00&&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&fields=conversion_purchases,impressions,swipes,spend&conversion_source_types=web,app,total&omit_empty=true"
-H "Authorization: Bearer meowmeowmeow"
An example using omit_empty, this returns only day entries with metrics:
{
"request_status": "SUCCESS",
"request_id": "5de0fa4900ff0942bb5374cb8f0001737e616473617069736300016275696c642d61663733336133322d312d3330372d300001014d",
"timeseries_stats": [
{
"sub_request_status": "SUCCESS",
"timeseries_stat": {
"id": "9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37",
"type": "CAMPAIGN",
"granularity": "DAY",
"swipe_up_attribution_window": "28_DAY",
"view_attribution_window": "7_DAY",
"start_time": "2019-11-12T00:00:00.000-08:00",
"end_time": "2019-11-16T00:00:00.000-08:00",
"finalized_data_end_time": "2019-11-28T00:00:00.000-08:00",
"timeseries": [
{
"start_time": "2019-11-14T00:00:00.000-08:00",
"end_time": "2019-11-15T00:00:00.000-08:00",
"stats": {
"impressions": 599725,
"swipes": 3790,
"spend": 594736665,
"conversion_purchases": 62,
"conversion_purchases_web": 42,
"conversion_purchases_app": 20
}
},
{
"start_time": "2019-11-15T00:00:00.000-08:00",
"end_time": "2019-11-16T00:00:00.000-08:00",
"stats": {
"impressions": 670692,
"swipes": 4189,
"spend": 716170632,
"conversion_purchases": 125,
"conversion_purchases_web": 82,
"conversion_purchases_app": 43
}
}
]
}
}
]
}
The parameter omit_empty will omit records with zero data for all metrics for a given date/entity. If there is data for any metric for a given date/entity, all metrics for that date/entity are returned.
The omit_empty parameter allows developers to speed up calculations as empty entries can be removed before the calculation is made, it also allows developers to structure an app to avoid displaying empty entries in the UI.
Metrics and supported granularities
Metric | Real time | HOUR | DAY | TOTAL | LIFETIME |
---|---|---|---|---|---|
android_installs | YES | YES. time must be of hour boundary, start_time and end_time within 7 days | YES. time must be of day boundary, start_time and end_time within 31 days | YES. time must be of day boundary, start_time and end_time must be both specified, or neither. In the latter case, it combines lifetime and realtime stats. | YES. no start_time, end_time can be specified. |
attachment_avg_view_time_millis | |||||
attachment_impressions | |||||
attachment_quartile_1 | |||||
attachment_quartile_2 | |||||
attachment_quartile_3 | |||||
attachment_total_view_time_millis | |||||
attachment_view_completion | |||||
avg_screen_time_millis | |||||
avg_view_time_millis | |||||
impressions | |||||
ios_installs | |||||
quartile_1 | |||||
quartile_2 | |||||
quartile_3 | |||||
screen_time_millis | |||||
spend | |||||
swipe_up_percent | |||||
swipes | |||||
total_installs | |||||
video_views | |||||
video_views_time_based | |||||
video_views_15s | |||||
view_completion | |||||
view_time_millis | |||||
paid_impressions | |||||
earned_impressions | |||||
total_impressions | |||||
play_time_millis | |||||
profile_clicks | |||||
shares | |||||
saves | |||||
native_leads | |||||
conversion_purchases | |||||
conversion_purchases_value | |||||
conversion_save | |||||
conversion_save_value | |||||
conversion_start_checkout | |||||
conversion_start_checkout_value | |||||
conversion_add_cart | |||||
conversion_add_cart_value | |||||
conversion_view_content | |||||
conversion_view_content_value | |||||
conversion_add_billing | |||||
conversion_add_billing_value | |||||
conversion_signups | |||||
conversion_signups_value | |||||
conversion_searches | |||||
conversion_searches_value | |||||
conversion_level_completes | |||||
conversion_level_completes_value | |||||
conversion_app_opens | |||||
conversion_app_opens_value | |||||
conversion_page_views | |||||
conversion_page_views_value | |||||
conversion_subscribe | |||||
conversion_subscribe_value | |||||
conversion_ad_click | |||||
conversion_ad_click_value | |||||
conversion_ad_view | |||||
conversion_ad_view_value | |||||
conversion_complete_tutorial | |||||
conversion_complete_tutorial_value | |||||
conversion_invite | |||||
conversion_invite_value | |||||
conversion_login | |||||
conversion_login_value | |||||
conversion_share | |||||
conversion_share_value | |||||
conversion_reserve | |||||
conversion_reserve_value | |||||
conversion_achievement_unlocked | |||||
conversion_achievement_unlocked_value | |||||
conversion_add_to_wishlist | |||||
conversion_add_to_wishlist_value | |||||
conversion_spend_credits | |||||
conversion_spend_credits_value | |||||
conversion_rate | |||||
conversion_rate_value | |||||
conversion_start_trial | |||||
conversion_start_trial_value | |||||
conversion_list_view | |||||
conversion_list_view_value | |||||
custom_event_1 | |||||
custom_event_1_value | |||||
custom_event_2 | |||||
custom_event_2_value | |||||
custom_event_3 | |||||
custom_event_3_value | |||||
custom_event_4 | |||||
custom_event_4_value | |||||
custom_event_5 | |||||
custom_event_5_value | |||||
attachment_frequency | YES | NO | YES | YES. Available from 1st January 2021 | YES |
attachment_uniques | |||||
frequency | |||||
uniques | |||||
total_reach | |||||
earned_reach |
Example for All Metrics
curl -H "Authorization: Bearer meowmeow" \
"https://adsapi.snapchat.com/v1/campaigns/2bbaa6e3-4ddb-4358-9efe-48334952f4aa/stats?breakdown=adsquad&fields=android_installs,avg_screen_time_millis,attachment_frequency,attachment_quartile_1,attachment_quartile_2,attachment_quartile_3,attachment_total_view_time_millis,attachment_uniques,attachment_view_completion,frequency,impressions,ios_installs,quartile_1,quartile_2,quartile_3,spend,swipe_up_percent,swipes,total_installs,uniques,view_completion,screen_time_millis&granularity=DAY&start_time=2016-10-24T07:00:00.000-00:00&end_time=2016-10-26T07:00:00.000-00:00"
{
"request_status": "SUCCESS",
"request_id": "5813ccf400ff07b016a837c09f0001737e616473617069736300016275696c642d65373832323966352d73746174732d322d7465737400010133",
"timeseries_stats": [
{
"sub_request_status": "SUCCESS",
"timeseries_stat": {
"id": "2bbaa6e3-4ddb-4358-9efe-48334952f4aa",
"type": "CAMPAIGN",
"start_time": "2016-10-24T07:00:00.000Z",
"end_time": "2016-10-26T07:00:00.000Z",
"breakdown_stats": {
"adsquad": [
{
"id": "134aeb99-6552-4f1d-b7a6-82b9813fd079",
"type": "AD_SQUAD",
"granularity": "DAY",
"start_time": "2016-10-24T07:00:00.000Z",
"end_time": "2016-10-26T07:00:00.000Z",
"timeseries": [
{
"start_time": "2016-10-24T07:00:00.000Z",
"end_time": "2016-10-25T07:00:00.000Z",
"stats": {
"impressions": 18294,
"swipes": 0,
"quartile_1": 7489,
"quartile_2": 2595,
"quartile_3": 1964,
"view_completion": 1635,
"attachment_quartile_1": 0,
"attachment_quartile_2": 0,
"attachment_quartile_3": 0,
"attachment_view_completion": 0,
"attachment_total_view_time_millis": 0,
"frequency": 1.0014,
"avg_screen_time_millis": 1832,
"swipe_up_percent": 0,
"attachment_frequency": 0,
"attachment_avg_view_time_millis": 0,
"uniques": 18268,
"attachment_uniques": 0,
"ios_installs": 0,
"android_installs": 0,
"total_installs": 0,
"spend": 144213617,
"screen_time_millis": 33876700
}
},
{
"start_time": "2016-10-25T07:00:00.000Z",
"end_time": "2016-10-26T07:00:00.000Z",
"stats": {
"impressions": 15377,
"swipes": 0,
"quartile_1": 6345,
"quartile_2": 2185,
"quartile_3": 1596,
"view_completion": 1324,
"attachment_quartile_1": 0,
"attachment_quartile_2": 0,
"attachment_quartile_3": 0,
"attachment_view_completion": 0,
"attachment_total_view_time_millis": 0,
"frequency": 1.0011,
"avg_screen_time_millis": 1828,
"swipe_up_percent": 0,
"attachment_frequency": 0,
"attachment_avg_view_time_millis": 0,
"uniques": 15360,
"attachment_uniques": 0,
"ios_installs": 0,
"android_installs": 0,
"total_installs": 0,
"spend": 120978178,
"screen_time_millis": 28547600
}
}
]
}
}
Get Ad Account Stats
curl "https://adsapi.snapchat.com/v1/adaccounts/22335ba6-7558-4100-9663-baca7adff5f2/stats?granularity=TOTAL&fields=spend" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b24d9c00ff0d85622341e7c60001737e616473617069736300016275676c642b34326313636139312d332d31312d390001010d",
"total_stats": [
{
"sub_request_status": "success",
"total_stat": {
"id": "22335ba6-7558-4100-9663-baca7adff5f2",
"type": "AD_ACCOUNT",
"granularity": "TOTAL",
"stats": {
"spend": 89196290
},
"finalized_data_end_time": "2019-08-29T03:00:00.000-07:00"
}
}
]
}
This endpoint retrieves the spend metric for the specified Ad Account, the spend metric is the only metric available for the ad account entity.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Get Campaign Stats
curl "https://adsapi.snapchat.com/v1/campaigns/92e1c28a-a331-45b4-8c26-fd3e0eea8c39/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b24d9c00ff0d85622341e7c60001737e616473617069736300016275696c642d34326333636139312d312d31312d390001010d",
"total_stats": [
{
"sub_request_status": "success",
"total_stat": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
}
]
}
This endpoint retrieves stats for the specified Campaign.
HTTP Request
GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/stats
Parameters
Parameter | Default | Description |
---|---|---|
campaign_id | Campaign ID |
Get Ad Squad Stats
curl "https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b24e5200ff0225cdf221e6c90001737e616473617069736300016275696c642d34326333636139312d312d31312d3900010106",
"total_stats": [
{
"sub_request_status": "success",
"total_stat": {
"id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"type": "AD_SQUAD",
"granularity": "TOTAL",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
}
]
}
This endpoint retrieves stats for the specified Ad Squad.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/stats
Parameters
Parameter | Default | Description |
---|---|---|
adsquad_id | Ad Squad ID |
Get Ad Stats
curl "https://adsapi.snapchat.com/v1/ads/e8d6217f-32ab-400f-9e54-39a86a7963e4/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b24ec400ff0b0a2104182f430001737e616473617069736300016275696c642d34326333636139312d312d31312d390001010f",
"total_stats": [
{
"sub_request_status": "success",
"total_stat": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"type": "AD",
"granularity": "TOTAL",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
}
]
}
This endpoint retrieves stats for the specified Ad.
HTTP Request
GET https://adsapi.snapchat.com/v1/ads/{ad_id}/stats
Parameters
Parameter | Default | Description |
---|---|---|
ad_id | Ad ID |
Reporting Insights and Dimensions
Delivery Insights can help you understand who viewed, engaged, and took action on your ads. These insights across demographic, location, device, and interest categories can help inform optimization and increase overall campaign efficiency. Insights can be pulled for specific campaigns, ad squads, or ads; insights can also use breakdowns for multiple campaigns, ad squads, or ads at once.
- Delivery Insights are estimated to protect user privacy. They are meant to provide directional guidance on audience performance.
- Delivery Insights are only availble on days when there are at least 30 impressions.
- Delivery Insights are only available from 1 January 2020. DAY, TOTAL, and LIFETIME granularities are supported, the HOUR granularity is not available for delivery insights. Some conversion reporting metrics are available from 1 May 2020.
- Delivery insights for the combination of Country and Operating System are available from 24 October 2022 onwards.
Dimensions
You can get reporting insights based on different geographic, demographic, interest-based, and device-based dimensions. You can only query one dimension at a time unless you are querying age & gender which may be combined. Some of the dimensions (region/dma/make) only support Delivery metrics, for these dimensions it’s not possible to fetch conversion metrics.
Using the report_dimension
query string parameter you can see Snapchat metrics based on a number of new dimensions
Category | API Dimension (report_dimension) | Conditions | Metrics availability |
---|---|---|---|
Geo | country | Metrics broken down by ISO country code | Delivery/Conversion |
country,os | Metrics broken down by ISO country code and Device Operating System* | Delivery | |
region | Metrics broken down by ISO country code (US only) | Delivery | |
dma | Metrics broken down by ISO country code (US only) | Delivery | |
Demographic | gender | Metrics broken down by gender | Delivery/Conversion |
age | Metrics broken down by age buckets | Delivery/Conversion | |
age,gender | Metrics broken down by age and gender | Delivery/Conversion | |
Device | os | Device Operating System | Delivery/Conversion |
os,country | Metrics broken down by Device Operating System and ISO country code (US only)* | Delivery | |
make | Device Make | Delivery | |
Interest | lifestyle_category | Metrics broken down by interest category (Snapchat Lifestyle Category) | Delivery |
*Country/OS metrics breakdown is available from 24 October 2022
Metrics
You may pass these metrics as a comma separated list for the fields
query parameter. Conversion metrics support attribution windows, swipe/view variants, and value metrics in local microcents. Note that conversion metrics are not available for the dimensions lifestyle_category
, region
,dma
or make
.
Delivery Metrics
Metric | API field | Description |
---|---|---|
Paid Impressions | impressions | Impression Count |
Swipe Ups | swipes | Swipe-Up Count |
25% Quartile | quartile_1 | Video Views to 25% |
50% Quartile | quartile_2 | Video Views to 50% |
75% Quartile | quartile_3 | Video Views to 75% |
Completions | view_completion | Video Views to completion |
Spend | spend | Amount Spent (micro-currency) |
Video Views | video_views | The total number of impressions that meet the qualifying video view criteria of at least 2 seconds of consecutive watch time or a swipe up action on the Top Snap |
25% Attachment Quartile | attachment_quartile_1 | Long Form Video Views to 25% |
50% Attachment Quartile | attachment_quartile_2 | Long Form Video Views to 50% |
75% Attachment Quartile | attachment_quartile_3 | Long Form Video Views to 75% |
Attachment Completions | attachment_view_completion | Long Form Video Views to completion |
Attachment View Time | attachment_total_view_time_millis | Total Attachment View Time (milli-seconds) |
Attachment Video Views | attachment_video_views | Long Form Video Attachment Views |
Story Opens | story_opens | # of times users tapped on the ad tile in the feed to view the Story Ad |
Story Completes | story_completes | # of times users viewed through to the last Snap of your Story Ad |
Shares | shares | # of times lens/filter was shared in a Chat or Story |
Saves | saves | # of times lens/filter was saved to Memories |
Conversion Metrics
Metric | API field | Description |
---|---|---|
Installs | total_installs | Total # of App Installs |
Purchases | conversion_purchases | # of attributed “PURCHASE” conversion events** |
Purchase Value | conversion_purchases_value | Value of attributed “PURCHASE” conversion events (microcurrency in Ad Account’s currency)** |
Saves | conversion_save | # of attributed “SAVE” conversion events** |
Start Checkout | conversion_start_checkout | # of attributed “START_CHECKOUT” conversion events** |
Add To Cart | conversion_add_cart | # of attributed “ADD_CART” conversion events** |
View Content | conversion_view_content | # of attributed “VIEW_CONTENT” conversion events** |
Add Billing | conversion_add_billing | # of attributed “ADD_BILLING” conversion events** |
Sign Ups | conversion_sign_ups | # of attributed “SIGN_UP” conversion events** |
Searches | conversion_searches | # of attributed “SEARCH” conversion events** |
Level Completes | conversion_level_completes | # of attributed “LEVEL_COMPLETE” conversion events** |
App Opens | conversion_app_opens | # of attributed “APP_OPEN” conversion events** |
Page Views | conversion_page_views | # of attributed “PAGE_VIEW” conversion events** |
Subscribes | conversion_subscribe | # of attributed “SUBSCRIBE” conversion events++ |
Ad Clicks | conversion_ad_click | # of attributed “CONVERSION_AD_CLICK” conversion events++ |
Ad Views | conversion_ad_view | # of attributed “CONVERSION_AD_VIEW” conversion events++ |
Completed Tutorials | conversion_complete_tutorial | # of attributed “CONVERSION_COMPLETE_TUTORIAL” conversion events++ |
Invites Sent | conversion_invite | # of attributed “CONVERSION_INVITE” conversion events++ |
Logins | conversion_login | # of attributed “CONVERSION_LOGIN” conversion events++ |
Shares | conversion_share | # of attributed “CONVERSION_SHARE” conversion events++ |
Reservations | conversion_reserve | # of attributed “CONVERSION_RESERVE” conversion events++ |
Achievements Unlocked | conversion_achievement_unlocked | # of attributed “CONVERSION_ACHIEVEMENT_UNLOCKED” conversion events++ |
Adds to Wishlist | conversion_add_to_wishlist | # of attributed “CONVERSION_ADD_TO_WISHLIST” conversion events++ |
Credits Spent | conversion_spend_credits | # of attributed “CONVERSION_SPEND_CREDITS” conversion events++ |
Rates Submitted | conversion_rate | # of attributed “CONVERSION_RATE” conversion events++ |
Trial Starts | conversion_start_trial | # of attributed “CONVERSION_START_TRIAL” conversion events++ |
Lists Viewed | conversion_list_view | # of attributed “LIST_VIEW” conversion events++ |
Store Visits | conversion_visit | # of attributed “VISIT” conversion events++ |
Custom Event 1 | custom_event_1 | # of attributed “CUSTOM_EVENT_1” conversion events++ |
Custom Event 2 | custom_event_2 | # of attributed “CUSTOM_EVENT_2” conversion events++ |
Custom Event 3 | custom_event_3 | # of attributed “CUSTOM_EVENT_3” conversion events++ |
Custom Event 4 | custom_event_4 | # of attributed “CUSTOM_EVENT_4” conversion events++ |
Custom Event 5 | custom_event_5 | # of attributed “CUSTOM_EVENT_5” conversion events++ |
** This conversion metric is available from 1st January 2020 when using action_report_time=conversion and 1st May 2020 when using action_report_time=impression ++ This conversion metric is available from 1st of May 2020 for both action_report_time=conversion and action_report_time=impression
Insights by GEO
curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/stats/?granularity=TOTAL&breakdown=campaign&fields=impressions,swipes,conversion_purchases&report_dimension=country&start_time=2020-01-25T00:00:00-08:00&end_time=2020-01-26T00:00:00-08:00&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e6bee5400ff0aaf11217b24900001737e616473617069736300016275696c642d31636430373832652d312d3333342d3000010128",
"total_stats": [
{
"sub_request_status": "SUCCESS",
"total_stat": {
"id": "22225ba6-7559-4000-9663-bace8adff5f2",
"type": "AD_ACCOUNT",
"granularity": "TOTAL",
"swipe_up_attribution_window": "28_DAY",
"view_attribution_window": "1_DAY",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-26T00:00:00.000-08:00",
"finalized_data_end_time": "2020-03-13T00:00:00.000-07:00",
"breakdown_stats": {
"campaign": [
{
"id": "88821981-14be-4315-9832-278b27004d68",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-26T00:00:00.000-08:00",
"dimension_stats": [
{
"impressions": 23433,
"swipes": 141,
"country": "au",
"conversion_purchases": 3
}
]
},
{
"id": "8079bbff-8a7b-4548-8556-d726461da248",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-26T00:00:00.000-08:00",
"dimension_stats": [
{
"impressions": 19970,
"swipes": 488,
"country": "us",
"conversion_purchases": 4
}
]
},
{
"id": "828f739c-7f32-4013-9a92-58c6495e9438",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-26T00:00:00.000-08:00",
"dimension_stats": [
{
"impressions": 46068,
"swipes": 74,
"country": "fr",
"conversion_purchases": 5
}
]
}
]
},
"split_results": []
}
}
]
}
This retrieves insights for country broken down to Campaign level using report_dimension=country
.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats
Parameters
Parameter | Default | Description |
---|---|---|
ad-account-id | Ad ID | |
report_dimension | The desired Report Dimension |
Insights by DEMO
curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/stats/?granularity=TOTAL&breakdown=campaign&fields=impressions,swipes,conversion_purchases&report_dimension=gender,age&start_time=2020-01-25T00:00:00-08:00&end_time=2020-01-28T00:00:00-08:00&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e6bf19f00ff068ca7c50849650001737e616473617069736300016275696c642d31636430373832652d312d3333342d3000010121",
"total_stats": [
{
"sub_request_status": "SUCCESS",
"total_stat": {
"id": "22225ba6-7559-4000-9663-bace8adff5f2",
"type": "AD_ACCOUNT",
"granularity": "TOTAL",
"swipe_up_attribution_window": "28_DAY",
"view_attribution_window": "1_DAY",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-28T00:00:00.000-08:00",
"finalized_data_end_time": "2020-03-13T00:00:00.000-07:00",
"breakdown_stats": {
"campaign": [
{
"id": "88921981-14be-4315-9832-278b27004d68",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-28T00:00:00.000-08:00",
"dimension_stats": [
{
"impressions": 18719,
"swipes": 63,
"age_bucket": "18-20",
"gender": "male",
"conversion_purchases": 1
},
{
"impressions": 12184,
"swipes": 37,
"age_bucket": "21-24",
"gender": "male",
"conversion_purchases": 0
},
{
"impressions": 25197,
"swipes": 113,
"age_bucket": "25-34",
"gender": "male",
"conversion_purchases": 1
},
{
"impressions": 12363,
"swipes": 147,
"age_bucket": "35+",
"gender": "male",
"conversion_purchases": 1
}
]
},
{
"id": "82d35332-00e3-4414-a125-922053d2c358",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-28T00:00:00.000-08:00",
"dimension_stats": [
{
"impressions": 12438,
"swipes": 11,
"age_bucket": "18-20",
"gender": "male",
"conversion_purchases": 0
},
{
"impressions": 23894,
"swipes": 21,
"age_bucket": "21-24",
"gender": "male",
"conversion_purchases": 0
},
{
"impressions": 31837,
"swipes": 51,
"age_bucket": "25-34",
"gender": "male",
"conversion_purchases": 0
},
{
"impressions": 5277,
"swipes": 24,
"age_bucket": "35+",
"gender": "male",
"conversion_purchases": 0
}
]
},
{
"id": "82c7b838-c084-4c3e-91ae-f96aa4e89008",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-28T00:00:00.000-08:00",
"dimension_stats": [
{
"impressions": 27826,
"swipes": 44,
"age_bucket": "18-20",
"gender": "male",
"conversion_purchases": 1
},
{
"impressions": 24745,
"swipes": 64,
"age_bucket": "21-24",
"gender": "male",
"conversion_purchases": 3
},
{
"impressions": 31849,
"swipes": 163,
"age_bucket": "25-34",
"gender": "male",
"conversion_purchases": 1
},
{
"impressions": 23918,
"swipes": 212,
"age_bucket": "35+",
"gender": "male",
"conversion_purchases": 2
}
]
}
]
},
"split_results": []
}
}
]
}
This retrieves insights for gender and age broken down to Campaign level, using report_dimension=gender,age
.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats
Parameters
Parameter | Default | Description |
---|---|---|
ad-account-id | Ad ID | |
report_dimension | The desired Report Dimension |
Reporting Insights: Dimension and Pivots
On the 20th of March 2020 we announced the deprecation of the dimension
and pivots
parameters, please ensure that you have switched to using report_dimension
by the 20th of June 2020. After the deprecation you will still be able to use dimension
and pivots
to retrieve data finalized prior to the 20th June 2020.
The new parameter report_dimension
is described in Reporting Insights and Dimensions.
Dimension and Pivots
You can get reporting insights based on different dimensions like GEO, DEMO, INTEREST and DEVICE by using the parameters dimension
and pivots
. Within each dimension, data can be broken down by different pivots. You can only query one dimension at a time. For insights breakdown, only LIFETIME granularity is supported.
Dimension | Pivot | Required/Optional | Conditions |
---|---|---|---|
GEO | country | Yes | None |
region | No | dma has to be queried with region | |
dma | No | dma has to be queried with region | |
DEMO | gender | No | At least one of gender or age_bucket has to be specified if dimension is DEMO |
age_bucket | No | At least one of gender or age_bucket has to be specified if dimension is DEMO | |
INTEREST | interest_category_id | Yes | None |
interest_category_name | No | None | |
DEVICE | operating_system | Yes | None |
make | No | model has to be queried with make | |
model | No | model has to be queried with make |
The fields that can be broken down by dimenssion and pivots are:
Field | Description |
---|---|
impressions | Impression Count |
impression_composition | The percent of impressions served to the insights category |
uniques | # of unique impressions |
unique_composition | The percent of uniques served to the insights category |
spend | Amount spent (microcurrency) |
swipes | Swipe up Count |
Attribution windows
Attribution window is the time period in which a conversion will be counted after a user sees an ad. By default, Snap’s attribution windows are 28 days post-swipe and 1 day post-view.
Metrics and their variants
Metric | Swipe variant | View variant |
---|---|---|
total_installs | total_installs_swipe_up | total_installs_view |
android_installs | android_installs_swipe_up | android_installs_view |
ios_installs | ios_installs_swipe_up | ios_installs_view |
conversion_purchases | conversion_purchases_swipe_up | conversion_purchases_view |
conversion_purchases_value | conversion_purchases_value_swipe_up | conversion_purchases_value_view |
conversion_save | conversion_save_swipe_up | conversion_save_view |
conversion_start_checkout | conversion_start_checkout_swipe_up | conversion_start_checkout_view |
conversion_add_cart | conversion_add_cart_swipe_up | conversion_add_cart_view |
conversion_view_content | conversion_view_content_swipe_up | conversion_view_content_view |
conversion_add_billing | conversion_add_billing_swipe_up | conversion_add_billing_view |
conversion_sign_ups | conversion_sign_ups_swipe_up | conversion_sign_ups_view |
conversion_searches | conversion_searches_swipe_up | conversion_searches_view |
conversion_level_completes | conversion_level_completes_swipe_up | conversion_level_completes_view |
conversion_app_opens | conversion_app_opens_swipe_up | conversion_app_opens_view |
conversion_page_views | conversion_page_views_swipe_up | conversion_page_views_view |
conversion_subscribe | conversion_subscribe_swipe_up | conversion_subscribe_view |
conversion_ad_click | conversion_ad_click_swipe_up | conversion_ad_click_view |
conversion_ad_view | conversion_ad_view_swipe_up | conversion_ad_view_view |
conversion_complete_tutorial | conversion_complete_tutorial_swipe_up | conversion_complete_tutorial_view |
conversion_invite | conversion_invite_swipe_up | conversion_invite_view |
conversion_login | conversion_login_swipe_up | conversion_login_view |
conversion_share | conversion_share_swipe_up | conversion_share_view |
conversion_reserve | conversion_reserve_swipe_up | conversion_reserve_view |
conversion_achievement_unlocked | conversion_achievement_unlocked_swipe_up | conversion_achievement_unlocked_view |
conversion_add_to_wishlist | conversion_add_to_wishlist_swipe_up | conversion_add_to_wishlist_view |
conversion_spend_credits | conversion_spend_credits_swipe_up | conversion_spend_credits_view |
conversion_rate | conversion_rate_swipe_up | conversion_rate_view |
conversion_start_trial | conversion_start_trial_swipe_up | conversion_start_trial_view |
conversion_list_view | conversion_list_view_swipe_up | conversion_list_view_view |
custom_event_1 | custom_event_1_swipe_up | custom_event_1_view |
custom_event_2 | custom_event_2_swipe_up | custom_event_2_view |
custom_event_3 | custom_event_3_swipe_up | custom_event_3_view |
custom_event_4 | custom_event_4_swipe_up | custom_event_4_view |
custom_event_5 | custom_event_5_swipe_up | custom_event_5_view |
Allowed combinations of attribution windows
View window | Swipe window 1_DAY | Swipe window 7_DAY | Swipe window 28_DAY |
---|---|---|---|
None | Allowed | Allowed | Allowed |
1_HOUR | Allowed | Allowed | Allowed |
3_HOUR | Allowed | Allowed | Allowed |
6_HOUR | Allowed | Allowed | Allowed |
1_DAY | Allowed | Allowed | Allowed |
7_DAY | Not Allowed | Allowed | Allowed |
28_DAY | Not Allowed | Not Allowed | Allowed |
Attribution windows example
curl "https://adsapi.snapchat.com/v1/campaigns/04dd5e26-7156-4e07-b2b8-2911ae3aaccc/stats?granularity=DAY&fields=impressions,spend,conversion_add_cart,conversion_add_cart_swipe_up,conversion_add_cart_view,conversion_purchases,conversion_purchases_swipe_up,conversion_purchases_view&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&start_time=2017-11-10T00:00:00-08:00&end_time=2017-11-12T00:00:00-08:00"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5a1e176f00ff09ef429913ea970001737e616473617069736300016275696c642d65336335336136322d312d3132312d31",
"timeseries_stats": [
{
"sub_request_status": "SUCCESS",
"timeseries_stat": {
"id": "04dd5e26-7156-4e07-b2b8-2911ae3aaccc",
"type": "CAMPAIGN",
"granularity": "DAY",
"swipe_up_attribution_window": "28_DAY",
"view_attribution_window": "7_DAY",
"start_time": "2017-11-10T00:00:00.000-08:00",
"end_time": "2017-11-12T00:00:00.000-08:00",
"finalized_data_end_time": "2017-11-27T00:00:00.000-08:00",
"timeseries": [
{
"start_time": "2017-11-10T00:00:00.000-08:00",
"end_time": "2017-11-11T00:00:00.000-08:00",
"stats": {
"impressions": 63027,
"spend": 190136020,
"conversion_purchases": 13,
"conversion_purchases_swipe_up": 6,
"conversion_purchases_view": 7,
"conversion_add_cart": 20,
"conversion_add_cart_swipe_up": 8,
"conversion_add_cart_view": 12
}
},
{
"start_time": "2017-11-11T00:00:00.000-08:00",
"end_time": "2017-11-12T00:00:00.000-08:00",
"stats": {
"impressions": 74153,
"spend": 200905774,
"conversion_purchases": 10,
"conversion_purchases_swipe_up": 3,
"conversion_purchases_view": 7,
"conversion_add_cart": 20,
"conversion_add_cart_swipe_up": 5,
"conversion_add_cart_view": 15
}
}
]
}
}
]
}
This retrieves insights broken down by specified attribution windows.
Reporting for Dynamic Product Ads (DPA)
Snapchat now offers a reporting API endpoint so that advertisers can retrieve product-level reporting for Dynamic Product Ads. This report allows advertisers to understand how their campaigns, ad squads, ads delivered & performed for individual products. Reports can only be pulled with a 1 day date range for TOTAL granularity. There are two types of reports that can be retrieved. These are the full reports using the async API and the top-k report using the regular API.
Supported Breakdowns
- Results can be broken down by campaign, ad squad, and ad
- Results can be broken down by date or total
Supported Metrics
- product_impressions (number of impressions for a product ID)
- swipes
- spend (microcents local currency)
Report Requirements
- Reports must be 1 day in length
- Start & End Date must be specified
Full reports for DPA (Async)
Due to the size of reports, DPA reporting runs on Snapchat’s asynchronous API and returns a file for the full DPA breakdown. The API call to the stats endpoint for a DPA report returns a report run ID. This run ID can be used to make a subsequent call to the stats_report endpoint to check its status. Upon completion, a signed URL is generated to download the report as a CSV; this CSV has a time to live of 24 hours.
Stats request - Step 1
curl "https://adsapi.snapchat.com/v1/adaccounts/<ad_acct_id>/stats?breakdown=campaign&granularity=TOTAL&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY&start_time=2020-03-17T00:00:00-07:00&end_time=2020-03-25T00:00:00-07:00&fields=product_impressions,swipes,spend,total_installs,conversion_purchases&position_stats=false&platform_stats=false&report_dimension=product&omit_empty=true&async=true&async_format=csv" -H "Authorization: Bearer meowmeowmeow"
{
"request_status": "SUCCESS",
"request_id": "<ID>",
"async_stats_reports": [
{
"sub_request_status": "SUCCESS",
"async_stats_report": {
"report_run_id": "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6"
}
}
]
}
Additional Request Parameters
These are the specific request parameters necessary to call the DPA Async report API
Attribute | Values |
---|---|
report_dimension | product |
async | true |
async_format | csv |
Response - async_stats_report Object
Attribute | Description | Values |
---|---|---|
report_run_id | the ID of your reporting task | eg: “ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6” |
async_status | The current status of the reporting task. Once this changes to COMPLETED, the result field will be populated with the URL for the report. | RUNNING, COMPLETED |
result | This contains the URL of the report file | eg: “https://data-transfer.snapads.com/async-report/dpa_full/ASYNC_STATS:0efa41e1-5087-48af-8dbc-2cf8aefasdf66e6/4a6csdf1-3234-484b-b2cf-eeb6f1a63c3f.csv” |
CSV request - Step 2
curl "https://adsapi.snapchat.com/v1/adaccounts/<ad_acct_id>/stats_report?report_run_id=ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6" -H "Authorization: Bearer meowmeowmeow"
Report is running
{
"request_status": "SUCCESS",
"request_id": "<ID>",
"async_stats_reports": [
{
"sub_request_status": "SUCCESS",
"async_stats_report": {
"report_run_id": "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6",
"async_status": "RUNNING",
"result": ""
}
}
]
}
Report is completed
{
"request_status": "SUCCESS",
"request_id": "<ID>",
"async_stats_reports": [
{
"sub_request_status": "SUCCESS",
"async_stats_report": {
"report_run_id": "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6",
"async_status": "COMPLETED",
"result": "https://data-transfer.snapads.com/async-report/dpa_full/ASYNC_STATS:0efa41e1-5087-48af-8dbc-2cf8aefasdf66e6/4a6csdf1-3234-484b-b2cf-eeb6f1a63c3f.csv"
}
}
]
}
Top-K report for DPA
To support UI reporting and understand the performance of DPA among products with the highest level of spend, Snapchat supports a Top-K report, which will return the top 50 products per entity by impression volume (Campaign, Ad Set, and Ad). This API is similar to the standard reporting API used for non DPA ads.
Additional Request Parameters
These are the specific request parameters necessary to call the DPA Async report API
Attribute | Values |
---|---|
report_dimension | product_topk |
curl "https://adsapi.snapchat.com/v1/adaccounts/<ad_acct_id>/stats?breakdown=campaign&granularity=TOTAL&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY&start_time=2020-03-17T00:00:00-07:00&end_time=2020-03-25T00:00:00-07:00&fields=product_impressions,swipes,spend,total_installs,conversion_purchases&position_stats=false&platform_stats=false&report_dimension=product_topk&omit_empty=true" -H "Authorization: Bearer meowmeowmeow"
{
"request_status": "SUCCESS",
"request_id": "5fb4467d00ff07d2b1b1968d810001737e616473617069736300016275696c642d36393939316436622d312d3430332d3100010142",
"total_stats": [
{
"sub_request_status": "SUCCESS",
"total_stat": {
"id": "<ID>",
"type": "AD_ACCOUNT",
"granularity": "TOTAL",
"swipe_up_attribution_window": "28_DAY",
"view_attribution_window": "1_DAY",
"start_time": "2020-10-27T00:00:00.000-07:00",
"end_time": "2020-10-29T00:00:00.000-07:00",
"finalized_data_end_time": "2020-11-17T00:00:00.000-08:00",
"breakdown_stats": {
"campaign": [
{
"id": "<CAMPAIGN_ID>",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"start_time": "2020-10-27T00:00:00.000-07:00",
"end_time": "2020-10-29T00:00:00.000-07:00",
"dimension_stats": [
{
"product_id": "56e39d8f1b0dd675f10e0131",
"product_impressions": 84051
},
{
"product_id": "577dfc15dac4a378150ebab0",
"product_impressions": 55271
},
{
"product_id": "5694f07db06a78118dd2bbae",
"product_impressions": 47643
},
{
"product_id": "56dff400cec25a1a9e1271cd",
"product_impressions": 26599
},
{
"product_id": "56eebe757505925c618e9807",
"product_impressions": 23737
},
{
"product_id": "569cbb6f16805211bb1f7750",
"product_impressions": 21171
},
{
"product_id": "57a6fad104e0d075a6084059",
"product_impressions": 19274
},
{
"product_id": "57ab01b93999d9602c743b8e",
"product_impressions": 12256
},
{
"product_id": "57ad3c3fd227704b8bab09dc",
"product_impressions": 12248
},
{
"product_id": "57a6c97c5bd8ec7787ea328f",
"product_impressions": 11340
},
{
"product_id": "569f56793fe3625b0cf56bd9",
"product_impressions": 7433
},
{
"product_id": "56e14676ae8c93398a13a7d3",
"product_impressions": 6597
},
{
"product_id": "56f24379f5f899740ec4c0b5",
"product_impressions": 6438
},
{
"product_id": "575645a524a8f27640d3d40c",
"product_impressions": 6419
},
{
"product_id": "5700b35e5581e05ce0b4adc3",
"product_impressions": 6056
},
{
"product_id": "576130685d3faf6218fd8dac",
"product_impressions": 5701
},
{
"product_id": "579eba20a037085566e39683",
"product_impressions": 1980
},
{
"product_id": "57adae01b1ce26244dd4012c",
"product_impressions": 1707
},
{
"product_id": "57a02216e3ada7734f02b275",
"product_impressions": 1185
},
{
"product_id": "579b220904af45576fae20a3",
"product_impressions": 1083
},
{
"product_id": "56b1adcdac5bc550738df9fb",
"product_impressions": 857
},
{
"product_id": "57623c6d823409625004be5e",
"product_impressions": 736
},
{
"product_id": "57b14c09689ce95b71558fff",
"product_impressions": 671
},
{
"product_id": "5779ced99bfad279a9783889",
"product_impressions": 573
},
{
"product_id": "56c29339a3537416ae4b7822",
"product_impressions": 556
}
...
]
}
]
},
"split_results": []
}
}
]
}
Viewability Metrics
Viewability Metrics are available given the following criteria;
- Metrics are available from the 1 April 2021
- Available in all granularities (HOUR, DAY, TOTAL, LIFETIME)
- Metrics cannot be broken down by Insights
- Story Ads are not covered by these metrics
Metrics
Metric | API field | Description |
---|---|---|
Viewable Impressions | viewable_impressions | Number of impressions that were 100% viewable on a user’s screen for 1 second for display ads or 2 seconds for video ads. |
Non-Viewable Impressions | non_viewable_impressions | Number of impressions that did not meet the criteria for a viewable impression |
Viewable Rate | viewable_rate | The percentage of the time that your paid Snap Ad impression met the qualifying viewable impression criteria |
Measured Impressions | measured_impressions | Number of impressions that were measured for viewability |
Gross Impressions | gross_impressions | Total impressions delivered, this includes invalid traffic which is excluded from spend & all other delivery metrics. |
Paid Impressions | paid_impressions | The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter’s viewing session. These impressions are net of invalid traffic. |
Audience filters
Audience filters were deprecated on 1 February 2023, this reporting information is preserved for Audience Filters created prior to the deprecation.
Field | Description | Availability |
---|---|---|
paid_impressions | The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter’s viewing session | Real Time |
earned_impressions | The number of times your ad was viewed after being shared by a Snapchatter via Chat or Stories | Within 24 hours |
shares | The number of times your ad was shared via Chat or Stories | Real Time |
saves | The number of times your ad was saved to Memories | Real Time |
spend | The total spend delivered in microcurrency | Real Time |
uniques | The number of unique paid impressions | Within 24 hours |
Stats are available at the Ad, Ad Squad and Campaign levels and are supported for all granularities: HOUR, DAY, TOTAL and LIFETIME.
curl "https://adsapi.snapchat.com/v1/adsquads/419d41d7-e4d4-4c13-803c-55e140a0ec1c/stats?granularity=LIFETIME&fields=paid_impressions,shares,saves,spend,uniques,earned_impressions"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "59b9cde600ff04b518a3c18db20001737e616473617069736300016275696c642d31386433356533662d312d3130302d3100010148",
"lifetime_stats": [
{
"sub_request_status": "SUCCESS",
"lifetime_stat": {
"id": "419d41d7-e4d4-4c13-803c-55e140a0eb1c",
"type": "AD_SQUAD",
"granularity": "LIFETIME",
"stats": {
"uniques": 186219,
"spend": 247184000,
"earned_impressions": 196140,
"paid_impressions": 199290,
"shares": 5762,
"saves": 799
},
"start_time": "2016-09-26T00:00:00.000-07:00",
"end_time": "2017-09-13T00:00:00.000-07:00",
"finalized_data_end_time": "2017-09-13T00:00:00.000-07:00"
}
}
]
}
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{adsquad-id}/stats
Parameters
Parameter | Description |
---|---|
adsquad-id | Audience filter Ad squad ID |
Create Lead Gen Report
This request initiates a lead gen report for an Ad Account given the selected start time and end time, the request returns a Report id in the form of report_run_id
which is then used to retrieve the report itself.
Data collected via Lead Gen Ads is not stored for more than 30 days, this also means that the start time can’t be more than 30 days in the past.
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/leads_report?async_format=csv&start_time=2021-12-01T00:00:00-07:00&end_time=2021-12-14T00:00:00-07:00
The above command returns a report_run_id:
{
"request_status": "SUCCESS",
"request_id": "61b8c10a00ff08449824e366290001737e616473617069736300016275696c642d38333537336364642d312d3530332d3000010159",
"async_stats_reports": [
{
"sub_request_status": "SUCCESS",
"async_stats_report": {
"report_run_id": "ASYNC_STATS:2e480f4f-0c2a-463c-a883-841f88175449",
"async_status": "STARTED"
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/leads_report
Parameters
Parameter | Default value | Description |
---|---|---|
async_format | csv | |
start_time | Start time in ISO format | |
end_time | End time in ISO format |
Fetch Lead Gen Report
This request uses the report_run_id
in order to fetch the status of a report.
If the report is ready the request returns the URL of a list of leads in CSV format, the async_status
indicates whether the report is completed and ready to be downloaded. If the report is ready the value of the async_status
is COMPLETED, if the report is still running the async_status
will be RUNNING.
When a report is completed the url for downloading the data is found in the result attribute. This URL is valid for 48 hours.
curl "https://adsapi.snapchat.comv1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/leads_report?report_run_id=ASYNC_STATS:7766eab2-643e-4117-8b58-c9ee3fe854f3" \
-H "Authorization: Bearer meowmeowmeow"
Example #1 - Report in progress
{
"request_status": "SUCCESS",
"request_id": "61b8bf2d00ff07c8f092caf50b0001737e616473617069736300016275696c642d38333537336364642d312d3530332d3000010142",
"async_stats_reports": [
{
"sub_request_status": "SUCCESS",
"async_stats_report": {
"report_run_id": "ASYNC_STATS:7766eae2-643e-4117-8b58-c9ee3fe854f3",
"async_status": "RUNNING"
}
}
]
}
curl "https://adsapi.snapchat.comv1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/leads_report?report_run_id=ASYNC_STATS:7766eeb2-643e-4117-8b58-c9ee3fe854f3" \
-H "Authorization: Bearer meowmeowmeow"
Example #2 - Completed report
{
"request_status": "SUCCESS",
"request_id": "61b8bf2d00ff07c8f092caf50b0001737e616473617069736300016275696c642d38333537336364642d312d3530332d3000010142",
"async_stats_reports": [
{
"sub_request_status": "SUCCESS",
"async_stats_report": {
"report_run_id": "ASYNC_STATS:7766eeb2-643e-4117-8b58-c9ee3fe854f3",
"async_status": "COMPLETED",
"result": "https://data-transfer.snapads.com/async-report/native_lead/ASYNC_STATS:7766eeb2-643e-4117-8b58-c9ee3fe854f3/00ea875b-1645-4fe8-8825-aa7a351b260b.csv"
}
}
]
}
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/leads_report
Parameters
Parameter | Default value | Description |
---|---|---|
report_run_id | Report id | The Report id returned by API request to initiate a report |
Lead Gen Report
This is a list of fields in the Lead Gen Report and their properties.
Field Name | Type | Max Length | Required? | Description | Example |
---|---|---|---|---|---|
Date | Datetime | 17 | Yes | Date that lead was submitted. The timestamp is truncated to the beginning of the local day and the time is always “00:00:00” Format: “yyyy-MM-dd 00:00:00” |
2022-05-11 00:00:00 |
Ad Account Id | String | 36 | Yes | Ad account ID associated with the ad that generated the lead. Hyphen separated UUID string. | f0d4666f-9f60-4df7-94c8-423ca55b2a17 |
Campaign Id | String | 36 | Yes | Campaign ID associated with ad that generated the lead. Hyphen separated UUID string. | 033fe5aa-59b4-423d-8ab5-b7a7cf6c5242 |
Ad Set Id | String | 36 | Yes | Ad Set ID associated with ad that generated the lead. Hyphen separated UUID string. | ebad6081-f387-4bce-b6dc-9ea4d2cbefbc |
Ad Id | String | 36 | Yes | Ad ID associated with ad that generated the lead. Hyphen separated UUID string. | ca72035c-9f8d-409b-abee-5e2e0c943f9c |
First Name | String | Yes | First name of Snapchat User | Jane | |
Last Name | String | Yes | Last name of Snapchat User | Smith | |
Phone Number | String | Yes (Either Email Address or Phone Number) | ex: 818-555-1234, +13105558765 *Not all formatted the same |
818-555-1234 +13105558765 |
|
Email Address | String | Yes (Either Email Address or Phone Number) | Email address of Snapchat user | johndoe@gmail.com | |
Address Line 1 | String | No | Address of Snapchat user, Line 1 | 19330 25th Ave | |
Address Line 2 | String | No | Address of Snapchat user, Line 2 | Unit 3 | |
Address Level 1 | String | No | Address city or town | Seattle | |
Address Level 2 | String | No | Address state, province, or region | WA | |
Postal Code | String | No | Postal code of Snapchat user | 94012 | |
Birthday | Date | 10 | No | Snapchat user’s birthdate. Formatted “MM/DD/YYYY” | 05/20/1998 |
Job Title | String | No | Job title | Marketing Manager | |
Company Name | String | No | Company name | Snap, Inc. | |
Custom Field 1 | String | No | Can be one of the following based on the type of Custom Question: Single-select: key-value object that contains the answer that the user selected and “true”: {answer:true} Multi-select: key-value object that contains all of the answers that the user selected and “true”: {answer1:true, answer2: true, answer3: true, answer4:true} Short Answer: String that contains the answer that the user entered into the form. Date Widget: The date that the user entered in the format “MM/DD/YYYY” |
{Pizza:true} {Pizza:true, Sushi:true, Hamburgers:true} This is what I entered into the form 01/02/2022 |
|
Custom Field 2 | String | No | Can be one of the following based on the type of Custom Question: Single-select: key-value object that contains the answer that the user selected and “true”: {answer:true} Multi-select: key-value object that contains all of the answers that the user selected and “true”: {answer1:true, answer2: true, answer3: true, answer4:true} Short Answer: String that contains the answer that the user entered into the form. Date Widget: The date that the user entered in the format “MM/DD/YYYY” |
{Pizza:true} {Pizza:true, Sushi:true, Hamburgers:true} This is what I entered into the form 01/02/2022 |
|
Custom Field 3 | String | No | Can be one of the following based on the type of Custom Question: Single-select: key-value object that contains the answer that the user selected and “true”: {answer:true} Multi-select: key-value object that contains all of the answers that the user selected and “true”: {answer1:true, answer2: true, answer3: true, answer4:true} Short Answer: String that contains the answer that the user entered into the form. Date Widget: The date that the user entered in the format “MM/DD/YYYY” |
{Pizza:true} {Pizza:true, Sushi:true, Hamburgers:true} This is what I entered into the form 01/02/2022 |
|
Consent 1 | String | Disclaimers: 80 Answer: 5 Total: 86 |
No | Disclaimer in the consent section of the form and the user’s response. Data is a key-value string in the following format: disclaimer:answer “answer” will be “true” if the user consented and “false” if they did not consent. |
do you consent?:true https://www.example.com:false |
Consent 2 | String | Disclaimers: 80 Answer: 5 Total: 86 |
No | Disclaimer in the consent section of the form and the user’s response. Data is a key-value string in the following format: disclaimer:answer “answer” will be “true” if the user consented and “false” if they did not consent. |
do you consent?:true https://www.example.com:false |
Example Lead Gen Report
Here is an example Lead Gen Report .csv file. All the sample data is made-up; no actual user data is included.
Audit Logs
For certain entities you can retrieve change logs which allows you to see all the changes made to the entity. You should always use pagination when fetching change logs for an entity.
Entities supported right now are Campaign, AdSquad, Ad, Creative and Dynamic Templates. Change logs are only availabe from the 16 July 2019 and onwards.
Fetch the change logs for a Campaign
curl "https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/external_changelogs?limit=50" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5d2f4a2e00ff0b2d2797e383a20001737e616473617069736300016275696c642d32613361333938642d312d3237332d3100010126",
"paging": {},
"changelogs": [
{
"sub_request_status": "SUCCESS",
"changelog": {
"id": "f9fd14cf-1bb0-4592-beeb-9d7e358e746b",
"updated_at": "2019-07-17T16:17:30.194Z",
"created_at": "2019-07-17T16:17:30.194Z",
"name": "Badger Campaign - July 2019",
"action": "UPDATED",
"user_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
"email": "honey.badger@hooli.com",
"event_at": "2019-07-17T16:17:29.991Z",
"app_id": "87947032-5fbd-46a7-ba60-073ca8efefbb",
"app_name": "Honey badger App",
"entity_id": "dcc3f407-7049-47aa-8300-6cce946ed04e",
"entity_type": "CAMPAIGN",
"update_value_records": {
"status": {
"before_value": "\"ACTIVE\"",
"after_value": "\"PAUSED\""
}
}
}
},
{
"sub_request_status": "SUCCESS",
"changelog": {
"id": "3cd457c6-077d-4d4b-9647-73a97045e709",
"updated_at": "2019-07-17T15:54:59.955Z",
"created_at": "2019-07-17T15:54:59.955Z",
"name": "Badger Campaign - July 2019",
"action": "UPDATED",
"user_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
"email": "honey.badger@hooli.com",
"event_at": "2019-07-17T15:54:59.755Z",
"app_id": "87947032-5fbd-46a7-ba60-073ca8efefbb",
"app_name": "Honey badger App",
"entity_id": "dcc3f407-7049-47aa-8300-6cce946ed04e",
"entity_type": "CAMPAIGN",
"update_value_records": {
"end_time": {
"after_value": "1563580491000"
}
}
}
}
]
}
This endpoint retrieves the latest 50 changes to the Campaign entity.
HTTP Request
GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/external_changelogs?limit=50
Parameters
Parameter | Default | Description |
---|---|---|
campaign_id | Campaign ID |
Fetch the change logs for an AdSquad
curl "https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/external_changelogs?limit=50" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5d2f495400ff05e47e72eb0f710001737e616473617069736300016275696c642d32613361333938642d312d3237332d310001011a",
"paging": {},
"changelogs": [
{
"sub_request_status": "SUCCESS",
"changelog": {
"id": "ae2161fb-737a-4f3c-9a3d-e6c83d9c9e30",
"updated_at": "2019-07-17T15:58:40.150Z",
"created_at": "2019-07-17T15:58:40.150Z",
"name": "Badger Ad Squad - July 2019",
"action": "UPDATED",
"user_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
"email": "honey.badger@hooli.com",
"event_at": "2019-07-17T15:58:39.872Z",
"app_id": "e9bdc78d-81fa-4470-8f6b-2a3d6f0487b3",
"app_name": "Honey badger App",
"entity_id": "c478150d-b177-4ecb-938d-f5157375f937",
"entity_type": "AD_SQUAD",
"update_value_records": {
"bid_micro": {
"before_value": "868402",
"after_value": "876174"
}
}
}
}
]
}
This endpoint retrieves the latest 50 changes to the AdSquad entity.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/external_changelogs?limit=50
Parameters
Parameter | Default | Description |
---|---|---|
adsquad_id | AdSquad ID |
Fetch the change logs for an Ad
curl "https://adsapi.snapchat.com/v1/ads/{ad_id}/external_changelogs?limit=50" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5d39e22900ff08cd2599670abb0001737e616473617069736300016275696c642d30633939333234362d312d3237352d300001014c",
"paging": {},
"changelogs": [
{
"sub_request_status": "SUCCESS",
"changelog": {
"id": "36f4b88b-1c24-41f5-af86-24983795edd7",
"updated_at": "2019-07-25T17:08:51.279Z",
"created_at": "2019-07-25T17:08:51.279Z",
"name": "Badger Holiday Ad 2019",
"action": "UPDATED",
"user_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
"email": "honey.badger@hooli.com",
"event_at": "2019-07-25T17:08:51.030Z",
"app_id": "87947032-5fbd-46a7-ba60-073ca8efefbb",
"app_name": "Honey badger App",
"entity_id": "cd88b368-35a3-46f4-b37f-2f1a72db2692",
"entity_type": "AD",
"update_value_records": {
"status": {
"before_value": "\"ACTIVE\"",
"after_value": "\"PAUSED\""
}
}
}
}
]
}
This endpoint retrieves the latest 50 changes to the Ad entity.
HTTP Request
GET https://adsapi.snapchat.com/v1/ads/{ad_id}/external_changelogs?limit=50
Parameters
Parameter | Default | Description |
---|---|---|
ad_id | Ad ID |
Fetch the change logs for a Creative
curl "https://adsapi.snapchat.com/v1/creatives/{creative_id}/external_changelogs?limit=50" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5d39de6000ff01c2268bd5c37b0001737e616473617069736300016275696c642d30633939333234362d312d3237352d300001010a",
"paging": {},
"changelogs": [
{
"sub_request_status": "SUCCESS",
"changelog": {
"id": "a94cb9ed-0171-402a-aee7-ffecae0ce7bc",
"updated_at": "2019-07-17T16:27:00.717Z",
"created_at": "2019-07-17T16:27:00.717Z",
"name": "Badger Rush",
"action": "UPDATED",
"user_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
"email": "honey.badger@hooli.com",
"event_at": "2019-07-17T16:27:00.566Z",
"app_id": "e9bdc78d-81fa-4470-8f6b-2a3d6f0487b3",
"app_name": "Honey Badger App",
"entity_id": "6475383b-cb70-4353-93b2-b227054169ae",
"entity_type": "CREATIVE",
"update_value_records": {
"call_to_action": {
"before_value": "\"MORE\"",
"after_value": "\"SIGN UP\""
}
}
}
},
{
"sub_request_status": "SUCCESS",
"changelog": {
"id": "72b18e3a-598a-4e29-a288-980613de3714",
"updated_at": "2019-07-17T16:07:00.985Z",
"created_at": "2019-07-17T16:07:00.985Z",
"name": "Badger Rush",
"action": "CREATED",
"user_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
"email": "honey.badger@hooli.com",
"event_at": "2019-07-17T16:07:00.629Z",
"app_id": "e9bdc78d-81fa-4470-8f6b-2a3d6f0487b3",
"app_name": "Honey Badger App",
"entity_id": "6475383b-cb70-4353-93b2-b227054169ae",
"entity_type": "CREATIVE"
}
}
]
}
This endpoint retrieves the latest 50 changes to the Creative entity.
HTTP Request
GET https://adsapi.snapchat.com/v1/creatives/{creative_id}/external_changelogs?limit=50
Parameters
Parameter | Default | Description |
---|---|---|
creative_id | Creative ID |
Fetch the change logs for a Dynamic Template
curl "https://adsapi.snapchat.com/v1/dynamic_templates/{dynamic_template_id}/external_changelogs?limit=50" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5d39e22900ff08cd2599670abb0001737e616473617069736300016275696c642d30633939333234362d312d3237352d300001014c",
"paging": {},
"changelogs": [
{
"sub_request_status": "SUCCESS",
"changelog": {
"id": "4f5f0eb1-92dd-4ae4-9d86-135ca516e696",
"updated_at": "2023-10-17T19:28:18.445Z",
"created_at": "2023-10-17T19:28:18.445Z",
"name": "Badger template",
"action": "CREATED",
"email": "honey.badger@hooli.com",
"event_at": "2023-10-17T19:28:17.912Z",
"app_id": "e9bdc78d-81fa-4470-8f6b-2a3d6f0487b3",
"app_name": "Honey badger App",
"entity_id": "f0a30c08-7613-4d41-a5fa-d8a0382bcced",
"entity_type": "DYNAMIC_TEMPLATE"
}
}
]
}
This endpoint retrieves the latest 50 changes to the Dynamic Template entity.
HTTP Request
GET https://adsapi.snapchat.com/v1/dynamic_templates/{dynamic_template_id}/external_changelogs?limit=50
Parameters
Parameter | Default | Description |
---|---|---|
dynamic_template_id | Dynamic Template ID |
Errors
The API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request – Your request sucks |
401 | Unauthorized – Your API key is wrong |
403 | Forbidden – The kitten requested is hidden for administrators only |
404 | Not Found – The specified kitten could not be found |
405 | Method Not Allowed – You tried to access a kitten with an invalid method |
406 | Not Acceptable – You requested a format that isn’t json |
410 | Gone – The kitten requested has been removed from our servers |
418 | I’m a teapot |
429 | Too Many Requests – You’re requesting too many kittens! Slow down! |
500 | Internal Server Error – We had a problem with our server. Try again later. |
503 | Service Unavailable – We’re temporarially offline for maintanance. Please try again later. |
Version
The API is versioned (you’re welcome). The current version is v1.
Rate Limits
The Snapchat Marketing API implements rate limits to ensure infrastructure stability.
Rate limits are implemented both at App and Token level, the App is able to support an overall average volume of 20 requests/second, individual Access tokens issued by the App can make requests at an average of 10 requests/second.
429 Error Code
If you reach the rate limit, you will start receiving an HTTP 429 Too Many Requests response.
In a scenario where your application regularly generates HTTP 429 Too Many Requests responses, you need to lower the rate at which your App is sending requests to the API.
Lenses
Lens AR experiences are a powerful and memorable way to connect with consumers on a massive scale using augmented reality.
Lens Implementation Details
- The advertiser will create a Lens with a target audience and a cost-per-impression bid.
- When a user opens the Lens carousel, Snapchat will run a second price auction containing all the Lenses targeting that user.
- The Lens that wins the auction will be inserted into the Lens section of the carousel.
- If the Lens is swiped on/over by the user, then the advertiser will be billed for the impression. An advertiser will only be billed once per Lens carousel session: while a user can swipe back and forth over the Lens during the session, the advertiser will only be billed for the first swipe in the session.
- If a user either posts the Lens to their story or sends the Lens in a Direct Snap, then the advertiser will not be charged for any of the resulting views.
Create a Campaign
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"campaigns": [{"name": "Lens Campaign", "ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1dab", "status": "ACTIVE", "start_time": "2016-08-11T22:00:00.000Z"}]}' \
"https://adsapi.snapchat.com/v1/adaccounts/3b0fbace-04b4-4f04-a425-33b5e0af1dab/campaigns"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b002ad00ff07e1f50fd2267f0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"campaigns": [
{
"sub_request_status": "success",
"campaign": {
"id": "5b48880f-bf65-495c-9810-2f4763add4cb",
"updated_at": "2020-02-04T05:33:33.876Z",
"created_at": "2020-02-04T05:33:33.876Z",
"name": "Lens Campaign",
"ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1dab",
"status": "ACTIVE",
"start_time": "2020-02-01T22:00:00.000Z"
}
}
]
}
This will create a campaign within a specified ad account, note Ad Squads with the type
LENS cannot be mixed with other types of Ad Squads (Snap Ads, Audience filters etc).
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/campaigns
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Lens Ad Squad
Attribute | Description | Required | Possible Values |
---|---|---|---|
campaign_id | Campaign ID | R | |
name | Ad Squad name | R | |
billing_event | Billing Event | R | IMPRESSION |
bid_micro | Max Bid (micro-currency) | R | |
auto_bid | Allow Snapchat to automatically set the bid to recommended amount | O (One of auto_bid, target_bid or bid_micro must be set) | true/false. |
target_bid | Allows Snapchat to adjust the bid aiming to keep your average CPA at or below the amount set by the ad set end date | O (One of auto_bid, target_bid or bid_micro must be set) | true/false. |
pixel_id | Pixel to be associated with the Ad Squad | O | |
start_time | Start time | R | |
end_time | End time | R | |
optimization_goal | Optimization Goal | R | IMPRESSIONS |
placement_v2.config | Placement | R | CUSTOM |
placement_v2.platforms | Placement | R | SNAPCHAT |
placement_v2.snapchat_positions | Placement | R | CAMERA |
status | Ad Squad status | R | ACTIVE, PAUSED |
type | Ad Squad Type | R | LENS |
targeting | Targeting spec | R | Any valid targeting options |
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adsquads": [{"name": "Lens adsquad","status": "ACTIVE","campaign_id": "5b48880f-bf65-495c-9810-2f4763add4cb","type": "LENS","placement_v2": {"config": "CUSTOM","platforms": ["SNAPCHAT"],"snapchat_positions": ["CAMERA"]},"billing_event": "IMPRESSION","bid_micro": "200000000","daily_budget_micro": "2000000000","start_time": "2020-08-15T12:16:17.444-07:00","end_time": "2020-08-19T12:16:17.444-07:00","optimization_goal": "IMPRESSIONS","targeting": {"regulated_content": "false","demographics": [{"min_age": "21","max_age": "24"}],"geos": [{"country_code": "us"}]}}]}' \
https://adsapi.snapchat.com/v1/campaigns/5b48880f-bf65-495c-9810-2f4763add4cb/adsquads
The above request returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e3c0a3d00ff077b3836beabb80001737e616473617069736300016275696c642d62343864336664332d312d3332332d3000010151",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "caff7533-52e1-4412-9ef2-18232dbcd1ba",
"updated_at": "2020-02-06T12:44:45.818Z",
"created_at": "2020-02-06T12:44:45.818Z",
"name": "Lens adsquad",
"status": "ACTIVE",
"campaign_id": "5b48880f-bf65-495c-9810-2f4763add4cb",
"type": "LENS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"min_age": "21",
"max_age": "24"
}
],
"geos": [
{
"country_code": "us"
}
]
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"CAMERA"
]
},
"billing_event": "IMPRESSION",
"bid_micro": 200000000,
"auto_bid": false,
"target_bid": false,
"daily_budget_micro": 2000000000,
"start_time": "2020-08-15T19:16:17.444Z",
"end_time": "2020-08-19T19:16:17.444Z",
"optimization_goal": "IMPRESSIONS",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD"
}
}
]
}
This creates an Ad Squad within a Campaign, note Ad Squads with the type
LENS cannot be mixed with other types of Ad Squads (Snap Ads, Audience filters etc).
HTTP Request
POST https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads
Parameters
Parameter | Default | Description |
---|---|---|
campaign_id | Campaign ID |
Lens Media
Unlike other Creatives, the Media file for a Lens Creative is not uploaded via the API, it’s instead created in Snapchat Lens Studio or Lens Web Builder and then transferred to the Ad Account via the Lens folder in Business Manager.
Lens Media Attributes
These attributes are unique to the Media type LENS_PACKAGE
Attribute | Description | Possible Values |
---|---|---|
type | The Media type | LENS_PACKAGE |
lens_package_metadata.lens_icon_media_id | Media ID of the lens icon | |
lens_package_metadata.default_camera | Default camera when lens opens | BOTH, FACE, WORLD |
Create the Creative - Lens
When a Lens is created in Snapchat Lens Studio, both the Media and the Creative will automatically be set up. You can however re-use the Lens media if you wish to set up a new Creative.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
name | Creative name | R | |
top_snap_media_id | Media ID of type LENS_PACKAGE | R | |
type | Creative Type | R | LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_WEB_VIEW |
ad_product | Ad product | R | LENS |
brand_name | Brand Name | R (required but not displayed) | 25 characters max |
headline | Headline | R (required but not displayed) | 34 characters max |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1","name" : "Honey Badger Lens","type": "LENS","top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01","ad_product": "LENS","headline": "Try the Honey Badger Lens","brand_name": "Honey Badger"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e3c5e7a00ff07ac2c051bd68e0001737e616473617069736300016275696c642d62343864336664332d312d3332332d3000010118",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "0091127a-1c58-4b0b-981d-d419d65cc87c",
"updated_at": "2020-02-06T18:44:12.044Z",
"created_at": "2020-02-06T18:44:12.044Z",
"name": "Honey Badger Lens",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
"type": "LENS",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Try the Honey Badger Lens",
"brand_name": "Honey Badger",
"render_type": "STATIC",
"top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01",
"top_snap_crop_position": "MIDDLE",
"ad_product": "LENS"
}
}
]
}
This creates a new Creative of the type LENS where the attribute top_snap_media_id
is of the type LENS_PACKAGE.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create the Creative - Lens with App Install Attachment
When a Lens is created in Snapchat Lens Studio or Lens Web Builder, both the Media and the Creative will automatically be set up, you can however re-use the Lens media if you wish to set up a new Creative.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
name | Creative name | R | |
top_snap_media_id | Media ID of type LENS_PACKAGE | R | |
type | Creative Type | R | LENS_APP_INSTALL |
ad_product | Ad product | R | LENS |
brand_name | Brand Name | R (required but not displayed) | 25 characters max |
headline | Headline | R (required but not displayed) | 34 characters max |
call_to_action | Call to Action | R | Please refer to the Creative type to CTA mapping table |
Additional Attributes
The following attributes should be added to the basic creative under the property app_install_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
app_name | App name | R | |
ios_app_id | iOS App ID | R | |
android_app_url | Google Play Store ID | R | (eg “com.x.y”) |
icon_media_id | Icon Media ID | R | |
product_page_id | Custom product page ID from iOS App Store. | O | 45812c9b-c296-43d3-c6a0-c5a02f74bf6e |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1","name" : "Honey Badger Lens with App Install Attachment","type": "LENS_APP_INSTALL","top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01","ad_product": "LENS","headline": "Try the Honey Badger Lens","brand_name": "Honey Badger","call_to_action": "INSTALL_NOW","app_install_properties": {"app_name": "Bitmoji - Your Personal Emoji","ios_app_id": "868077558","android_app_url": "com.bitstrips.imoji","icon_media_id": "73b5deb6-5b2c-43b4-b60d-983bc344a4a2"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e42e3c700ff04d097d68c02810001737e616473617069736300016275696c642d63343664356339642d312d3332352d300001011a",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "1deb9eda-83bb-419d-a86c-67e2a7025385",
"updated_at": "2020-02-11T17:26:32.402Z",
"created_at": "2020-02-11T17:26:32.402Z",
"name": "Honey Badger Lens with App Install Attachment",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
"type": "LENS_APP_INSTALL",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Try the Honey Badger Lens",
"brand_name": "Honey Badger",
"call_to_action": "INSTALL_NOW",
"render_type": "STATIC",
"top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01",
"top_snap_crop_position": "MIDDLE",
"app_install_properties": {
"app_name": "Bitmoji - Your Personal Emoji",
"ios_app_id": "868077558",
"android_app_url": "com.bitstrips.imoji",
"icon_media_id": "73b5deb6-5b2c-43b4-b60d-983bc344a4a2"
},
"ad_product": "LENS"
}
}
]
}
This creates a new Creative of the type LENS_APP_INSTALL where the attribute top_snap_media_id
is of the type LENS_PACKAGE, and where the app_install_properties
specify the attributes for the App Install Attachment.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create Lens with Deep Link Attachment
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
name | Creative name | R | |
top_snap_media_id | Media ID of type LENS_PACKAGE | R | |
type | Creative Type | R | LENS_DEEP_LINK |
ad_product | Ad product | R | LENS |
brand_name | Brand Name | R (required but not displayed) | 25 characters max |
headline | Headline | R (required but not displayed) | 34 characters max |
call_to_action | Call to Action | R | Please refer to the Creative type to CTA mapping table |
Additional Attributes
The following attributes should be added to the basic creative under the property deep_link_properties.
Attribute | Description | Required |
---|---|---|
deep_link_uri | Deep Link URL | R |
app_name | App name | R |
ios_app_id | iOS App ID | Optional but one of ios_app_id or android_app_url is required |
android_app_url | Google Play Store ID | Optional but one of ios_app_id or android_app_url is required |
icon_media_id | Icon Media ID | R |
fallback_type | Type of fallback to be used when user doesn’t have the app | O |
web_view_fallback_url | Fallback web url to be used | O |
product_page_id | Custom Product Page ID on iOS App Store | O |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1","name" : "A new Lens with Deep Link Attachment","type": "LENS_DEEP_LINK","top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01","ad_product": "LENS","headline": "Try the Honey Badger Lens","brand_name": "Honey Badger","call_to_action": "TRY","deep_link_properties": {"deep_link_uri": "bitmoji://home","app_name": "Bitmoji - Your Personal Emoji","ios_app_id": "868077558","android_app_url": "com.bitstrips.imoji","icon_media_id": "73b5deb6-5b2c-43b4-b60d-983bc344a4a2","fallback_type": "APP_INSTALL"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e42ff007200ff071b3da02f5e6c0001737e616473617069736300016275696c642d63343664356339642d312d3332352d3000010110",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "d1b888eb-8998-42e3-9e73-45b5b5e8938d",
"updated_at": "2020-02-11T19:24:35.553Z",
"created_at": "2020-02-11T19:24:35.553Z",
"name": "A new Lens with Deep Link Attachment",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
"type": "LENS_DEEP_LINK",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Try the Honey Badger Lens",
"brand_name": "Honey Badger",
"call_to_action": "TRY",
"render_type": "STATIC",
"top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01",
"top_snap_crop_position": "MIDDLE",
"deep_link_properties": {
"deep_link_uri": "bitmoji://home",
"app_name": "Bitmoji - Your Personal Emoji",
"ios_app_id": "868077558",
"android_app_url": "com.bitstrips.imoji",
"icon_media_id": "73b5deb6-5b2c-43b4-b60d-983bc344a4a2",
"fallback_type": "APP_INSTALL"
},
"ad_product": "LENS"
}
}
]
}
This creates a new Creative of the type LENS_APP_INSTALL where the attribute top_snap_media_id
is of the type LENS_PACKAGE, and where the deep_link_properties
specify the attributes for the Deep link Attachment.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create Lens with Web View Attachment
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
name | Creative name | R | |
top_snap_media_id | Media ID of type LENS_PACKAGE | R | |
type | Creative Type | R | LENS_WEB_VIEW |
ad_product | Ad product | R | LENS |
brand_name | Brand Name | R (required but not displayed) | 25 characters max |
headline | Headline | R (required but not displayed) | 34 characters max |
call_to_action | Call to Action | R | Please refer to the Creative type to CTA mapping table |
Additional Attributes
The following attributes should be added to the basic creative under the property web_view_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
url | Web view URL | R | |
allow_snap_javascript_sdk | Allow Snapchat Javascript SDK to autofill form fields | O | true/false |
block_preload | Block Snapchat from preloading the web page | O | true/false |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1","name" : "A new Lens with Web View Attachment","type": "LENS_WEB_VIEW","top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01","ad_product": "LENS","headline": "Try the Honey Badger Lens","brand_name": "Honey Badger","call_to_action": "GET_NOW","web_view_properties": {"url": "http://www.example.com","allow_snap_javascript_sdk": "false","block_preload": "true"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e43d97400ff00ffe6fb1765c4350001737e616473617069736300016275696c642d63343664356339642d312d3332352d3000010119",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "b8f8dfb3-7738-4765-bd8e-ff312a34740d",
"updated_at": "2020-02-12T10:54:45.363Z",
"created_at": "2020-02-12T10:54:45.363Z",
"name": "A new Lens with Web View Attachment",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
"type": "LENS_WEB_VIEW",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Try the Honey Badger Lens",
"brand_name": "Honey Badger",
"call_to_action": "GET_NOW",
"render_type": "STATIC",
"top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01",
"top_snap_crop_position": "MIDDLE",
"web_view_properties": {
"url": "http://www.example.com",
"allow_snap_javascript_sdk": false,
"use_immersive_mode": false,
"deep_link_urls": [],
"block_preload": true
},
"ad_product": "LENS"
}
}
]
}
This creates a new Creative of the type LENS_WEB_VIEW where the attribute top_snap_media_id
is of the type LENS_PACKAGE, and where the web_view_properties
specify the attributes for the Web View Attachment.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create the Ad
This endpoint creates an Ad within an Ad Squad, note that the type
attribute should match the Creative type of the Lens.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_squad_id | Ad Squad ID | R | |
creative_id | Creative ID | R | |
name | Ad name | R | |
type | Ad type | R | LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_REMOTE_WEBPAGE |
review_status | Ad Review Status | READ ONLY | PENDING, APPROVED, REJECTED |
review_status_reason | List of Ad Review Rejection Reasons | READ ONLY | if rejected, list of reasons |
status | Ad status | R | ACTIVE, PAUSED |
Ad Type <-> Creative Type Mapping
Ad Type | Allowed Creative Lens Type |
---|---|
LENS | LENS |
LENS_REMOTE_WEBPAGE | LENS_WEB_VIEW |
LENS_APP_INSTALL | LENS_APP_INSTALL |
LENS_DEEP_LINK | LENS_DEEP_LINK |
curl -X POST \
-d '{"ads":[{"ad_squad_id": "caff7533-52e1-4412-9ef2-18232dbcd1ba", "creative_id":"0091127a-1c58-4b0b-981d-d419d65cc87c", "name": "Honey Badger Ad - Lens", "type": "LENS", "status": "ACTIVE"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/caff7533-52e1-4412-9ef2-18232dbcd1ba/ads
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e41982700ff0e64c8b9dcef490001737e616473617069736300016275696c642d66646632303364612d312d3332342d310001012a",
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "1ab494d4-73e8-4986-8517-c2d313e63f6e",
"updated_at": "2020-02-10T17:51:38.097Z",
"created_at": "2020-02-10T17:51:38.097Z",
"name": "Honey Badger Ad - Lens",
"ad_squad_id": "caff7533-52e1-4412-9ef2-18232dbcd1ba",
"creative_id": "0091127a-1c58-4b0b-981d-d419d65cc87c",
"status": "ACTIVE",
"type": "LENS"
}
}
]
}
This creates a new Ad of the type LENS.
HTTP Request
POST https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Parameters
Parameter | Default | Description |
---|---|---|
ad_squad_id | Ad Squad ID |
Reporting
Lens Metrics
Field | Description | Availability |
---|---|---|
paid_impressions | The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter’s viewing session | Real Time |
earned_impressions | The number of times your ad was viewed after being shared by a Snapchatter via Chat or Stories | Within 24 hours |
total_impressions | The total number of impressions (Paid and Earned) | Within 24 hours |
shares | The number of times your Lens ad was shared via Chat or Stories | Real Time |
saves | The number of times your Lens ad was saved to Memories | Real Time |
play_time_millis | The total amount of time in where Snapchatters interacted with your Lens in the camera (milliseconds) | Real Time |
spend | The total spend delivered in microcurrency | Real Time |
uniques | The number of unique paid impressions | Within 24 hours, LIFETIME only |
total_reach | The number of unique Snapchatters who viewed your Lens ad, either by receiving a Paid or Earned Impression. | Within 24 hours, LIFETIME only |
Stats are available at the Ad, Ad Squad and Campaign levels and are supported for all granularities: HOUR, DAY, TOTAL and LIFETIME.
For lenses with attachments you can also request swipes
and attachment specific metrics.
curl "https://adsapi.snapchat.com/v1/adsquads/21136912-6d1a-44ea-a171-8ac29cf4d75d/stats?granularity=LIFETIME&fields=spend,paid_impressions,earned_impressions,shares,saves,play_time_millis,total_impressions,total_reach,uniques"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e448f8200ff0a3c430fd301390001737e616473617069736300016275696c642d63343664356339642d312d3332352d300001011c",
"lifetime_stats": [
{
"sub_request_status": "SUCCESS",
"lifetime_stat": {
"id": "21136912-6d1a-44ea-a171-8ac29cf4d75d",
"type": "AD_SQUAD",
"granularity": "LIFETIME",
"stats": {
"uniques": 298861,
"spend": 7027120158,
"total_reach": 315925,
"total_impressions": 979631,
"earned_impressions": 29190,
"paid_impressions": 950441,
"shares": 7351,
"saves": 1784,
"play_time_millis": 6354875748
},
"start_time": "2016-09-26T08:00:00.000+01:00",
"end_time": "2020-02-12T17:00:00.000Z",
"finalized_data_end_time": "2020-02-12T17:00:00.000Z"
}
}
]
}
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{adsquad-id}/stats
Parameters
Parameter | Description |
---|---|
adsquad-id | Lens Ad squad ID |
Snap Pixel
Snap Pixel provides an entity that advertisers can use to build a correlation between the ads that the users viewed and the conversions that happened on advertiser’s website.
Create a Pixel
You can create a Snap Pixel for your Ad Account on Ad Manager
Get the Pixel associated with an Ad Account
curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/pixels" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5a0253c100ff013af0e5dd11d40001737e616473617069736300016275696c642d61306563656639392d312d3131392d3300010124",
"pixels": [
{
"sub_request_status": "SUCCESS",
"pixel": {
"id": "6abc82ca-4a3a-4391-98ba-0317a8471234",
"updated_at": "2017-03-15T18:19:08.576Z",
"created_at": "2017-03-15T18:19:08.576Z",
"effective_status": "ACTIVE",
"name": "Test pixel",
"ad_account_id": "3cb7c65d-a943-448b-90aa-bd6bac71dabc",
"status": "ACTIVE",
"pixel_javascript": "<!-- Snap Pixel Code -->\n<script type='text/javascript'>\n(function(e,t,n){if(e.snaptr)return;var a=e.snaptr=function()\n{a.handleRequest?a.handleRequest.apply(a,arguments):a.queue.push(arguments)};\na.queue=[];var s='script';r=t.createElement(s);r.async=!0;\nr.src=n;var u=t.getElementsByTagName(s)[0];\nu.parentNode.insertBefore(r,u);})(window,document,\n'https://sc-static.net/scevent.min.js');\n\nsnaptr('init', '6abc82ca-4a3a-4391-98ba-0317a8471234', {\n'user_email': '__INSERT_USER_EMAIL__'\n});\n\nsnaptr('track', 'PAGE_VIEW');\n\n</script>\n<!-- End Snap Pixel Code -->"
}
}
]
}
This endpoint retrieves the pixel associated with the specified Ad Account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/pixels
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Implementing the Snap Pixel
Please check Business Help Center for steps to implement the pixel on your website.
Get a Specific Pixel
curl "https://adsapi.snapchat.com/v1/pixels/sf6f3815-3527-49e3-a5a7-b9681b31daf4" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5a025dac00ff011af30b6a01d00001737e616473617069736300016275696c642d61306563656639392d312d3131392d3300010162",
"pixels": [
{
"sub_request_status": "SUCCESS",
"pixel": {
"id": "sf6f3815-3527-49e3-a5a7-b9681b31daf4",
"updated_at": "2017-03-15T18:19:08.576Z",
"created_at": "2017-03-15T18:19:08.576Z",
"effective_status": "ACTIVE",
"name": "Test pixel",
"ad_account_id": "3c42c65d-a943-448b-90aa-bd6bac71d2bc",
"status": "ACTIVE",
"pixel_javascript": "<!-- Snap Pixel Code -->\n<script type='text/javascript'>\n(function(e,t,n){if(e.snaptr)return;var a=e.snaptr=function()\n{a.handleRequest?a.handleRequest.apply(a,arguments):a.queue.push(arguments)};\na.queue=[];var s='script';r=t.createElement(s);r.async=!0;\nr.src=n;var u=t.getElementsByTagName(s)[0];\nu.parentNode.insertBefore(r,u);})(window,document,\n'https://sc-static.net/scevent.min.js');\n\nsnaptr('init', 'sf6f3815-3527-49e3-a5a7-b9681b31daf4', {\n'user_email': '__INSERT_USER_EMAIL__'\n});\n\nsnaptr('track', 'PAGE_VIEW');\n\n</script>\n<!-- End Snap Pixel Code -->"
}
}
]
}
This endpoint retrieves a pixel associated with a specific Ad Account.
HTTP Request
GET https://adsapi.snapchat.com/v1/pixels/<PIXEL_ID>
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the Pixel to retrieve |
Update a Pixel - Organization level
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"pixels":[{"id":"6eda10b7-a5fe-4ac6-80f4-417e68d748fb","name": "New pixel name","organization_id":"7fdeefec-f502-4ca8-9a84-6411e0a51053"}]}'
https://adsapi.snapchat.com/v1/organizations/7fdeefec-f502-4ca8-9a84-6411e0a51053/pixels
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "589a3df500ff035b6c6fefa6340001737e616473617069736300016275696c642d62666138636139332d312d33392d3400010123",
"pixels": [
{
"sub_request_status": "SUCCESS",
"pixel": {
"id": "6eda10b7-a5fe-4ac6-80f4-417e68d748fb",
"updated_at": "2024-01-30T14:49:40.516Z",
"created_at": "2018-10-15T07:08:15.742Z",
"last_updated_by_app_id": "ff503f30-8e94-450b-abac-18e3e25a8da1",
"last_updated_by_user": "82beca53-2402-45f6-bc0f-1244a2cb8936",
"name": "New pixel name",
"organization_id": "7fdeefec-f502-4ca8-9a84-6411e0a51053",
"status": "ACTIVE",
"pixel_javascript": "<!-- Snap Pixel Code -->\n<script type='text/javascript'>\n(function(e,t,n){if(e.snaptr)return;var a=e.snaptr=function()\n{a.handleRequest?a.handleRequest.apply(a,arguments):a.queue.push(arguments)};\na.queue=[];var s='script';r=t.createElement(s);r.async=!0;\nr.src=n;var u=t.getElementsByTagName(s)[0];\nu.parentNode.insertBefore(r,u);})(window,document,\n'https://sc-static.net/scevent.min.js');\n\nsnaptr('init', '6eda10b7-a5fe-4ac6-80f4-417e68d748fb', {\n'user_email': '__INSERT_USER_EMAIL__'\n});\n\nsnaptr('track', 'PAGE_VIEW');\n\n</script>\n<!-- End Snap Pixel Code -->",
"visible_to": [
"AdAccountEntity_438cf09a-c829-41f9-bb08-89512a574682",
"AdAccountEntity_3dbf041c-f500-442a-89e3-cfd2311dbdd9",
"OrganizationEntity_7fdeefec-f502-4ca8-9a84-6411e0a51053",
"AdAccountEntity_88225ba6-7559-4000-9663-bace8adff5f2"
]
}
}
]
}
This endpoint retrieves a pixel associated with a specific Organization.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
id | ID of the Pixel | R | |
name | Name of the Pixel | R | |
organization_id | Organization ID | R |
Attributes that can be updated
Attribute | Description |
---|---|
name | Name of the Pixel |
HTTP Request
PUT https://adsapi.snapchat.com/v1/organizations/{{organization_id}}/pixels
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Update a Pixel - Ad Account level
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"pixels":[{"id":"6eda10b7-a5fe-4ac6-80f4-417e68d748fb","name": "New pixel name","ad_account_id":"88225ba6-7559-4000-9663-bace8adff5f2"}]}'
https://adsapi.snapchat.com/v1/adaccounts/88225ba6-7559-4000-9663-bace8adff5f2/pixels
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "589a3df500ff035b6c6fefa6340001737e616473617069736300016275696c642d62666138636139332d312d33392d3400010123",
"pixels": [
{
"sub_request_status": "SUCCESS",
"pixel": {
"id": "6eda10b7-a5fe-4ac6-80f4-417e68d748fb",
"updated_at": "2024-01-30T14:46:58.636Z",
"created_at": "2018-10-15T07:08:15.742Z",
"last_updated_by_app_id": "ff503f30-8e94-450b-abac-18e3e25a8da1",
"last_updated_by_user": "82beca53-2402-45f6-bc0f-1244a2cb8936",
"name": "New pixel name",
"organization_id": "7fdeefec-f502-4ca8-9a84-6411e0a51053",
"ad_account_id": "88225ba6-7559-4000-9663-bace8adff5f2",
"status": "ACTIVE",
"pixel_javascript": "<!-- Snap Pixel Code -->\n<script type='text/javascript'>\n(function(e,t,n){if(e.snaptr)return;var a=e.snaptr=function()\n{a.handleRequest?a.handleRequest.apply(a,arguments):a.queue.push(arguments)};\na.queue=[];var s='script';r=t.createElement(s);r.async=!0;\nr.src=n;var u=t.getElementsByTagName(s)[0];\nu.parentNode.insertBefore(r,u);})(window,document,\n'https://sc-static.net/scevent.min.js');\n\nsnaptr('init', '6eda10b7-a5fe-4ac6-80f4-417e68d748fb', {\n'user_email': '__INSERT_USER_EMAIL__'\n});\n\nsnaptr('track', 'PAGE_VIEW');\n\n</script>\n<!-- End Snap Pixel Code -->"
}
}
]
}
This endpoint will update a specified pixel.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
id | ID of the Pixel | R | |
name | Name of the Pixel | R | |
ad_account_id | Ad Account ID | R |
Attributes that can be updated
Attribute | Description |
---|---|
name | Name of the Pixel |
HTTP Request
PUT https://adsapi.snapchat.com/v1/adaccounts/{{ad_account_id}}/pixels
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Associate a Pixel to an Ad Squad
To track conversions, the pixel_id parameter must be set in the Ad Squad creation call.
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adsquads": [{"name": "Ad Squad with Pixel", "status": "PAUSED", "campaign_id": "84dc65d7-2745-45c3-a2b7-2d616dbb7fff", "type": "SNAP_ADS", "placement": "SNAP_ADS", "billing_event": "IMPRESSION", "bid_micro": "5000000", "daily_budget_micro": "100000000", "start_time": "2017-03-31T15:00:00.444-07:00", "end_time": "2017-04-30T12:16:17.444-07:00", "optimization_goal": "IMPRESSIONS", "targeting": {"regulated_content": false, "geos": [{"country_code": "us"}]}, "pixel_id": "6c9d82ca-4a3a-4391-98ba-0317a8471233"}]}' \
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": "58e8246700ff03be1041ca773d0001737e616473617069736300016275696c642d39663230313762372d312d35362d3300010111",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "7fe85cf3-74c7-494e-bdf6-4db478dc4955",
"updated_at": "2017-04-07T23:44:40.447Z",
"created_at": "2017-04-07T23:44:40.447Z",
"name": "Ad Squad with Pixel",
"status": "PAUSED",
"campaign_id": "84dc65d7-2745-45c3-a2b7-2d616dbb7fff",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"geos": [
{
"country_code": "us"
}
]
},
"placement": "SNAP_ADS",
"billing_event": "IMPRESSION",
"bid_micro": 5000000,
"daily_budget_micro": 100000000,
"start_time": "2017-03-31T22:00:00.444Z",
"end_time": "2017-04-30T19:16:17.444Z",
"optimization_goal": "IMPRESSIONS",
"pixel_id": "6c9d82ca-4a3a-4391-98ba-0317a8471233"
}
}
]
}
Conversion Event Stats
The conversion event metrics available are listed here
Get Campaign Stats
curl "https://adsapi.snapchat.com/v1/campaigns/69d120bd-b319-4201-9a2a-0e64b2ee5411/stats?granularity=DAY&fields=impressions,swipes,conversion_purchases,conversion_save,conversion_start_checkout,conversion_add_cart,conversion_view_content,conversion_add_billing,conversion_sign_ups,conversion_searches,conversion_level_completes,conversion_app_opens,conversion_page_views&start_time=2017-04-28T07:00:00.000-00:00&end_time=2017-04-30T07:00:00.000-00:00" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5907c87e00ff00ffebe513c872800001737e616473617069736300016275696c642d62663930383438312d312d36322d3200010112",
"timeseries_stats": [
{
"sub_request_status": "SUCCESS",
"timeseries_stat": {
"id": "69d120bd-b319-4201-9a2a-0e64b2ee5411",
"type": "CAMPAIGN",
"granularity": "DAY",
"start_time": "2017-04-28T00:00:00.000-07:00",
"end_time": "2017-04-30T00:00:00.000-07:00",
"finalized_data_end_time": "2017-05-01T00:00:00.000-07:00",
"timeseries": [
{
"start_time": "2017-04-28T00:00:00.000-07:00",
"end_time": "2017-04-29T00:00:00.000-07:00",
"stats": {
"impressions": 7715,
"swipes": 57,
"conversion_purchases": 200,
"conversion_save": 150,
"conversion_start_checkout": 300,
"conversion_add_cart": 500,
"conversion_view_content": 785,
"conversion_add_billing": 666,
"conversion_sign_ups": 1000,
"conversion_searches": 1500,
"conversion_level_completes": 450,
"conversion_app_opens": 800,
"conversion_page_views": 1500
}
},
{
"start_time": "2017-04-29T00:00:00.000-07:00",
"end_time": "2017-04-30T00:00:00.000-07:00",
"stats": {
"impressions": 7715,
"swipes": 57,
"conversion_purchases": 200,
"conversion_save": 150,
"conversion_start_checkout": 300,
"conversion_add_cart": 500,
"conversion_view_content": 785,
"conversion_add_billing": 666,
"conversion_sign_ups": 1000,
"conversion_searches": 1500,
"conversion_level_completes": 450,
"conversion_app_opens": 800,
"conversion_page_views": 1500
}
}
]
}
}
]
}
This endpoint retrieves stats for the specified Campaign.
HTTP Request
GET https://adsapi.snapchat.com/v1/campaigns/{campaign-id}/stats
Parameters
Parameter | Default | Description |
---|---|---|
campaign-id | Campaign ID |
Get Ad Squad Stats
curl "https://adsapi.snapchat.com/v1/adsquads/260ea29d-8380-4103-90cd-89a326090b01/stats?granularity=TOTAL&fields=impressions,swipes,conversion_purchase,conversion_save,conversion_start_checkout,conversion_add_cart,conversion_view_content,conversion_add_billing,conversion_sign_up,conversion_search,conversion_level_complete,conversion_app_open,conversion_page_view" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5907c1c300ff0724e2dea334690001737e616473617069736300016275696c642d62663930383438312d312d36322d3200010154",
"total_stats": [
{
"sub_request_status": "SUCCESS",
"total_stat": {
"id": "260ea29d-8380-4103-90cd-89a326090b01",
"type": "AD_SQUAD",
"granularity": "TOTAL",
"stats": {
"impressions": 15430,
"swipes": 114,
"conversion_purchases": 400,
"conversion_save": 300,
"conversion_start_checkout": 600,
"conversion_add_cart": 1000,
"conversion_view_content": 1570,
"conversion_add_billing": 1332,
"conversion_sign_ups": 2000,
"conversion_searches": 3000,
"conversion_level_completes": 900,
"conversion_app_opens": 1600,
"conversion_page_views": 3000
},
"finalized_data_end_time": "2017-05-01T00:00:00.000-07:00"
}
}
]
}
This endpoint retrieves stats for the specified Ad Squad.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{adsquad-id}/stats
Parameters
Parameter | Default | Description |
---|---|---|
adsquad-id | Ad Squad ID |
Get Ad Stats
curl "https://adsapi.snapchat.com/v1/ads/482fa116-95c1-43c9-8d17-5a6dc3330d41/stats?granularity=HOUR&fields=impressions,swipes,conversion_purchases,conversion_save,conversion_start_checkout,conversion_add_cart,conversion_view_content,conversion_add_billing,conversion_sign_ups,conversion_searches,conversion_level_completes,conversion_app_opens,conversion_page_views&start_time=2017-04-30T07:00:00.000-00:00&end_time=2017-04-30T10:00:00.000-00:00" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5907cec100ff0aef6f08499b460001737e616473617069736300016275696c642d62663930383438312d312d36322d3200010145",
"timeseries_stats": [
{
"sub_request_status": "SUCCESS",
"timeseries_stat": {
"id": "482fa116-95c1-43c9-8d17-5a6dc3330d41",
"type": "AD",
"granularity": "HOUR",
"start_time": "2017-04-30T00:00:00.000-07:00",
"end_time": "2017-04-30T03:00:00.000-07:00",
"finalized_data_end_time": "2017-05-01T00:00:00.000-07:00",
"timeseries": [
{
"start_time": "2017-04-30T00:00:00.000-07:00",
"end_time": "2017-04-30T01:00:00.000-07:00",
"stats": {
"impressions": 7715,
"swipes": 57,
"conversion_purchases": 200,
"conversion_save": 150,
"conversion_start_checkout": 300,
"conversion_add_cart": 500,
"conversion_view_content": 785,
"conversion_add_billing": 666,
"conversion_sign_ups": 1000,
"conversion_searches": 1500,
"conversion_level_completes": 450,
"conversion_app_opens": 800,
"conversion_page_views": 1500
}
},
{
"start_time": "2017-04-30T01:00:00.000-07:00",
"end_time": "2017-04-30T02:00:00.000-07:00",
"stats": {
"impressions": 7715,
"swipes": 57,
"conversion_purchases": 200,
"conversion_save": 150,
"conversion_start_checkout": 300,
"conversion_add_cart": 500,
"conversion_view_content": 785,
"conversion_add_billing": 666,
"conversion_sign_ups": 1000,
"conversion_searches": 1500,
"conversion_level_completes": 450,
"conversion_app_opens": 800,
"conversion_page_views": 1500
}
},
{
"start_time": "2017-04-30T02:00:00.000-07:00",
"end_time": "2017-04-30T03:00:00.000-07:00",
"stats": {
"impressions": 7715,
"swipes": 57,
"conversion_purchases": 200,
"conversion_save": 150,
"conversion_start_checkout": 300,
"conversion_add_cart": 500,
"conversion_view_content": 785,
"conversion_add_billing": 666,
"conversion_sign_ups": 1000,
"conversion_searches": 1500,
"conversion_level_completes": 450,
"conversion_app_opens": 800,
"conversion_page_views": 1500
}
}
]
}
}
]
}
This endpoint retrieves stats for the specified Ad.
HTTP Request
GET https://adsapi.snapchat.com/v1/ads/{ad-id}/stats
Parameters
Parameter | Default | Description |
---|---|---|
ad-id | Ad ID |
Get Pixel Domains
curl "https://adsapi.snapchat.com/v1/pixels/57ad1ad-600076e-58fa375-e19284/domains/stats" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "59b1e63000ff0aeee681bf3ac50001737e616473617069736300016275696c642d64333736306564362d312d39382d3100010123",
"timeseries_stats": [
{
"sub_request_status": "SUCCESS",
"timeseries_stat": {
"id": "6c9d82ca-4a3a-4391-98ba-0317a8471296",
"type": "PIXEL",
"start_time": "2017-08-31T18:00:00.000-07:00",
"end_time": "2017-09-07T18:00:00.000-07:00",
"domains": [
{
"domain_name": "abc.snapchat.com",
"total_events": 30
},
{
"domain_name": "xyz.snapchat.com",
"total_events": 8
},
{
"domain_name": "snapchat.com",
"total_events": 180886
},
{
"domain_name": "www.snapchat.com",
"total_events": 9682034
}
]
}
}
]
}
This endpoint retrieves the domains that have fired the pixel in the past 7 days.
HTTP Request
GET https://adsapi.snapchat.com/v1/pixels/{pixel-id}/domains/stats
Parameters
Parameter | Default | Description |
---|---|---|
pixel-id | Pixel ID |
Get Pixel Stats for a specific domain
curl "https://adsapi.snapchat.com//v1/pixels/57ad1ad-600076e-58fa375-e19284/stats?start_time=2017-08-31T18:00:00.000-07:00&end_time=2017-09-07T18:00:00.000-07:00&granularity=DAY&domain=abc.snapchat.com&fields=event_type,os_type,browser_type" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "59b1eac600ff088c614606e13d0001737e616473617069736300016275696c642d64333736306564362d312d39382d3100010157",
"timeseries_stats": [
{
"sub_request_status": "SUCCESS",
"timeseries_stat": {
"id": "6c9d82ca-4a3a-4391-98ba-0317a8471234",
"type": "PIXEL",
"granularity": "DAY",
"start_time": "2017-08-31T18:00:00.000-07:00",
"end_time": "2017-09-07T18:00:00.000-07:00",
"timeseries": [
{
"start_time": "2017-08-31T00:00:00.000-07:00",
"end_time": "2017-09-01T00:00:00.000-07:00",
"total_events": 253926,
"event_type_breakdown": {
"VIEW_CONTENT": 13560,
"PAGE_VIEW": 240366
},
"os_type_breakdown": {
"MAC_OS_X": 1,
"IOS": 217753,
"ANDROID": 36170,
"LINUX": 2
},
"browser_type_breakdown": {
"FIREFOX": 4,
"BROWSER_TYPE_OTHER": 154,
"SAFARI": 217747,
"CHROME": 36021
}
},
{
"start_time": "2017-09-01T00:00:00.000-07:00",
"end_time": "2017-09-02T00:00:00.000-07:00",
"total_events": 873039,
"event_type_breakdown": {
"VIEW_CONTENT": 36094,
"PAGE_VIEW": 836945
},
"os_type_breakdown": {
"IOS": 738139,
"ANDROID": 134867,
"MAC_OS_X": 17,
"LINUX": 2,
"WINDOW": 14
},
"browser_type_breakdown": {
"BROWSER_TYPE_OTHER": 709,
"SAFARI": 738135,
"CHROME": 134163,
"FIREFOX": 22,
"INTERNET_EXPLORER": 4,
"OPERA": 5,
"EDGE": 1
}
},
[[snip]]
{
"start_time": "2017-09-07T00:00:00.000-07:00",
"end_time": "2017-09-08T00:00:00.000-07:00",
"total_events": 1675610,
"event_type_breakdown": {
"VIEW_CONTENT": 82831,
"PAGE_VIEW": 1592779
},
"os_type_breakdown": {
"IOS": 1363740,
"ANDROID": 311818,
"MAC_OS_X": 11,
"WINDOW": 40,
"LINUX": 1
},
"browser_type_breakdown": {
"BROWSER_TYPE_OTHER": 570,
"SAFARI": 1363719,
"CHROME": 311301,
"FIREFOX": 17,
"OPERA": 3
}
}
],
"domain": "abc.snapchat.com"
}
}
]
}
This endpoint retrieves the pixel stats for a specified domain. You can retrieve stats for a specific domain looking back 7 days from current time.
HTTP Request
GET https://adsapi.snapchat.com/v1/pixels/{pixel-id}/stats
Parameters
Parameter | Default | Description |
---|---|---|
pixel-id | Pixel ID |
Query Paramters
Query Parameter | Description | Required | Possible Values |
---|---|---|---|
start_time | Start Time (ISO 8601) | Yes | |
end_time | End Time (ISO 8601) | Yes | |
granularity | Granularity for the data | Yes | DAY, HOUR |
domain | Domain name | Yes | Valid domain name |
fields | Comma-separated list of fields to retrieve | Yes | EVENT_TYPE, OS_TYPE, BROWSER_TYPE |
Snap App ID
The Snap App ID is a unique ID set up by an advertiser to verify ownership of their apps, the Snap App ID maps to iOS and/or Android and is used for both App Install marketing and re-engagement via the Deep Link ad format.
Setting the Snap App ID
The Snap App ID is set up via Snap Business Manager using the App name and the app identifiers from the iOS Apple store (numerical value) and the Google Play Store (eg “com.x.y”), if you wish to share events with an MMP you can pick the MMP within the Snap App settings.
Once your Snap App ID has been set up via Snap Business Manager a Snap App entity will have been created under your Organization, it’s possible to fetch this entity via an API request.
Snap App entity attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
id | Snap App ID | Read-only | |
name | App name | Read-only | |
ios_app_id | iOS App ID | Read-only | numerical value from the Apple app store |
ios_app_id_verified | iOS verification status | Read-only | true |
android_app_url | Google Play store ID | Read-only | eg “com.x.y” |
android_app_url_verified | Android verification status | Read-only | true |
Get all Snap Apps under an Organization
curl "https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51098/mobile_apps?limit=200" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "6005af2e00ff056460e3b8f73e0001737e616473617069736300016275696c642d34343839623532342d312d3431342d3000010142",
"paging": {},
"mobile_apps": [
{
"sub_request_status": "SUCCESS",
"mobile_app": {
"id": "07b517bb-9cdb-42ef-ba77-9dd9a9eb2dc8",
"updated_at": "2020-05-28T12:17:48.744Z",
"created_at": "2020-05-28T12:17:01.757Z",
"container_kind": "Organizations",
"container_id": "8fdeefec-f502-4ca8-9a84-6411e0a51098",
"name": "The Kitty Cat App",
"visible_to": [
"OrganizationEntity_8fdeefec-f502-4ca8-9a84-6411e0a51098",
"AdAccountEntity_82225ba6-7559-4000-9663-bace8adff5f8"
]
}
},
{
"sub_request_status": "SUCCESS",
"mobile_app": {
"id": "9b5b83ec-c593-4a64-9c6d-a0eb9da0edb9",
"updated_at": "2020-12-08T22:33:32.204Z",
"created_at": "2020-09-29T22:33:48.661Z",
"container_kind": "Organizations",
"container_id": "8fdeefec-f502-4ca8-9a84-6411e0a51098",
"name": "The Badger tunneling app",
"visible_to": [
"OrganizationEntity_8fdeefec-f502-4ca8-9a84-6411e0a51098",
"AdAccountEntity_82225ba6-7559-4000-9663-bace8adff5f8"
],
"ios_app_id": "444433333",
"ios_app_id_verified": true,
"android_app_url": "com.badgertunneling.android"
}
}
]
}
This endpoint retrieves all Mobile Apps under an Organization.
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/mobile_apps
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID | |
limit | integer, min 50, max 1000 |
Get all Snap Apps under an Ad Account
curl "https://adsapi.snapchat.com/v1/adaccounts/7ebc489b-2120-47ed-95f8-3fe1b26ca997/mobile_apps" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "60abc6ea00ff0a33fdabf6a9c00001737e616473617069736300016275696c642d37356261303735372d312d3434392d3200010119",
"paging": {},
"mobile_apps": [
{
"sub_request_status": "SUCCESS",
"mobile_app": {
"id": "e1956376-a963-4000-8e54-84461bf59388",
"updated_at": "2021-05-07T12:35:57.591Z",
"created_at": "2021-04-23T13:01:46.816Z",
"container_kind": "Organizations",
"container_id": "7fdeefec-f502-4ca8-9a84-6411e0a51057",
"name": "Badger Mates",
"ios_app_id": "9876543210",
"android_app_url": "com.badger",
"mobile_measurement_partners": [
"ADJUST"
]
}
},
{
"sub_request_status": "SUCCESS",
"mobile_app": {
"id": "8b5b83ec-c593-4a64-9c6d-a0eb9da0edba",
"updated_at": "2021-03-19T07:45:53.009Z",
"created_at": "2020-09-29T22:33:48.661Z",
"container_kind": "Organizations",
"container_id": "7fdeefec-f502-4ca8-9a84-6411e0a51058",
"name": "Badger Timber Supplies",
"ios_app_id": "1234567890",
"ios_app_id_verified": true,
"android_app_url": "com.badgerexample.android",
"mobile_measurement_partners": [
"APPSFLYER",
"KOCHAVA"
]
}
}
]
}
This endpoint retrieves all Mobile Apps associated with an Ad Account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{adaccount_id}/mobile_apps
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Get a specific Snap App
curl "https://adsapi.snapchat.com/v1/mobile_apps/9b5b83ec-c593-4a64-9c6d-a0eb9da0edb9" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "6005afef00ff00ff53c3310c98d70001737e616473617069736300016275696c642d34343839623532342d312d3431342d3000010147",
"mobile_apps": [
{
"sub_request_status": "SUCCESS",
"mobile_app": {
"id": "9b5b83ec-c593-4a64-9c6d-a0eb9da0edb9",
"updated_at": "2020-12-08T22:33:32.204Z",
"created_at": "2020-09-29T22:33:48.661Z",
"container_kind": "Organizations",
"container_id": "8fdeefec-f502-4ca8-9a84-6411e0a51098",
"name": "The Badger tunneling app",
"visible_to": [
"OrganizationEntity_8fdeefec-f502-4ca8-9a84-6411e0a51098",
"AdAccountEntity_82225ba6-7559-4000-9663-bace8adff5f8"
],
"ios_app_id": "444433333",
"ios_app_id_verified": true,
"android_app_url": "com.badgertunneling.android",
"android_app_url_verified": true
}
}
]
}
This endpoint retrieves a specific Mobile App.
HTTP Request
GET https://adsapi.snapchat.com/v1/mobile_apps/{mobile_app_id}
Parameters
Parameter | Default | Description |
---|---|---|
snap_app_id | Mobile App ID |
Reach and Frequency Guide
Reach and Frequency buying allows advertisers to purchase reach-optimized campaigns via the API. This feature is currently in beta and available on a whitelist basis only. Please contact your Snap Account Manager to setup access.
Create R&F Campaign
- Campaign status must be set to ‘ACTIVE’
- buy_model must be set to ‘RESERVED’
- objective must be set to ‘BRAND_AWARENESS’
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"campaigns": [{"name": "Audience Filter Campaign", "ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1dab", "status": "ACTIVE", "start_time": "2018-08-11T22:00:00.000Z", "buy_model": "RESERVED", "objective": "BRAND_AWARENESS"}]}' \
"https://adsapi.snapchat.com/v1/adaccounts/3b0fbace-04b4-4f04-a425-33b5e0af1dab/campaigns"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b002ad00ff07e1f50fd2267f0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"campaigns": [
{
"sub_request_status": "success",
"campaign": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"updated_at": "2016-08-14T05:33:33.876Z",
"created_at": "2016-08-14T05:33:33.876Z",
"name": "Audience Filter Campaign",
"ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1dab",
"status": "ACTIVE",
"start_time": "2018-08-11T22:00:00.000Z",
"objective": "BRAND_AWARENESS",
"buy_model": "RESERVED"
}
}
]
}
This will create a campaign within a specified ad account. Once a R&F campaign is booked we do not allow for edits to the campaign or ad squad. Edits, or a re-booking, is only allowed if the initial booking fails.
Re-booking is done only if your initial R&F Ad Squad booking request is FAILED. In addition, we reserve the right to remove any advertiser from the R&F program if we see an excessive number of cancellations.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/campaigns
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Forecasting Request
Before creating the Reach & Frequency Ad Squad you will need to make a forecasting request using the Ad Squad with the placement, targeting spec and frequency cap that you wish to use.
The forecasting request will return a reach curve showing the estimated reach based on your targeting and which budget you need to apply for a certain estimated reach.
- Reach & Frequency Lenses and Single Image and Video ads are currently available in the Australia, Belgium, Brazil, Canada, Denmark, France, Germany, India, Ireland, Italy, Kuwait, Mexico, Netherlands, Norway, Saudi Arabia, Spain, Sweden, UAE, UK, and US.
- Minimum reach of at least 500,000 unique users.
- Booking / Set-Up Timing: No less than 12 hours in advance and no greater than 365 days from current time.
- Radius targeting and LOI targeting are not permitted.
- Customer List targeting is allowed but dependent on Customer List segments being available for forecasting.
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"placement_v2":{"config":"AUTOMATIC"},"targeting":{"geos":[{"country_code":"us"}],"demographics":[{"gender":"MALE"}]},"delivery_constraint":"REACH_AND_FREQUENCY","start_time":"2020-08-28T14:08:04+01:00","end_time":"2020-09-29T14:08:04+01:00","optimization_goal":"VIDEO_VIEWS","cap_and_exclusion_config":{"frequency_cap_config":[{"frequency_cap_count":1,"frequency_cap_type":"IMPRESSIONS","time_interval":7,"frequency_cap_interval":"DAYS"}]}}' \
"https://adsapi.snapchat.com/v1/adaccounts/3b0fbace-04b4-4f04-a425-33b5e0af1dab/reserved_forecasting"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b3e5c9600ff0675dc615cb9090001737e616473617069736300016275696c642d31346237626365612d312d3138312d300001010b",
"reach_frequency_curve": [
{
"impression": 254240,
"reach": 250320,
"budget_micro": 610557576
},
{
"impression": 1300320,
"reach": 1211840,
"budget_micro": 3121198726
},
// snip
{
"impression": 102770081,
"reach": 29095360,
"budget_micro": 729561535468
},
{
"impression": 104879041,
"reach": 29445920,
"budget_micro": 847933759640
}
],
"display_message": "",
"debug_message": "",
}
}
Required Ad Squad attributes - Forecasting request
Attribute | Description | Possible Values |
---|---|---|
placement_v2 | Placement for the Ads | Placement V2 |
targeting | Targeting of the Ads | Targeting Spec |
delivery_constraint | REACH_AND_FREQUENCY | |
start_time | Start time | |
end_time | End time | |
type | Ad Squad type | SNAP_ADS, LENS |
optimization_goal | Optimization Goal based on Ad Squad type | For SNAP_ADS the optimization_goal has to be VIDEO_VIEWS, for LENS the optimization_goal has to be USES |
cap_and_exclusion_config | Frequency Cap Spec |
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/reserved_forecasting
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create R&F Ad Squad
When creating the Reach & Frequency ad squad you should use the same Ad Squad values used in the Forecast request for Placement V2, targeting and frequency cap. Additionally you should also use the values impression
, reach
and budget_micro
returned in the forecast.
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adsquads": [{"name": "Snap Ad, United States, All Genders, All Ages", "placement_v2": {"config": "AUTOMATIC"}, "start_time": "2018-07-08T15:13:36-07:00", "end_time": "2018-08-07T15:13:36-07:00", "delivery_constraint": "REACH_AND_FREQUENCY", "pixel_id": null, "campaign_id": "319bcd47-3d99-4d3b-a39a-33c3fbea470b", "daily_budget_micro": null, "targeting": {"geos": [{"country_code": "us"}]}, "cap_and_exclusion_config": {"frequency_cap_config": [{"frequency_cap_count": 2, "time_interval": 7, "frequency_cap_interval": "DAYS", "frequency_cap_type": "IMPRESSIONS"}]},"type": "SNAP_ADS", "conversion_window": null, "status": "ACTIVE", "auto_bid": false, "optimization_goal": "VIDEO_VIEWS", "reach_goal": 39084400, "impression_goal": 132528801, "lifetime_budget_micro": 484048584430, "reach_and_frequency_status": "PENDING"}]}' \
https://adsapi.snapchat.com/v1/campaigns/a09f983a-06ac-4081-9659-7bc9e1cd6888/adsquads
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b3e983d00ff059adbd17a39bd0001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d31623031633134632d312d3138322d3000010116",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "5fd79efb-e544-4d43-9e59-9e6a88f8232e",
"updated_at": "2018-07-05T22:14:21.824Z",
"created_at": "2018-07-05T22:14:21.824Z",
"name": "Snap Ad, United States, All Genders, All Ages",
"status": "ACTIVE",
"campaign_id": "319bcd47-3d99-4d3b-a39a-33c3fbea470b",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": false,
"lifetime_budget_micro": 484048584430,
"start_time": "2018-07-08T22:13:36.000Z",
"end_time": "2018-08-07T22:13:36.000Z",
"optimization_goal": "VIDEO_VIEWS",
"impression_goal": 132528801,
"reach_goal": 39084400,
"cap_and_exclusion_config": {
"frequency_cap_config": [
{
"frequency_cap_count": 2,
"frequency_cap_type": "IMPRESSIONS",
"time_interval": 7,
"frequency_cap_interval": "DAYS"
}
],
"is_industry_exclusive": false,
"is_industry_competitively_separated": false
},
"delivery_constraint": "REACH_AND_FREQUENCY",
// Will automatically update to ACTIVE or FAILED
"reach_and_frequency_status": "PENDING",
"reach_and_frequency_rate_micro": 3652402
}
}
]
}
This creates an Ad Squad within a Campaign. For R&F Ad Squads there can only be one Ad Squad under a Campaign.
Attributes for R&F Ad Squad
Attribute | Description | Required | Possible Values |
---|---|---|---|
campaign_id | Campaign ID | R | |
bid_micro | Max Bid (micro-currency) | Must not be included | |
billing_event | Billing Event | R | IMPRESSION |
daily_budget_micro | Daily Budget (micro-currency) | R | Must be set to null |
start_time | Start time | R | Must be greater than or equal to 2 days and less than or equal to 90 days from current time |
end_time | End time | R | DIfference between end_time and start_time must be greater than or equal to 3 days and less than or equal to 90 days |
name | Ad Squad name | R | |
optimization_goal | Optimization Goal | R | Must be set to VIDEO_VIEWS (Optimizes for Reach and Frequency) for Snap Ads, or USES for Lenses |
placement_v2 | Placement | R | Json object containing advanced placement options See placement_v2 |
status | Ad Squad status | R | Must be set to ACTIVE |
targeting | Targeting spec | R | |
type | Ad Squad Type | R | SNAP_ADS, LENS |
included_content_types | Content Type to be included | O | NEWS, ENTERTAINMENT, SCIENCE_TECHNOLOGY, BEAUTY_FASHION, MENS_LIFESTYLE, WOMENS_LIFESTYLE, GENERAL_LIFESTYLE, FOOD, SPORTS, YOUNG_BOLD |
excluded_content_types | Content Type to be excluded | O | NEWS, ENTERTAINMENT, SCIENCE_TECHNOLOGY, BEAUTY_FASHION, MENS_LIFESTYLE, WOMENS_LIFESTYLE, GENERAL_LIFESTYLE, FOOD, SPORTS, YOUNG_BOLD |
cap_and_exclusion_config | The frequency cap and exclusion spec | R | |
lifetime_budget_micro | Lifetime budget (micro-currency) | R | Must match the desired budget value defined as budget_micro in the forecasting request |
reach_goal | Reach goal as specified in the Forecasting request | R | Must match the reach value in the forecasting request |
impression_goal | Impression goal as specified in the Forecasting request | R | Must match the impression value in the forecasting request |
ad_scheduling_config | The schedule for running ads | N/A | Should not be set |
auto_bid | Allow Snapchat to automatically set the bid to recommended amount | R | Must be set to false |
target_bid | Allows Snapchat to adjust the bid aiming to keep your average CPA at or below the amount set by the ad set end date | R | Must be set to false |
pixel_id | Pixel to be associated with the Ad Squad | O | |
delivery_constraint | Type of delivery | R | REACH_AND_FREQUENCY |
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 |
HTTP Request
POST https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads
Parameters
Parameter | Default | Description |
---|---|---|
campaign_id | Campaign ID |
Updating R&F Ad Squads and Rebooking
Once you create an AdSquad the reach_and_frequency_status will be PENDING. This will be automatically updated to ACTIVE or FAILED by our booking service within a minute. If it is FAILED, you can rebook with the same Ad Squad by doing an UPDATE on the AdSquad.
You would issue a new Forecasting Request and then update the Ad Squad, providing the ID, while setting the reach_and_frequency_status from FAILED to PENDING, passing new impression_goal, reach_goal, and lifetime_budget_micro values from the forecast.
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adsquads": [{"id": "39df6afb-fbea-4a9d-8b5e-8899ab4f4890", "name": "Snap Ad, United States, All Genders, All Ages", "type": "SNAP_AD", "status": "ACTIVE", "campaign_id": "cfeb4b9c-8464-4498-9906-b4eb2d6c56ac", "placement_v2": {"config": "AUTOMATIC"}, "auto_bid": false, "lifetime_budget_micro": 200000000000, "optimization_goal": "VIDEO_VIEWS", "targeting": {"geos": [{"operation": "INCLUDE", "country_code": "us"}], "regulated_content": false}, "start_time": "2018-07-08T15:13:36-07:00", "end_time": "2018-08-07T15:13:36-07:00", "cap_and_exclusion_config": {"frequency_cap_config": [{"frequency_cap_count": 4, "time_interval": 7, "frequency_cap_interval": "DAYS", "frequency_cap_type": "IMPRESSIONS"}]}, "delivery_constraint": "REACH_AND_FREQUENCY", "reach_goal": 2263600, "lifetime_budget_micro": 200000000000, "impression_goal": 13975600, "reach_and_frequency_status": "PENDING"}]}'
https://adsapi.snapchat.com/v1/campaigns/cfeb4b9c-8464-4498-9906-b4eb2d6c56ac/adsquads
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b3e983d00ff059adbd17a39bd0001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d31623031633134632d312d3138322d3000010116",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "5fd79efb-e544-4d43-9e59-9e6a88f8232e",
"updated_at": "2018-07-05T22:14:21.824Z",
"created_at": "2018-07-05T22:14:21.824Z",
"name": "Snap Ad, United States, All Genders, All Ages",
"status": "ACTIVE",
"campaign_id": "319bcd47-3d99-4d3b-a39a-33c3fbea470b",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": false,
"lifetime_budget_micro": 200000000000,
"start_time": "2018-07-08T22:13:36.000Z",
"end_time": "2018-08-07T22:13:36.000Z",
"optimization_goal": "VIDEO_VIEWS",
"impression_goal": 13975600,
"reach_goal": 2263600,
"cap_and_exclusion_config": {
"frequency_cap_config": [
{
"frequency_cap_count": 4,
"frequency_cap_type": "IMPRESSIONS",
"time_interval": 7,
"frequency_cap_interval": "DAYS"
}
],
"is_industry_exclusive": false,
"is_industry_competitively_separated": false
},
"delivery_constraint": "REACH_AND_FREQUENCY",
// Will automatically update to ACTIVE or FAILED
"reach_and_frequency_status": "PENDING",
"reach_and_frequency_rate_micro": 3652402
}
}
]
}
This endpoint will update a specified ad squad.
Attributes that must be updated
Attribute | Description |
---|---|
reach_and_frequency_status | Must be set back to PENDING |
impression_goal | Must be set to new value from new forecasting request |
reach_goal | Must be set to new value from new forecasting request |
lifetime_budget_micro | Must be set to new value from new forecasting request |
HTTP Request
PUT https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads
Parameters
Parameter | Default | Description |
---|---|---|
campaign_id | Campaign ID |
Create the Ad
R&F can be used with creatives of type Snap Ads or type Lens. Ads follow the type of creative as explained here
Cancelling R&F booking
There are four ways to cancel a booking. Please be aware that cancelling bookings frequently will lead to removal from the R&F program.
- Updating the AdSquad status to PAUSED
- Deleting the AdSquad
- Updating the Campaign status to PAUSED
- Deleting the Campaign
Dynamic Product Ads Guide
Dynamic ads power personalized ad experiences in an automated way.
Product Catalog
A detailed spec of the Catalog and available file formats can be found in the following article, the current item limit of a Product Catalog is 10 million items. The permission Organization Admin
is required to create, update or delete a Product Catalog.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | R | max 375 characters | |
organization_id | Organization ID | R | |
vertical | R | UNKNOWN_VERTICAL, COMMERCE, HOTELS, PLACES, FLIGHTS | |
source | Indicates the source of Catalog, set automatically on creation | Read-only | BUSINESS_MANAGER, FEED, WOOCOMMERCE, SHOPIFY |
default_product_set_id | Default product set that includes all the products in the catalog | Read-only | |
event_sources | List of Pixel IDs and/or the Snap App IDs that reports events for the Catalog | O | [ {“id”: “aa1a11aa-a111-1a11-1a1a-a1aa1aa1aaa”,“type”: “MOBILE_APP”}, {“id”: “2bbb22b2-b22bb-2bb2-22b2-222b22b222bb”,“type”: “PIXEL”} ] |
API Limits
- Max # of catalogs per organization: 200
- Max # of catalogs per batch: 10
- Catalog name length: 1-375
Create a Catalog
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"catalogs": [{"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058","name": "Honeybear Catalog","vertical": "COMMERCE","event_sources": [{"id": "aa1a11aa-a111-1a11-1a1a-a1aa1aa1aaa","type": "PIXEL"},{"id": "2bbb22b2-b22bb-2bb2-22b2-222b22b222bb","type": "MOBILE_APP"}] }]}' \
"https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/catalogs"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f73b68a00ff0e59830e4d95c80001737e616473617069736300016275696c642d63326234383933652d312d3338392d3000010129",
"catalogs": [
{
"sub_request_status": "SUCCESS",
"catalog": {
"created_at": "2020-09-29T22:34:52.540013Z",
"updated_at": "2020-09-29T22:34:52.540013Z",
"id": "39ae292e-7ec7-4ed7-a0c4-7567731e9c78",
"name": "Honeybear Catalog",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"event_sources": [
{
"id": "2bbb22b2-b22bb-2bb2-22b2-222b22b222bb",
"type": "MOBILE_APP"
},
{
"id": "aa1a11aa-a111-1a11-1a1a-a1aa1aa1aaa",
"type": "PIXEL"
}
],
"default_product_set_id": "728912bf-4402-49d9-aa38-9b60fb98ee73",
"vertical": "COMMERCE"
}
}
]
}
This creates a Catalog under the organization
HTTP Request
POST https://adsapi.snapchat.com/v1/organizations/{organization_id}/catalogs
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Update a Catalog
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"catalogs": [{"id":"39ae292e-7ec7-4ed7-a0c4-7567731e9c78","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058","name": "Honeybear Catalog II","vertical": "COMMERCE","event_sources": [{"id": "aa1a11aa-a111-1a11-1a1a-a1aa1aa1aaa","type": "PIXEL" },{"id": "bb1b11bb-b111-1b11-1b1b-b1bb1bb1bbb","type": "PIXEL" },{ "id": "2bbb22b2-b22bb-2bb2-22b2-222b22b222bb", "type": "MOBILE_APP"}]}]}'
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/catalogs
The above request updates the name of the Catalog and adds an additional PIXEL to the event_sources, it returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f73cddc00ff0167a5aa92d5900001737e616473617069736300016275696c642d63326234383933652d312d3338392d300001012c",
"catalogs": [
{
"sub_request_status": "SUCCESS",
"catalog": {
"created_at": "2020-09-29T22:34:52.540013Z",
"updated_at": "2020-09-30T00:14:20.491333Z",
"id": "39ae292e-7ec7-4ed7-a0c4-7567731e9c78",
"name": "Honeybear Catalog II",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"event_sources": [
{
"id": "aa1a11aa-a111-1a11-1a1a-a1aa1aa1aaa",
"type": "PIXEL"
},
{
"id": "bb1b11bb-b111-1b11-1b1b-b1bb1bb1bbb",
"type": "PIXEL"
},
{
"id": "2bbb22b2-b22bb-2bb2-22b2-222b22b222bb",
"type": "MOBILE_APP"
}
],
"default_product_set_id": "728912bf-4402-49d9-aa38-9b60fb98ee73",
"vertical": "COMMERCE"
}
}
]
}
This request updates the specified Catalog.
Attributes that can be updated
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | End time | R | |
event_sources | The Pixel IDs and/or the Snap App IDs that reports events for the Catalog | O | {“id”: “aa1a11aa-a111-1a11-1a1a-a1aa1aa1aaa”,“type”: “MOBILE_APP”}, {“id”: “2bbb22b2-b22bb-2bb2-22b2-222b22b222bb”,“type”: “PIXEL”} ] |
HTTP Request
PUT https://adsapi.snapchat.com/v1/organizations/{organization_id}/catalogs
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Get All Catalogs
curl
"https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/catalogs?limit=100" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5d6f282800ff099634a02909d20001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d36373633363336342d312d3238352d300001014e",
"catalogs": [
{
"sub_request_status": "SUCCESS",
"catalog": {
"created_at": "2020-09-29T22:34:52.540013Z",
"updated_at": "2020-09-30T00:14:20.491333Z",
"id": "39ae292e-7ec7-4ed7-a0c4-7567731e9c78",
"name": "Honeybear Catalog II",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"event_sources": [
{
"id": "aa1a11aa-a111-1a11-1a1a-a1aa1aa1aaa",
"type": "PIXEL"
},
{
"id": "fb5b83ec-c593-4a64-9c6d-a0eb9da0edba",
"type": "MOBILE_APP"
},
{
"id": "bb1b11bb-b111-1b11-1b1b-b1bb1bb1bbb",
"type": "PIXEL"
}
],
"default_product_set_id": "728912bf-4402-49d9-aa38-9b60fb98ee73",
"vertical": "COMMERCE"
}
},
...
{
"sub_request_status": "SUCCESS",
"catalog": {
"created_at": "2020-09-29T21:49:51.063514Z",
"updated_at": "2020-09-29T21:49:51.063514Z",
"id": "419f565a-ae00-40b5-b159-3c5b051f742a",
"name": "Honeybear Catalog",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"default_product_set_id": "10e7d339-0ff1-434a-996a-94d34918c948",
"vertical": "COMMERCE"
}
},
],
"paging": {
"next_link": "https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/catalogs?cursor=def456&limit=100"
}
}
This request will retrieve a list of all the catalogs within an organization
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/catalogs
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Get a specific Catalog
curl
"https://adsapi.snapchat.com/v1/catalogs/0e854f6a-523a-4f9e-8b82-5a9071e023a6" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f7ef67500ff053956b806c94a0001737e616473617069736300016275696c642d31663731616139352d312d3339312d3100010118",
"catalogs": [
{
"sub_request_status": "SUCCESS",
"catalog": {
"created_at": "2020-09-29T22:23:37.676100Z",
"updated_at": "2020-09-29T22:23:37.676100Z",
"id": "0e854f6a-523a-4f9e-8b82-5a9071e023a6",
"name": "Honeybear Catalog",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"event_sources": [
{
"id": "aa1a11aa-a111-1a11-1a1a-a1aa1aa1aaa",
"type": "PIXEL"
}
],
"default_product_set_id": "b6d35541-d5b6-4e06-a400-03f9937392cc",
"vertical": "COMMERCE"
}
}
]
}
This request retrieves a specific Catalog.
HTTP Request
GET https://adsapi.snapchat.com/v1/catalogs/{catalog_id}
Parameters
Parameter | Default | Description |
---|---|---|
catalog_id | Catalog ID |
Delete a Catalog
curl -X DELETE "https://adsapi.snapchat.com/v1/catalogs/bbe607b2-03ab-4387-9cb6-0cc6c2cc4b44" \
-H "Authorization: Bearer meowmeowmeow"
The above request returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f74cc3a00ff02642c414049a30001737e616473617069736300016275696c642d63326234383933652d312d3338392d300001010f",
"catalogs": []
}
This request deletes a specific Catalog.
HTTP Request
DELETE https://adsapi.snapchat.com/v1/catalogs/{catalog_id}
Parameters
Parameter | Default | Description |
---|---|---|
catalog_id | Catalog ID |
ERRORS
Error | Cause |
---|---|
CAT_VALIDATION_ERROR_TOO_MANY_CATALOGS_IN_BATCH | Thrown when there are too many catalogs in a batch |
CAT_VALIDATION_ERROR_INVALID_PAGINATION_READ_LIMIT | Thrown if the read limit specified by user is invalid |
CAT_VALIDATION_ERROR_READ_LIMIT_MUST_BE_SPECIFIED | Thrown if only pagination cursor is provided but not an explicit read limit |
CAT_VALIDATION_ERROR_INVALID_CURSOR | Thrown if the pagination cursor provided by the user is invalid |
NOT_FOUND | Thrown when catalog is not found |
FORBIDDEN | Thrown when catalog cannot be accessed by this user |
Product Feed
The relationship between a Catalog and a Product feed is currently 1:1, there can only ever be one Product Feed under a Catalog.
Product Feed attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | R | max 375 characters | |
catalog_id | The Catalog ID | R | |
status | O | ACTIVE (default) | |
default_currency | The Currency used by the feed using the three letter ISO 4217 code | R | AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHE, CHF, CHW, CLF, CLP, CNY, COP, COU, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, SSP, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USN, UYI, UYU, UYW, UZS, VES, VND, VUV, WST, XAF, XBC, XCD, XOF, XPF, XSU, XUA, YER, ZAR, ZMW, ZWL |
schedule | Json configuration which defines the schedule for fetching the product feed | O | See schedule attributes below |
Sample schedule #1 - This schedule is set to fetch a non-password protected feed 15 minutes past every hour given the America/Los_Angeles timezone
"schedule": {
"interval_type": "HOURLY",
"timezone": "America/Los_Angeles",
"minute": 15,
"url": "https://example.com/product_feed.csv"
}
Sample schedule #2 - This schedule is set to fetch a non-password protected every Tuesday at 6 am given the Europe/Berlin timezone, since minute is left out it defaults to 0
"schedule": {
"interval_type": "WEEKLY",
"timezone": "Europe/Berlin",
"hour": 6,
"day_of_week": "TUESDAY",
"url": "https://example.com/product_feed.csv"
}
Sample schedule #3 - This schedule is set to fetch a password protected FTP hosted feed on the 10th day of every month at 6:30 AM given the Europe/London timezone
"schedule": {
"interval_type": "MONTHLY",
"timezone": "Europe/London",
"day_of_month": 10,
"hour": 06,
"minute": 30,
"url": "ftp://example.com/product_feed.csv"
"username": "H0neyBadger",
"password": "BeezAreCool99"
}
Schedule attributes
The schedule attribute allows you to define how often Snap should fetch your Product Feed, the attributes you can use vary depending on the interval type that you pick.
Schedule attribute | Description | Required | Possible Values |
---|---|---|---|
url | The FTP/SFTP/HTTP/HTTPS URL including file name where the product feed is to be fetched from | R | |
username | The username to access the product feed | O/Required if url is password protected | |
password | The password to access the product feed | O/Required if url is password protected | |
timezone | The time zone used for the schedule, default timezone is UTC | O | |
interval_type | The interval by which the product feed will be fetched | R | HOURLY, DAILY, WEEKLY, MONTHLY |
interval_count | Specifies number of intervals between the feed being fetched | See below table | See below table |
day_of_month | Represents a day of the month | See below table | 1-31 |
day_of_week | Represents a day of the week | See below table | MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY |
hour | Represents the hour setting | See below table | 00-23 |
minute | Represents the minute setting | See below table | 00-59 |
interval_type required values
Different interval settings require different attributes, this table outlines which attributes that can be included.
interval_type | day_of_month | day_of_week | hour | minute | interval_count | interval_count value |
---|---|---|---|---|---|---|
MONTHLY | R | - | R | R | - | - |
WEEKLY | - | R | R | R | - | - |
DAILY | - | - | R | R | O | 1-31 , specifies the number of days in between each fetch |
HOURLY | - | - | - | R | O | 1-23 , specifies the number of hours in between each fetch |
Create a Product Feed
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"product_feeds":[{"catalog_id":"419f565a-ae00-40b5-b159-3c5b051f742a","name":"Badger Burrow supplies","default_currency":"USD","status":"ACTIVE","schedule":{"url":"ftp://93.184.216.34/timber_product_feed.csv","username":"H0neyBadger","password":"BeezAreCool99","interval_type":"HOURLY","interval_count":"1","timezone":"PST","minute":"15"}}]}' \
"https://adsapi.snapchat.com/v1/catalogs/419f565a-ae00-40b5-b159-3c5b051f742a/product_feeds"
The above request returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f74db4600ff0d85ee173e68b30001737e616473617069736300016275696c642d63326234383933652d312d3338392d3000010149",
"product_feeds": [
{
"sub_request_status": "SUCCESS",
"product_feed": {
"created_at": "2020-09-30T19:23:51.441770Z",
"updated_at": "2020-09-30T19:23:51.441770Z",
"id": "63397464-b02e-4da5-93d7-fc00e4ac9a5b",
"catalog_id": "419f565a-ae00-40b5-b159-3c5b051f742a",
"name": "Badger Burrow supplies",
"default_currency": "USD",
"schedule": {
"interval_type": "HOURLY",
"timezone": "PST",
"minute": 15,
"interval_count": 1,
"url": "ftp://93.184.216.34/timber_product_feed.csv"
}
}
}
]
}
This request creates a Product Feed, it allows for the option to specify a schedule and URL for retrieving an updated Product Feed.
HTTP Request
POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/product_feeds
Parameters
Parameter | Default | Description |
---|---|---|
feed_id | Feed ID |
Update a Product Feed
curl -X PUT \
-d '{"product_feeds":[{"id":"b5139779-d001-4f12-ae33-d86a2faf05a6","catalog_id":"79ae292e-7ec7-4ed7-a0c4-7567731e9c78","name":"Badger Burrow supplies","default_currency":"GBP","status":"ACTIVE","schedule":{"url":"ftp://93.184.216.34/timber_product_feed.csv","username":"H0neyBadger","password":"BeezAreCool99","interval_type":"HOURLY","interval_count":"4","timezone":"PST","hour":"12","minute":"30"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/catalogs/39ae292e-7ec7-4ed7-a0c4-7567731e9c78/product_feeds
The above request returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f74bfb500ff05f08282c21d6d0001737e616473617069736300016275696c642d63326234383933652d312d3338392d300001012e",
"product_feeds": [
{
"sub_request_status": "SUCCESS",
"product_feed": {
"created_at": "2020-09-30T16:09:20.748830Z",
"updated_at": "2020-09-30T17:26:13.749843Z",
"id": "b5139779-d001-4f12-ae33-d86a2faf05a6",
"catalog_id": "79ae292e-7ec7-4ed7-a0c4-7567731e9c78",
"name": "Badger Burrow supplies",
"default_currency": "GBP",
"schedule": {
"interval_type": "HOURLY",
"timezone": "PST",
"minute": 30,
"interval_count": 4,
"url": "ftp://93.184.216.34/timber_product_feed.csv"
}
}
}
]
}
This request updates a specific Product Feed.
HTTP Request
PUT https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/product_feeds
Parameters
Parameter | Default | Description |
---|---|---|
feed_id | Feed ID |
Get all Product Feeds
curl
"https://adsapi.snapchat.com/v1/catalogs/19bc3acf-20ce-444f-9829-c3e635ead3a9/product_feeds" \
-H "Authorization: Bearer meowmeowmeow"
The above request returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f74d7e000ff0ec7804b0e6f540001737e616473617069736300016275696c642d63326234383933652d312d3338392d3000010105",
"product_feeds": [
{
"sub_request_status": "SUCCESS",
"product_feed": {
"created_at": "2020-09-30T18:49:46.429529Z",
"updated_at": "2020-09-30T18:49:54.681827Z",
"id": "72cffebf-b91b-4af7-a8b9-d2a91e51b456",
"catalog_id": "19bc3acf-20ce-444f-9829-c3e635ead3a9",
"name": "Badger Burrow supplies",
"default_currency": "EUR",
"schedule": {
"interval_type": "WEEKLY",
"timezone": "CET",
"hour": 6,
"interval_count": 1,
"day_of_week": "TUESDAY",
"url": "ftp://93.184.216.34/timber_product_feed.csv"
}
}
}
]
}
This request lists all Product Feeds under the Catalog, at the moment there can only be one Product Feed under the catalog.
HTTP Request
GET https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/product_feeds
Parameters
Parameter | Default | Description |
---|---|---|
feed_id | Feed ID |
Get a specific Product Feed
curl
"https://adsapi.snapchat.com/v1/product_feeds/b5139779-d001-4f12-ae33-d86a2faf05a9" \
-H "Authorization: Bearer meowmeowmeow"
The above request returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f74d7f300ff025b1dcfd518760001737e616473617069736300016275696c642d63326234383933652d312d3338392d3000010136",
"product_feeds": [
{
"sub_request_status": "SUCCESS",
"product_feed": {
"created_at": "2020-09-30T16:09:20.748830Z",
"updated_at": "2020-09-30T17:26:51.410921Z",
"id": "b5139779-d001-4f12-ae33-d86a2faf05a9",
"catalog_id": "39ae292e-7ec7-4ed7-a0c4-7567731e9c78",
"name": "Badger Burrow Supplies",
"default_currency": "GBP",
"schedule": {
"interval_type": "HOURLY",
"timezone": "PST",
"minute": 30,
"interval_count": 4,
"url": "ftp://93.184.216.34/timber_product_feed.csv"
}
}
}
]
}
This request returns a specific Product Feed based on the Product Feed id.
HTTP Request
GET https://adsapi.snapchat.com/v1/product_feeds/{product_feed_id}
Parameters
Parameter | Default | Description |
---|---|---|
feed_id | Feed ID |
Delete a Product Feed
curl -X DELETE "https://adsapi.snapchat.com/v1/product_feeds/ab2ac629-b218-4699-9e19-6946d17faaa3" \
-H "Authorization: Bearer meowmeowmeow"
The above request returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f74d24400ff06f46ef9a8b6c00001737e616473617069736300016275696c642d63326234383933652d312d3338392d3000010155",
"product_feeds": []
}
This request deletes a specific Product Feed.
HTTP Request
DELETE https://adsapi.snapchat.com/v1/product_feeds/{product_feed_id}
Parameters
Parameter | Default | Description |
---|---|---|
product_feed_id | Feed ID |
Feed Upload
A Feed Upload is an individual upload of new data to the Product feed, when using the Product Feed schedule attribute the Feed Uploads are created automatically by the API at the set timings as specified by the schedule setting.
It’s possible to create a Feed Upload without using the schedule attribute, this is suitable for feeds that remain largely static and only need to be updated occasionally. Such an upload is referred to as a one time upload, one time uploads can only happen in product feeds where there is no schedule attribute defined.
Feed Upload attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
url | The FTP/SFTP/HTTP/HTTPS URL including file name where the product feed is to be fetched from | R | |
update_type | Indicates the type of update, REPLACE means existing product feed will be replaced by the new file, UPSERT means products in the uploaded file will be updated or added to the product feed, any products already in the product feed but missing in the file will be preserved | R | REPLACE, UPSERT |
username | The username to access the product feed | O/Required if url is password protected | |
password | The password to access the product feed | O/Required if url is password protected | |
id | The id of the upload | Read only | |
feed_id | The product feed id | Read only | |
status | Indicates the current status of the upload | Read only | INITIALIZED, FETCHING, PROCESSING, COMPLETE, ERRORED |
summary | A summary of the items affected by the upload including errors and recommendations | Read only |
Feed Upload Status
Status attribute | Description |
---|---|
INITIALIZED | The feed upload has been created and is expected to start downloading soon |
FETCHING | The file is currently being downloaded |
PROCESSING | The file is downloaded and the catalog is being updated |
COMPLETE | The file was downloaded and the catalog was updated |
ERRORED | All products in the upload failed because of a problem with the download or with the file |
Feed Upload Summary
Summary attribute | Description | Possible Values |
---|---|---|
total_items | Total number of items affected by the upload | |
items_modified | Number of items that were modified by the upload | |
items_deleted | Number of items that were deleted by the upload | |
items_errored | Number of items that has an error | |
items_with_warnings | Number of items that have a warning | |
issues_summary | Summary of all errors and recommendations | see errors and recommendations |
Errors and Recommendations
Recommendation | Description |
---|---|
CAT_RECOMMENDATION_MISSING_APP_INSTALL_PROPERTIES | Properties required to run App Install Ads haven’t been provided. |
CAT_RECOMMENDATION_MISSING_DEEP_LINK_PROPERTIES | Properties required to run Deep Link Ads haven’t been provided. |
Error | Description |
---|---|
CAT_VALIDATION_ERROR_CATALOG_ID_INVALID | Catalog id is invalid/malformed |
CAT_VALIDATION_ERROR_EVENT_SOURCE_ID_INVALID | Event source id is invalid/malformed |
CAT_VALIDATION_ERROR_FEED_ID_INVALID | Feed id is invalid/malformed |
CAT_VALIDATION_ERROR_UPLOAD_ID_INVALID | Upload id is invalid/malformed |
CAT_VALIDATION_ERROR_FILTER_ID_INVALID | Filter id is invalid/malformed |
CAT_VALIDATION_ERROR_ORGANIZATION_ID_INVALID | Organization id is invalid/malformed |
CAT_VALIDATION_ERROR_PRODUCT_SET_ID_INVALID | Product set id is invalid/malformed |
CAT_VALIDATION_ERROR_SNAP_PRODUCT_ID_INVALID | Snap product id is invalid |
CAT_VALIDATION_ERROR_PRODUCT_SCAN_FILTER_INVALID | Product scan filter is invalid |
CAT_VALIDATION_ERROR_REQUIRED_INPUT_PARAMETER_EMPTY | Required parameter is empty |
CAT_VALIDATION_ERROR_REQUIRED_INPUT_PARAMETER_NULL | Required parameter cannot be null |
CAT_VALIDATION_ERROR_DUPLICATE_PRODUCT | Duplicate Product detected. Please make sure product ‘id’ is unique |
CAT_VALIDATION_ERROR_DEEP_LINK_INVALID | Link is invalid |
CAT_VALIDATION_ERROR_IMAGE_LINK_INVALID | Image Link must be a well formed URL |
CAT_VALIDATION_ERROR_PRODUCT_TYPE_INVALID | Product Type is invalid |
CAT_VALIDATION_ERROR_BRAND_INVALID | Brand is invalid |
CAT_VALIDATION_ERROR_ICON_MEDIA_URL_INVALID | Icon Media Link must be a well formed URL |
CAT_VALIDATION_ERROR_DEEP_LINK_APP_NAME_INVALID | App Name is invalid |
CAT_VALIDATION_ERROR_DEEP_LINK_ANDROID_INFO_INVALID | Android Information is invalid/malformed |
CAT_VALIDATION_ERROR_DEEP_LINK_STORE_ID_INVALID | Apple Store ID is invalid/malformed |
CAT_VALIDATION_ERROR_PRODUCT_LINK_INVALID | Product Link must be a well formed URL |
CAT_VALIDATION_ERROR_MOBILE_LINK_INVALID | Mobile Link must be a well formed URL |
CAT_VALIDATION_ERROR_ADDITIONAL_IMAGES_LINK_INVALID | The additional image Link must be a well formed URL |
CAT_VALIDATION_ERROR_ADDITIONAL_IMAGES_TAG_INVALID | Image Tags for additional images is not valid |
CAT_VALIDATION_ERROR_TOO_MANY_TAGS | Too many tags have been used for a product |
CAT_VALIDATION_ERROR_TOO_MANY_ADDITIONAL_IMAGES | Too many additional images have been used for a product |
CAT_VALIDATION_ERROR_PRODUCT_CONDITION_INVALID | Product condition value is invalid |
CAT_VALIDATION_ERROR_AVAILABILITY_INVALID | Product availability value is invalid |
CAT_VALIDATION_ERROR_ADULT_INVALID | Adult value is invalid |
CAT_VALIDATION_ERROR_REQUIRED_INPUT_PARAMETER_TOO_LARGE | Parameter is too large |
CAT_VALIDATION_ERROR_SALE_PRICE_EFFECTIVE_DATE_INVALID | Sale Price Effective Date is invalid/malformed |
CAT_VALIDATION_ERROR_GTIN_INVALID | GTIN value is invalid |
CAT_VALIDATION_ERROR_MPN_INVALID | MPN value is invalid |
CAT_VALIDATION_ERROR_COLOR_INVALID | Color value is invalid |
CAT_VALIDATION_ERROR_GENDER_INVALID | Gender value is invalid |
CAT_VALIDATION_ERROR_MATERIAL_INVALID | Material value is invalid |
CAT_VALIDATION_ERROR_PATTERN_INVALID | Pattern is value invalid |
CAT_VALIDATION_ERROR_SIZE_INVALID | Size value is invalid |
CAT_VALIDATION_ERROR_ITEM_GROUP_ID_INVALID | Item Group ID is invalid |
CAT_VALIDATION_ERROR_CUSTOM_LABEL_INVALID | Custom Label is invalid |
CAT_VALIDATION_ERROR_REQUIRED_INPUT_PARAMETER_MALFORMED | Required input parameter is malformed |
CAT_VALIDATION_ERROR_REQUIRED_INPUT_PARAMETER_TOO_SMALL | Required input parameter is too small |
CAT_VALIDATION_ERROR_PRODUCT_PRICE_INVALID | Price is invalid/malformed |
CAT_VALIDATION_ERROR_SALE_PRICE_INVALID | Sale Price is invalid/malformed |
CAT_VALIDATION_EXPIRATION_DATE_INVALID | Expiration Date is invalid/malformed |
CAT_VALIDATION_ERROR_INVALID_GOOGLE_PRODUCT_CATEGORY | Google product category is invalid/malformed |
CAT_VALIDATION_ERROR_AVAILABILITY_RADIUS_INVALID | Availability Radius is invalid/malformed |
CAT_VALIDATION_ERROR_GEOGRAPHIC_COORDINATES_INVALID | Geographic Coordinates are invalid/malformed |
CAT_VALIDATION_ERROR_AVAILABILITY_RADIUS_AND_GEOGRAPHIC_COORDINATE_MISSING | Availability Radius and geographic coordinates are both required |
CAT_FX_RATE_NOT_SUPPORTED | The provided currency is currently not supported in our Fx Service |
CAT_SALE_PRICE_EQUAL_OR_GREATER_THAN_PRICE | Sale price is greater than or equal to the regular price |
CAT_VALIDATION_ERROR_AGE_GROUP_INVALID | Age Group is invalid |
CAT_VALIDATION_ERROR_CURRENCY_INVALID | Currency Code is invalid/malformed |
CAT_VALIDATION_ERROR_DESCRIPTION_INVALID | Description is invalid |
CAT_VALIDATION_ERROR_TITLE_INVALID | Title is invalid. |
CAT_VALIDATION_ERROR_PRODUCT_ID_INVALID | Product ‘ID’ is invalid |
CAT_FEED_FILE_NO_DATA | File containing feed is empty or cannot be fully parsed |
Get all Feed Uploads
curl
"https://adsapi.snapchat.com/v1/product_feeds/c03a1fd9-97f2-4f87-a1c2-7696a8d6bde8/feed_uploads" \
-H "Authorization: Bearer meowmeowmeow"
The above request returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f7e5a1b00ff0d38ed96d3af7c0001737e616473617069736300016275696c642d31663731616139352d312d3339312d3100010105",
"feed_uploads": [
{
"sub_request_status": "SUCCESS",
"feed_upload": {
"created_at": "2020-10-08T00:15:06.631226Z",
"updated_at": "2020-10-08T00:15:06.631226Z",
"id": "f5e58ff4-1014-401a-baeb-5866e515deb0",
"feed_id": "c03a1fd9-97f2-4f87-a1c2-7696a8d6bde8",
"summary": {
"issues_summary": {}
},
"url": "https://www.example.com/productfeed/timber_product_feed.csv",
"update_type": "REPLACE",
"status": "INITIALIZED"
}
},
{
"sub_request_status": "SUCCESS",
"feed_upload": {
"created_at": "2020-10-07T23:15:00.702Z",
"updated_at": "2020-10-07T23:15:35.624449Z",
"id": "0aea4326-80cf-49de-9555-6d7c01566d9d",
"feed_id": "c03a1fd9-97f2-4f87-a1c2-7696a8d6bde8",
"summary": {
"total_items": 16,
"items_modified": 16,
"issues_summary": {
"recommendations": {
"CAT_RECOMMENDATION_MISSING_APP_INSTALL_PROPERTIES": 5,
"CAT_RECOMMENDATION_MISSING_DEEP_LINK_PROPERTIES": 5
}
}
},
"url": "https://www.example.com/productfeed/timber_product_feed.csv",
"update_type": "REPLACE",
"status": "COMPLETE"
}
},
{
"sub_request_status": "SUCCESS",
"feed_upload": {
"created_at": "2020-10-07T22:15:01.366260Z",
"updated_at": "2020-10-07T22:15:32.186709Z",
"id": "6d3e1ecd-362a-4386-b2b7-71b199d20c5b",
"feed_id": "c03a1fd9-97f2-4f87-a1c2-7696a8d6bde8",
"summary": {
"total_items": 7,
"items_modified": 7,
"issues_summary": {
"recommendations": {
"CAT_RECOMMENDATION_MISSING_APP_INSTALL_PROPERTIES": 7,
"CAT_RECOMMENDATION_MISSING_DEEP_LINK_PROPERTIES": 7
}
}
},
"url": "https://www.example.com/productfeed/timber_product_feed.csv",
"update_type": "REPLACE",
"status": "COMPLETE"
}
}
]
}
This request lists the 200 latest Feed Uploads for the Product feed in order of creation.
HTTP Request
GET https://adsapi.snapchat.com/v1/product_feeds/{product_feed_id}/feed_uploads
Parameters
Parameter | Default | Description |
---|---|---|
product_feed_id | Feed ID |
Create a Feed Upload
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"product_feeds":[{"catalog_id":"7ae3e924-dc70-48f6-9733-4d009d4f2152","name":"The No Schedule Feed","default_currency":"EUR","status":"ACTIVE"}]}' \
"https://adsapi.snapchat.com/v1/catalogs/7ae3e924-dc70-48f6-9733-4d009d4f2152/product_feeds"
The above request creates a Product Feed without the scheduling attribute:
{
"request_status": "SUCCESS",
"request_id": "5f7e532800ff070665a0c9d0a00001737e616473617069736300016275696c642d31663731616139352d312d3339312d310001010b",
"product_feeds": [
{
"sub_request_status": "SUCCESS",
"product_feed": {
"created_at": "2020-10-07T23:45:44.925724Z",
"updated_at": "2020-10-07T23:45:44.925724Z",
"id": "c79a127a-3ff2-4278-ae5a-f3f35f4093ae",
"catalog_id": "7ae3e924-dc70-48f6-9733-4d009d4f2152",
"name": "The No Schedule Feed",
"default_currency": "EUR"
}
}
]
}
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"feed_uploads":[{"url":"ftp://93.184.216.34/timber_product_feed.csv","username":"H0neyBadger","password":"BeezAreCool99","update_type":"REPLACE"}]}' \
"https://adsapi.snapchat.com/v1/product_feeds/c79a127a-3ff2-4278-ae5a-f3f35f4093ae/feed_uploads"
The above request creates a one time upload of the designated file to the Product feed, the update_type REPLACE value stipulates all products in the current feed will be replaced by the products in the new file.:
{
"request_status": "SUCCESS",
"request_id": "5f7db87900ff0627f67519a13a0001737e616473617069736300016275696c642d31663731616139352d312d3339312d3100010121",
"feed_uploads": [
{
"sub_request_status": "SUCCESS",
"feed_upload": {
"created_at": "2020-10-07T12:45:45.884998Z",
"updated_at": "2020-10-07T12:45:45.884998Z",
"id": "2c2a503a-01cf-4695-986b-b8281e7136e2",
"feed_id": "c79a127a-3ff2-4278-ae5a-f3f35f4093ae",
"summary": {
"issues_summary": {}
},
"url": "ftp://93.184.216.34/timber_product_feed.csv",
"update_type": "REPLACE",
"status": "INITIALIZED"
}
}
]
}
The Create Feed upload request is used to create a one off Feed Upload for a Product Feed where the schedule attribute has not been defined.
- Create a Product Feed without the schedule attribute.
- Create a Feed Upload specifying url and update_type, if the url is password protected username and password are required.
Body
Attribute | Description | Required | Possible Values |
---|---|---|---|
url | The FTP/SFTP/HTTP/HTTPS URL including file name where the product feed is to be fetched from | R | |
update_type | Indicates the type of update, REPLACE means existing product feed will be replaced by the new file, UPSERT means products in the uploaded file will be updated or added to the product feed, any products already in the product feed but missing in the file will be preserved | R | REPLACE, UPSERT |
username | The username to access the product feed | O/Required if url is password protected | |
password | The password to access the product feed | O/Required if url is password protected |
HTTP Request
POST https://adsapi.snapchat.com/v1/product_feeds/{product_feed_id}/feed_uploads
Parameters
Parameter | Default | Description |
---|---|---|
product_feed_id | Feed ID |
Get a Feed Upload
curl
"https://adsapi.snapchat.com/v1/feed_uploads/ea7534f3-5576-4698-b48c-5a955aca0747" \
-H "Authorization: Bearer meowmeowmeow"
The above request returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f7d150400ff0b8aba6ba67c710001737e616473617069736300016275696c642d31663731616139352d312d3339312d3100010121",
"feed_uploads": [
{
"sub_request_status": "SUCCESS",
"feed_upload": {
"created_at": "2020-10-06T04:00:06.146753Z",
"updated_at": "2020-10-06T04:03:06.001196Z",
"id": "ea7534f3-5576-4698-b48c-5a955aca0747",
"feed_id": "72cffebf-b91b-4af7-a8b9-d2a91e51b456",
"summary": {
"total_items": 7,
"items_modified": 7,
"issues_summary": {
"recommendations": {
"CAT_RECOMMENDATION_MISSING_APP_INSTALL_PROPERTIES": 7,
"CAT_RECOMMENDATION_MISSING_DEEP_LINK_PROPERTIES": 7
}
}
},
"url": "ftp://93.184.216.34/timber_product_feed.csv",
"update_type": "REPLACE",
"status": "COMPLETE"
}
}
]
}
This request fetches a specific Feed upload, this contains a summary of any recommendations or feedback for the latest executed upload.
HTTP Request
GET https://adsapi.snapchat.com/v1/product_feeds/{product_feed_id}/feed_uploads
Parameters
Parameter | Default | Description |
---|---|---|
product_feed_id | Feed ID |
Catalog Diagnostics
curl -X POST \
-d '{"facets": [{"property": "BRAND"}], "filter": {"AVAILABILITY": {"EQ": "IN_STOCK"}}}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/catalogs/f1180af0-949b-4439-8f62-021ac96cfcff
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ed4fe0a00ff00ff18b512bc3ae30001737e616473617069736300016275696c642d36653163373061642d312d3335352d3000010154",
"summary": {
"total_products": {
"count": "100",
"relation": "EQ"
}
},
"facets": [
{
"facet": {
"property": "BRAND"
},
"values": [
{
"name": "Farmani",
"count": "89"
},
{
"name": "Rolo Ralph",
"count": "10"
},
{
"name": "Thomas Hillgren",
"count": "1"
}
]
}
]
}
Catalog diagnostics allows you to group existing items given the properties you define, either for an entire Catalog, or for a single Product Set.
The facets
body allows you to specify a property to group items by. You can also use a single AND/OR operator to select up to ten additional item properties, this is defined within the filter
part the request, you can filter by up to ten item properties using AND/OR.
If you want to keep the grouping to a single Product Set you can do so by using the product_set_id
within the filter
part of the request.
HTTP Request
POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/facets?limit=100
Parameters
Parameter | Required | Description |
---|---|---|
catalog_id | R | Catalog ID |
limit | O | Integer, min 1, max 50, the number of groupings returned |
Attributes
These attributes can be used within the facets
part of
Attribute | Description | Required | Possible values |
---|---|---|---|
property | The property you want to group products by | R | AGE_GROUP, AVAILABILITY, BASE_PRICE_CURRENCY, BRAND, COLOR, CONDITION, CUSTOM_LABEL_0, CUSTOM_LABEL_1, CUSTOM_LABEL_2, CUSTOM_LABEL_3, CUSTOM_LABEL_4, GENDER, GOOGLE_PRODUCT_CATEGORY, ITEM_GROUP_ID, MATERIAL, PATTERN, PRICE_CURRENCY, PRODUCT_TYPE, SIZEEL_3, CUSTOM_LABEL_4, GOOGLE_PRODUCT_CATEGORY, ITEM_GROUP_ID, MATERIAL, PATTERN, SALE_PRICE_CURRENCY, SIZE, AGE_GROUP, AVAILABILITY, COLOR, CONDITION, GENDER, PRICE_CURRENCY, LOYALTY_PROGRAM, ACTIVITY, LOCALITY, POSTAL_CODE, COUNTRY_CODE, ORIGIN_AIRPORT, DESTINATION_AIRPORT, ORIGIN_CITY, DESTINATION_CITY |
filter | Optional filtering, can use one logical operator (AND, OR) | O | PRODUCT_SET_ID, AGE_GROUP, AVAILABILITY, BRAND, COLOR, CONDITION, CUSTOM_LABEL_0, CUSTOM_LABEL_1, CUSTOM_LABEL_2, CUSTOM_LABEL_3, CUSTOM_LABEL_4, GENDER, GOOGLE_PRODUCT_CATEGORY, ITEM_GROUP_ID, MATERIAL, PATTERN, PRICE_CURRENCY, PRODUCT_TYPE, SIZE, BASE_PRICE_AMOUNT, SALE_PRICE_AMOUNT, NEIGHBORHOOD, STAR_RATING, LOYALTY_PROGRAM, ACTIVITY, LOCALITY, POSTAL_CODE, COUNTRY_CODE, NUMBER_OF_RATERS, GUEST_RATING_SCORE, ORIGIN_AIRPORT, DESTINATION_AIRPORT, ORIGIN_CITY, DESTINATION_CITY |
Filter Operator
Operator | Description | Can be used with |
---|---|---|
EQ | Equal to | Integer, Float, String |
NEQ | Not Equal to | Integer, Float, String |
GT | Greater than | Integer, Float |
GTE | Greater than or equal to | Integer, Float |
LT | Less than | Integer, Float |
LTE | Less than or equal to | Integer, Float |
CONTAINS | Contains | String |
NOT_CONTAINS | Does not contain | String |
I_CONTAINS | Contains - Case insensitive | String |
I_NOT_CONTAINS | Does not contain - Case insensitive | String |
STARTS_WITH | Starts with | String |
I_STARTS_WITH | Starts with - Case insensitive | String |
IS_ANY | Is any of the list. Only works with strings containing alphanumeric characters | List of Strings |
IS_NOT_ANY | Is not any of the list. Only works with strings containing alphanumeric characters | List of Strings |
I_IS_ANY | Is any of the list - Case insensitive. Only works with strings containing alphanumeric characters | List of Strings |
I_IS_NOT_ANY | Is not any of the list - Case insensitive. Only works with strings containing alphanumeric characters | List of Strings |
Example 1 - Diagnostics
Diagnostics for a single Product Set using product_set_id
curl -X POST \
-d '{"facets": [{"property": "BRAND"}], "filter": {"PRODUCT_SET_ID": {"EQ": "99246572-4c2b-4e66-935c-1b1ee1ea2360"}}}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/catalogs/8318ff5c-78f7-47db-8a32-675f0b787c75/facets?limit=50
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ed517ff0000ff0a11b020203f100001737e616473617069736300016275696c642d36653163373061642d312d3335352d300001014f",
"summary": {
"total_products": {
"count": "33",
"relation": "EQ"
}
},
"facets": [
{
"facet": {
"property": "BRAND"
},
"values": [
{
"name": "Rolo Ralph",
"count": "33"
}
]
}
]
}
Example 2 - Diagnostics
Diagnostics using several AND operators (gender, availablity, size)
curl -X POST \
-d '{"facets": [{"property": "BRAND"}], "filter": {"AND": [{"GENDER": {"EQ": "UNISEX"}},{"AVAILABILITY": {"EQ": "IN_STOCK"}},{"SIZE": {"EQ": "M"}}]}}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/catalogs/8318ff5c-78f7-47db-8a32-675f0b787c75/facets?limit=50
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ed5252800ff0e424ba54e30da0001737e616473617069736300016275696c642d36653163373061642d312d3335352d3000010115",
"summary": {
"total_products": {
"count": "11",
"relation": "EQ"
}
},
"facets": [
{
"facet": {
"property": "BRAND"
},
"values": [
{
"name": "Rolo Ralph",
"count": "11"
}
]
}
]
}
Example 3 - Diagnostics
Diagnostics using several AND operators (product_set_id, gender, availablity, size)
curl -X POST \
-d '{"facets": [{"property": "BRAND"}], "filter": {"AND": [{"PRODUCT_SET_ID": {"EQ":"99246572-4c2b-4e66-935c-1b1ee1ea2360"}},{"GENDER": {"EQ": "UNISEX"}},{"AVAILABILITY": {"EQ": "IN_STOCK"}},{"SIZE": {"EQ": "M"}}]}}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/catalogs/8318ff5c-78f7-47db-8a32-675f0b787c75/facets?limit=50
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ed5252800ff0e424ba54e30da0001737e616473617069736300016275696c642d36653163373061642d312d3335352d3000010115",
"summary": {
"total_products": {
"count": "11",
"relation": "EQ"
}
},
"facets": [
{
"facet": {
"property": "BRAND"
},
"values": [
{
"name": "Rolo Ralph",
"count": "11"
}
]
}
]
}
Product Search
The product search is used to search a catalog for products given a provided filter, each level of the filter can only have one operator and we allow up to two levels of nesting, for each operator we can have up to 10 fields
HTTP Request
POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/products/search
Request Parameters
Parameter | Required | Description |
---|---|---|
catalog_id | R | Catalog ID |
Body Parameters
Parameter | Required | Description |
---|---|---|
limit | O | this pagination variable specifies the number of products per page 50 - 1000 |
Filter properties
Property | Possible values |
---|---|
AGE_GROUP | NEWBORN, INFANT, TODDLER, KIDS, ADULT |
AVAILABILITY | IN_STOCK, OUT_OF_STOCK, PREORDER, DISCONTINUED, AVAILABLE_FOR_ORDER |
BRAND | |
COLOR | |
CONDITION | NEW, REFURBISHED, USED |
CUSTOM_LABEL_0 | |
CUSTOM_LABEL_1 | |
CUSTOM_LABEL_2 | |
CUSTOM_LABEL_3 | |
CUSTOM_LABEL_4 | |
GENDER | FEMALE, MALE, UNISEX |
GOOGLE_PRODUCT_CATEGORY | |
ID | |
ITEM_GROUP_ID | |
MATERIAL | |
PATTERN | |
PRICE_AMOUNT | |
PRICE_CURRENCY | |
PRODUCT_TYPE | |
SIZE | |
TITLE | |
PRODUCT_SET_ID | |
PRODUCT_STATUS | COMPLETE, FAILED_MEDIA |
ELIGIBLE_AD_TYPE | APP_INSTALL, REMOTE_WEBPAGE, DEEPLINK_ATTACHMENT |
Filter Operator
Operator | Description | Can be used with |
---|---|---|
EQ | Equal to | Integer, Float, String |
NEQ | Not Equal to | Integer, Float, String |
GT | Greater than | Integer, Float |
GTE | Greater than or equal to | Integer, Float |
LT | Less than | Integer, Float |
LTE | Less than or equal to | Integer, Float |
CONTAINS | Contains | String |
NOT_CONTAINS | Does not contain | String |
I_CONTAINS | Contains - Case insensitive | String |
I_NOT_CONTAINS | Does not contain - Case insensitive | String |
STARTS_WITH | Starts with | String |
I_STARTS_WITH | Starts with - Case insensitive | String |
IS_ANY | Is any of the list. Only works with strings containing alphanumeric characters | List of Strings |
IS_NOT_ANY | Is not any of the list. Only works with strings containing alphanumeric characters | List of Strings |
I_IS_ANY | Is any of the list - Case insensitive. Only works with strings containing alphanumeric characters | List of Strings |
I_IS_NOT_ANY | Is not any of the list - Case insensitive. Only works with strings containing alphanumeric characters | List of Strings |
Example 1 - Product Search
Request the entire Product Catalog using a pagination of 50 products, setting "limit":50
attribute achieves this.
curl -X POST \
-d '{"limit": 50}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/products/search
The above command returns JSON structured like this (this response has been shortened):
{
"request_status": "SUCCESS",
"request_id": "5f19a01000ff00fff430ee807f720001737e616473617069736300016275696c642d63616265303361622d312d3336392d3000010108",
"summary": {
"total_products": {
"count": "209",
"relation": "EQ"
}
},
"paging": {
"next_link": "https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/products/search?cursor=IlNDLTE1MCI=&limit=50",
"next_link_body": "H4sIAAAAAAAAAONiAAB1-ja7AgAAAA=="
},
"products": [
{
"sub_request_status": "SUCCESS",
"product": {
"id": "9156245200715568072",
"external_id": "SC-101",
"catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
"title": "Denim Shirt - Women's",
"description": "Women's denim shirt - crafted from the finest squirrel made denim.",
"link": "https://www.example.com/ch/en/jj/denim/denim-jackets/jean-cj-195-denim-jacket-12169148.html?cgid=jj-outerwear-denim&dwvar_colorPattern=12169148_BlueDenim",
"image_link": "https://www.example.com/dw/image/v2/ABBT_PRD/on/demandware.static/-/Sites-bd-catalog/default/dw7809338c/pim-static/large/12169148_BlueDenim_003_ProductLarge.jpg?sw=685",
"availability": "in stock",
"google_product_category": "Apparel & Accessories > Clothing > Shirts & Tops",
"product_type": "Women's > Tops > Denim",
"brand": "Honeybear Denim Jackets",
"gtin": "912345678905",
"mpn": "912345678905",
"condition": "new",
"age_group": "adult",
"color": "blue",
"gender": "female",
"size": "L",
"item_group_id": "SC-1",
"custom_label_0": "Bestseller",
"price": {
"value": "24.99",
"currency": "USD"
},
"sale_price": {
"value": "22.99",
"currency": "USD"
},
"created_at": "2020-07-23T14:34:56.532179Z",
"updated_at": "2020-07-23T14:34:56.532202Z",
"additional_media": [
{
"url": "https://example.com/images/womensdenimshirt/altimage.jpeg"
}
]
}
},
...
{
"sub_request_status": "SUCCESS",
"product": {
"id": "9151706793146519301",
"external_id": "SC-150",
"catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
"title": "Denim trousers",
"description": "Blue jeans for men",
"link": "https://www.example.com.com/loose-fit-jeans-1999.html?cgid=jj-nl-some-37&dwvar_colorPattern=12179324_BlueDenim",
"image_link": "https://www.example.com/static/large/11239324_BlueDenim_003_ProductLarge.jpg",
"availability": "in stock",
"product_type": "Unisex > Trousers",
"brand": "Honeybear Denim",
"gtin": "912345678905",
"mpn": "912345678905",
"condition": "new",
"age_group": "adult",
"color": "blue",
"gender": "unisex",
"size": "M",
"item_group_id": "SC-5",
"custom_label_0": "Bestseller",
"price": {
"value": "14.99",
"currency": "USD"
},
"created_at": "2020-07-23T14:34:56.536774Z",
"updated_at": "2020-07-23T14:34:56.536779Z"
}
}
]
}
Example 2 - Product Search
Request all products within a specific Product Set.
curl -X POST \
-d '{"limit": 50,"filter": {"PRODUCT_SET_ID": {"EQ": "dcaa2832-48bd-4df6-8ba5-0edac83971c2"}}}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/products/search
The above command returns JSON structured like this (this response has been shortened):
{
"request_status": "SUCCESS",
"request_id": "5f19a9fc00ff0356de38dde9990001737e616473617069736300016275696c642d63616265303361622d312d3336392d3000010131",
"summary": {
"total_products": {
"count": "20",
"relation": "EQ"
}
},
"products": [
{
"sub_request_status": "SUCCESS",
"product": {
"id": "998335299479914169",
"external_id": "SC-106",
"catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
"title": "Beanie hat",
"description": "Honeybear knitted beanie hat",
"link": "https://www.example.com/accessories/beanies/ackman-short-knit-beanie-beanie-12164650.html?cgid=jj-accessories-beanies&dwvar_colorPattern=12164650_WinterMoss",
"image_link": "https://www.example.com/image/e/12164650_ProductLarge.jpg",
"availability": "in stock",
"product_type": "Unisex > Headwear",
"brand": "Honeybear Headwear",
"gtin": "912345678905",
"mpn": "912345678905",
"condition": "new",
"age_group": "adult",
"color": "red",
"gender": "unisex",
"size": "M",
"item_group_id": "SC-6",
"custom_label_0": "Bestseller",
"price": {
"value": "14.99",
"currency": "USD"
},
"created_at": "2020-07-23T15:17:16.594913Z",
"updated_at": "2020-07-23T15:17:16.594933Z"
}
},
...
{
"sub_request_status": "SUCCESS",
"product": {
"id": "9435790241890490957",
"external_id": "SC-209",
"catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
"title": "Cap",
"description": "Cap with Kevin",
"link": "https://www.example.com/accessories/caps/billy-baseball-cap.html?ar_colorPattern=121_Black",
"image_link": "https://www.example.com/image/9964499_Black_001_ProductLarge.jpg",
"availability": "in stock",
"product_type": "Unisex > Headwear",
"brand": "Honeybear Caps",
"gtin": "912345778905",
"mpn": "912345778905",
"condition": "new",
"age_group": "adult",
"color": "green",
"gender": "unisex",
"size": "M",
"item_group_id": "SC-10",
"custom_label_0": "Bestseller",
"price": {
"value": "4.99",
"currency": "USD"
},
"created_at": "2020-07-23T15:17:16.597499Z",
"updated_at": "2020-07-23T15:17:16.597501Z"
}
}
]
}
Example 3 - Product Search
Request all products in a feed where the media failed due to being unavailable.
curl -X POST \
-d '{"limit": 50,"filter":{"PRODUCT_STATUS": {"EQ": "FAILED_MEDIA"}}}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/products/search
The above command returns JSON structured like this (this response has been shortened):
{
"request_status": "SUCCESS",
"request_id": "5f1af77c00ff075e0536d7780d0001737e616473617069736300016275696c642d32363038643739372d312d3337302d3000010145",
"summary": {
"total_products": {
"count": "12",
"relation": "EQ"
}
},
"products": [
{
"sub_request_status": "SUCCESS",
"product": {
"id": "9877985877291710328",
"external_id": "W999-HOT-M",
"catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
"title": "Honeybear Bikini",
"description": "A bikini made out of the finest fox crafted fabric.",
"link": "https://www.example.com/products/womens-bikini-red.jpg",
"image_link": "https://example.com/external/images/5a54e8920edac/94d9b4004d87f46722801c503514585a.jpg",
"availability": "out of stock",
"product_type": "Swimwear",
"brand": "Honeybear Swimwear",
"condition": "new",
"age_group": "adult",
"color": "red",
"gender": "female",
"item_group_id": "123",
"custom_label_0": "Women's Bikini",
"custom_label_2": "Subscription Available",
"custom_label_4": "additional_images",
"price": {
"value": "18.00",
"currency": "USD"
},
"created_at": "2020-07-24T15:00:12.854449Z",
"updated_at": "2020-07-24T15:00:12.854470Z",
"feed_id": "852733e2-6838-4c61-9d23-7e5fddaca3f8",
"main_media": {
"url": "https://example.com/external/images/5a54e8920edac/94d9b4004d87f46722801c503514585a.jpg",
"internal_url_status": "FAILURE",
"internal_url_error_code": "NOT_FOUND"
},
"icon_media": {}
}
},
...
{
"sub_request_status": "SUCCESS",
"product": {
"id": "9940768843314259508",
"external_id": "W9990-HTH-XXXL/XXXXL",
"catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
"title": "Women's Robe",
"description": "This robe is the perfect addition to your wardrobe.",
"link": "https://www.example.com/products/womens-robe.jpg",
"image_link": "https://example.com/external/images/5a54e8920edac/b90a21dfe0c3da11d7b37232f599a5db.jpg",
"availability": "in stock",
"google_product_category": "Apparel & Accessories > Clothing > Sleepwear & Loungewear > Loungewear",
"product_type": "Robes",
"brand": "Honeybear Homewear",
"condition": "new",
"age_group": "adult",
"color": "green",
"gender": "female",
"item_group_id": "368",
"custom_label_0": "Women's Robe",
"custom_label_2": "Subscription Not Available",
"custom_label_4": "additional_images",
"price": {
"value": "88.00",
"currency": "USD"
},
"created_at": "2020-07-24T15:00:12.856278Z",
"updated_at": "2020-07-24T15:00:12.856287Z",
"feed_id": "852733e2-6838-4c61-9d23-7e5fddaca3f8",
"main_media": {
"url": "https://example.com/external/images/5a54e8920edac/b90a21dfe0c3da11d7b37232f599a5db.jpg",
"internal_url_status": "FAILURE",
"internal_url_error_code": "NOT_FOUND"
},
"icon_media": {}
}
}
]
}
Example 4 - Product Search
Request all products within a specific Product Set, where the title attribute contains the term ‘jacket’ or ‘hat’, and where the availability is in stock and the product status is complete.
curl -X POST \
-d '{"filter": {"AND": [{"OR": [{"TITLE": {"I_CONTAINS": "jacket"}},{"TITLE": {"I_CONTAINS": "hat"}}]},{"PRODUCT_STATUS": {"EQ": "COMPLETE"}},{"AVAILABILITY": {"EQ": "IN_STOCK" }},{"PRODUCT_SET_ID": {"EQ": "99246572-4c2b-4e66-935c-1b1ee1ea2360"}}]}}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/products/search
The above command returns JSON structured like this (this response has been shortened):
{
"request_status": "SUCCESS",
"request_id": "5f1ad42e00ff09810a9af6828c0001737e616473617069736300016275696c642d32363038643739372d312d3337302d300001015d",
"summary": {
"total_products": {
"count": "11",
"relation": "EQ"
}
},
"products": [
{
"sub_request_status": "SUCCESS",
"product": {
"id": "9767298711984673596",
"external_id": "SC-103",
"catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
"title": "Denim Jacket",
"description": "Oversized denim jacket",
"link": "https://www.example.com/index.php?jj-outerwear-denim&dwvar_colorPattern=12166869_BlueDenim",
"image_link": "https://www.example.com/dw/image/large/12166811_BlueDenim_008_ProductLarge.jpg?sw=685",
"availability": "in stock",
"product_type": "Men's > Jackets > Denim",
"brand": "Badger Denim",
"gtin": "912345678905",
"mpn": "912345678905",
"condition": "new",
"age_group": "adult",
"color": "green",
"gender": "unisex",
"size": "M",
"item_group_id": "SC-3",
"custom_label_0": "Bestseller",
"price": {
"value": "14.99",
"currency": "USD"
},
"created_at": "2020-07-24T12:29:35.036864Z",
"updated_at": "2020-07-24T12:29:35.036901Z"
}
},
...
{
"sub_request_status": "SUCCESS",
"product": {
"id": "9285992718921035814",
"external_id": "SC-193",
"catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
"title": "Denim Jacket",
"description": "Skinny fit denim jacket",
"link": "https://www.example.com/index.php?bd-outerwear-denim&dwvar_colorPattern=12166869_BlueDenim",
"image_link": "https://www.example.com/dw/image/large/12166869_BlueDenim_003_ProductLarge.jpg?sw=685",
"availability": "in stock",
"product_type": "Men's > Jackets > Denim",
"brand": "Honeybear Denim",
"gtin": "912345678905",
"mpn": "912345678905",
"condition": "new",
"age_group": "adult",
"color": "light blue",
"gender": "unisex",
"size": "M",
"item_group_id": "SC-3",
"custom_label_0": "Bestseller",
"price": {
"value": "24.99",
"currency": "USD"
},
"created_at": "2020-07-24T12:29:35.039136Z",
"updated_at": "2020-07-24T12:29:35.039142Z"
}
}
]
}
Hotel Search
The hotel search is used to search a catalog for hotels given a provided filter, each level of the filter can only have one operator and we allow up to two levels of nesting, for each operator we can have up to 10 fields
HTTP Request
POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/hotels/search
Request Parameters
Parameter | Required | Description |
---|---|---|
catalog_id | R | Catalog ID |
Body Parameters
Parameter | Required | Description |
---|---|---|
limit | O | this pagination variable specifies the number of products per page 50 - 1000 |
Filter properties
Property | Possible values |
---|---|
ID | |
NAME | |
BASE_PRICE_AMOUNT | |
BASE_PRICE_CURRENCY | |
SALE_PRICE_AMOUNT | |
SALE_PRICE_CURRENCY | |
BRAND | |
NEIGHBORHOOD | |
STAR_RATING | |
LOYALTY_PROGRAM | |
ACTIVITY | ACTIVE, INACTIVE |
CUSTOM_LABEL_0 | |
CUSTOM_LABEL_1 | |
CUSTOM_LABEL_2 | |
CUSTOM_LABEL_3 | |
CUSTOM_LABEL_4 | |
LOCALITY | |
POSTAL_CODE | |
COUNTRY_CODE | |
NUMBER_OF_RATERS | |
GUEST_RATING_SCORE | |
PRODUCT_SET_ID | |
PRODUCT_STATUS | COMPLETE, FAILED_MEDIA |
ELIGIBLE_AD_TYPE | APP_INSTALL, REMOTE_WEBPAGE, DEEPLINK_ATTACHMENT |
Filter Operator
Operator | Description | Can be used with |
---|---|---|
EQ | Equal to | Integer, Float, String |
NEQ | Not Equal to | Integer, Float, String |
GT | Greater than | Integer, Float |
GTE | Greater than or equal to | Integer, Float |
LT | Less than | Integer, Float |
LTE | Less than or equal to | Integer, Float |
CONTAINS | Contains | String |
NOT_CONTAINS | Does not contain | String |
I_CONTAINS | Contains - Case insensitive | String |
I_NOT_CONTAINS | Does not contain - Case insensitive | String |
STARTS_WITH | Starts with | String |
I_STARTS_WITH | Starts with - Case insensitive | String |
IS_ANY | Is any of the list. Only works with strings containing alphanumeric characters | List of Strings |
IS_NOT_ANY | Is not any of the list. Only works with strings containing alphanumeric characters | List of Strings |
I_IS_ANY | Is any of the list - Case insensitive. Only works with strings containing alphanumeric characters | List of Strings |
I_IS_NOT_ANY | Is not any of the list - Case insensitive. Only works with strings containing alphanumeric characters | List of Strings |
Example 1 - Hotel Search
Request the entire Hotel Catalog using a pagination of 50 products, setting "limit":50
attribute achieves this.
curl -X POST \
-d '{"limit": 50}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/hotels/search
The above command returns JSON structured like this (this response has been shortened):
{
"request_status": "SUCCESS",
"request_id": "5f19a01000ff00fff430ee807f720001737e616473617069736300016275696c642d63616265303361622d312d3336392d3000010108",
"summary": {
"total_products": {
"count": "209",
"relation": "EQ"
}
},
"paging": {
"next_link": "https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/hotels/search?cursor=IlNDLTE1MCI=&limit=50",
"next_link_body": "H4sIAAAAAAAAAONiAAB1-ja7AgAAAA=="
},
"products": [
{
"sub_request_status": "SUCCESS",
"product": {
"id": "9156245200715568072",
"external_id": "SC-101",
"created_at": "2020-07-23T14:34:56.532179Z",
"updated_at": "2020-07-23T14:34:56.532202Z",
"catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
"name": "Snapchat Hotel",
"description": "Located in sunny Santa Monica",
"link": "https://www.example.com/hotel",
"mobile_link": "https://www.m.example.com/hotel",
"main_media": {
"url": "https://storage.example.com/hotels-assets/image1926.jpg",
"tags": [
"Swimming pool",
"Gym"
]
},
"additional_media": [
{
"url": "https://storage.example.com/hotels-assets/image19262.jpg",
"tags": [
"Lobby view",
"Overview"
]
}
],
"address": {
"line": "1600 Pennsylvania Avenue",
"line2": "Unit 1",
"locality": "Los Angeles",
"postal_code": "90210",
"region": "California",
"country_code": "US"
},
"price": {
"value": "199",
"currency": "USD"
},
"sale_price": {
"value": "299",
"currency": "USD"
},
"neighborhoods": [
"uptown",
"downtown"
],
"geographic_coordinates": {
"longitude": 2.294464,
"latitude": 48.858353
},
"guest_ratings": {
"rating_system": "tripAdvisor",
"score": "7.8",
"max_score": "10",
"number_of_reviewers": "300"
},
"star_rating": "3.5",
"ios_app_link": {
"url": "myapp://a/random/path",
"app_store_id": "427916203",
"app_name": "Snapchat Hotel App"
},
"android_app_link": {
"url": "https://snapchathoteldeeplink.com",
"package": "com.snap.hotel",
"app_name": "Snapchat Hotel App"
},
"loyalty_program": "Premium program",
"custom_labels": {},
"activity": "ACTIVE",
}
},
...
{
"sub_request_status": "SUCCESS",
"product": {
"id": "9156245200715568072",
"external_id": "SC-101",
"created_at": "2020-07-23T14:34:56.532179Z",
"updated_at": "2020-07-23T14:34:56.532202Z",
"catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
"name": "Fantastic Hotel",
"description": "This hotel features a restaurant, an outdoor pool, and a front-desk safe.",
"link": "https://www.example.com/hotel",
"brand": "Independent",
"main_media": {
"url": "https://storage.example.com/hotels-assets/image1.jpg",
"tags": ["Lobby View"]
},
"address": {
"line1": "342 Snap Avenue",
"line2": "Unit 505",
"locality": "Las Vegas",
"region": "Nevada",
"postal_code": "90210",
"country": "US"
},
"price": {
"value": "499",
"currency": "USD"
},
"sale_price": {
"value": "599",
"currency": "USD"
},
"neighborhoods": [
"eastside",
],
"geographic_coordinates": {
"longitude": 24.294464,
"latitude": -48.858353
},
"guest_ratings": {
"rating_system": "tripAdvisor",
"score": "7.8",
"max_score": "10",
"number_of_reviewers": "300"
},
"star_rating": "2.5",
"ios_app_link": {
"url": "myapp://a/random/path",
"app_store_id": "427916203",
"app_name": "Snapchat Hotel App"
},
"android_app_link": {
"url": "https://snapchathoteldeeplink.com",
"package": "com.snap.hotel",
"app_name": "Snapchat Hotel App"
},
"loyalty_program": "Loyalty Diamond Program",
"custom_labels": {},
"activity": "ACTIVE",
}
},
]
}
Example 2 - Hotel Search
Request all hotels within a specific Product Set, where the name attribute contains the term ‘Snap’ or ‘elmwood’, and the star rating is greater or equal than 3.5.
curl -X POST \
-d '{"filter": {"AND":[{"OR":[{"NAME": {"I_CONTAINS": "Snap"}},{"NAME": {"I_CONTAINS": "elmwood"}}]},{"STAR_RATING": {"GTE": "3.5"}}]}}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/hotels/search
The above command returns JSON structured like this (this response has been shortened):
{
"request_status": "SUCCESS",
"request_id": "5f19a01000ff00fff430ee807f720001737e616473617069736300016275696c642d63616265303361622d312d3336392d3000010108",
"summary": {
"total_hotels": {
"count": "1",
"relation": "EQ"
}
},
"hotels": [
{
"sub_request_status": "SUCCESS",
"product": {
"id": "9156245200715568072",
"external_id": "SC-101",
"created_at": "2020-07-23T14:34:56.532179Z",
"updated_at": "2020-07-23T14:34:56.532202Z",
"catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
"name": "Snapchat Hotel",
"description": "Located in sunny Santa Monica",
"link": "https://www.example.com/hotel",
"mobile_link": "https://www.m.example.com/hotel",
"main_media": {
"url": "https://storage.example.com/hotels-assets/image1926.jpg",
"tags": [
"Swimming pool",
"Gym"
]
},
"additional_media": [
{
"url": "https://storage.example.com/hotels-assets/image19262.jpg",
"tags": [
"Lobby view",
"Overview"
]
}
],
"address": {
"line": "1600 Pennsylvania Avenue",
"line2": "Unit 1",
"locality": "Los Angeles",
"postal_code": "90210",
"region": "California",
"country_code": "US"
},
"price": {
"value": "199",
"currency": "USD"
},
"sale_price": {
"value": "299",
"currency": "USD"
},
"neighborhoods": [
"uptown",
"downtown"
],
"geographic_coordinates": {
"longitude": 2.294464,
"latitude": 48.858353
},
"guest_ratings": {
"rating_system": "tripAdvisor",
"score": "7.8",
"max_score": "10",
"number_of_reviewers": "300"
},
"star_rating": "3.5",
"ios_app_link": {
"url": "myapp://a/random/path",
"app_store_id": "427916203",
"app_name": "Snapchat Hotel App"
},
"android_app_link": {
"url": "https://snapchathoteldeeplink.com",
"package": "com.snap.hotel",
"app_name": "Snapchat Hotel App"
},
"loyalty_program": "Premium program",
"custom_labels": {},
"activity": "ACTIVE",
}
},
]
}
Flight Search
The flight search is used to search a catalog for flights given a provided filter, each level of the filter can only have one operator and we allow up to two levels of nesting, for each operator we can have up to 10 fields
HTTP Request
POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/flights/search
Request Parameters
Parameter | Required | Description |
---|---|---|
catalog_id | R | Catalog ID |
Body Parameters
Parameter | Required | Description |
---|---|---|
limit | O | this pagination variable specifies the number of products per page 50 - 1000 |
Filter properties
Property | Possible values |
---|---|
ID | |
ORIGIN_AIRPORT | |
DESTINATION_AIRPORT | |
ORIGIN_CITY | |
DESTINATION_CITY | |
PRICE_AMOUNT | |
CUSTOM_LABEL_0 | |
CUSTOM_LABEL_1 | |
CUSTOM_LABEL_2 | |
CUSTOM_LABEL_3 | |
CUSTOM_LABEL_4 | |
ITEM_SET_ID | |
PRODUCT_STATUS | COMPLETE, FAILED_MEDIA |
ELIGIBLE_AD_TYPE | APP_INSTALL, REMOTE_WEBPAGE, DEEPLINK_ATTACHMENT |
Filter Operator
Operator | Description | Can be used with |
---|---|---|
EQ | Equal to | Integer, Float, String |
NEQ | Not Equal to | Integer, Float, String |
GT | Greater than | Integer, Float |
GTE | Greater than or equal to | Integer, Float |
LT | Less than | Integer, Float |
LTE | Less than or equal to | Integer, Float |
CONTAINS | Contains | String |
NOT_CONTAINS | Does not contain | String |
I_CONTAINS | Contains - Case insensitive | String |
I_NOT_CONTAINS | Does not contain - Case insensitive | String |
STARTS_WITH | Starts with | String |
I_STARTS_WITH | Starts with - Case insensitive | String |
IS_ANY | Is any of the list. Only works with strings containing alphanumeric characters | List of Strings |
IS_NOT_ANY | Is not any of the list. Only works with strings containing alphanumeric characters | List of Strings |
I_IS_ANY | Is any of the list - Case insensitive. Only works with strings containing alphanumeric characters | List of Strings |
I_IS_NOT_ANY | Is not any of the list - Case insensitive. Only works with strings containing alphanumeric characters | List of Strings |
Example 1 - Flight Search
Request the entire Flight Catalog using a pagination of 50 products, setting "limit":50
attribute achieves this.
curl -X POST \
-d '{"limit": 50}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/flights/search
The above command returns JSON structured like this (this response has been shortened):
{
"request_status": "SUCCESS",
"request_id": "5f19a01000ff00fff430ee807f720001737e616473617069736300016275696c642d63616265303361622d312d3336392d3000010108",
"summary": {
"total_flights": {
"count": "209",
"relation": "EQ"
}
},
"paging": {
"next_link": "https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/flights/search?cursor=IlNDLTE1MCI=&limit=50",
"next_link_body": "H4sIAAAAAAAAAONiAAB1-ja7AgAAAA=="
},
"flights": [
{
"sub_request_status": "SUCCESS",
"flight": {
"id": "3675153106588450894",
"external_id": "1",
"catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
"created_at": "2022-07-06T01:14:01.354366Z",
"updated_at": "2022-07-06T02:12:36.444333Z",
"origin_airport_code": "BWI",
"destination_airport_code": "SEA",
"link": "https://www.example.com/flights/tt0080339/2",
"description": "Flight to Seattle from Baltimore",
"price": {
"value": "95.00",
"currency": "USD"
},
"main_media": {
"url": "https://storage.snap-flights-example.com/flights-assets/image1.jpg",
"tags": [
"banner"
]
},
"icon_media": {
"url": "https://storage.snap-flights-example.com/flights-assets/icon.jpg",
},
"additional_media": [
{
"url": "https://storage.snap-flights-example.com/flights-assets/image2.jpg",
}
],
"origin_city": "Baltimore",
"destination_city": "Seattle",
"ios_app_link": {
"url": "myapp://a/random/path",
"app_store_id": "427916203",
"app_name": "Snap Flight App"
},
"android_app_link": {
"url": "https://snapairplanedeeplink.com",
"package": "com.snap.airplane",
"app_name": "Snap Flight App"
},
"custom_labels": {}
}
},
...
{
"sub_request_status": "SUCCESS",
"flight": {
"id": "877657809172084551",
"external_id": "6",
"catalog_id": "6d5def3e-a2af-4dcc-88c1-9da72632e25f",
"created_at": "2022-07-06T01:14:01.354366Z",
"updated_at": "2022-07-06T02:12:26.927293Z",
"origin_airport_code": "SFO",
"destination_airport_code": "LAX",
"link": "https://www.example.com/flights/tt0080339/4",
"description": "Flight SFO to LAX",
"price": {
"value": "495.00",
"currency": "USD"
},
"main_media": {
"url": "https://storage.snap-flights-example.com/flights-assets/image1.jpg",
"tags": [
"banner"
]
},
"icon_media": {
"url": "https://storage.snap-flights-example.com/flights-assets/icon.jpg",
},
"additional_media": [
{
"url": "https://storage.snap-flights-example.com/flights-assets/image2.jpg",
}
],
"origin_city": "San Francisco",
"destination_city": "Los Angeles",
"ios_app_link": {
"url": "myapp://a/random/path",
"app_store_id": "427916203",
"app_name": "Snap Flight App"
},
"android_app_link": {
"url": "https://snapairplanedeeplink.com",
"package": "com.movie.airplane",
"app_name": "Snap Flight App"
},
"custom_labels": {}
}
},
]
}
Example 2 - Flight Search
Request all flights within a specific Product Set, where the origin airport attribute contains the term ‘BWI’.
-d '{"filter": {"ORIGIN_AIRPORT": {"CONTAINS": "BWI"}}}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/flights/search
The above command returns JSON structured like this (this response has been shortened):
{
"request_status": "SUCCESS",
"request_id": "5f19a01000ff00fff430ee807f720001737e616473617069736300016275696c642d63616265303361622d312d3336392d3000010108",
"summary": {
"total_flights": {
"count": "209",
"relation": "EQ"
}
},
"flights": [
{
"sub_request_status": "SUCCESS",
"flight": {
"id": "3675153106588450894",
"external_id": "1",
"catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
"created_at": "2022-07-06T01:14:01.354366Z",
"updated_at": "2022-07-06T02:12:36.444333Z",
"origin_airport_code": "BWI",
"destination_airport_code": "SEA",
"link": "https://www.example.com/flights/tt0080339/2",
"description": "Flight to Seattle from Baltimore",
"price": {
"value": "95.00",
"currency": "USD"
},
"main_media": {
"url": "https://storage.snap-flights-example.com/flights-assets/image1.jpg",
"tags": [
"banner"
]
},
"icon_media": {
"url": "https://storage.snap-flights-example.com/flights-assets/icon.jpg",
},
"additional_media": [
{
"url": "https://storage.snap-flights-example.com/flights-assets/image2.jpg",
}
],
"origin_city": "Baltimore",
"destination_city": "Seattle",
"ios_app_link": {
"url": "myapp://a/random/path",
"app_store_id": "427916203",
"app_name": "Snap Flight App"
},
"android_app_link": {
"url": "https://snapairplanedeeplink.com",
"package": "com.snap.airplane",
"app_name": "Snap Flight App"
},
"custom_labels": {}
}
},
...
{
"sub_request_status": "SUCCESS",
"flight": {
"id": "877657809172084551",
"external_id": "3",
"catalog_id": "6d5def3e-a2af-4dcc-88c1-9da72632e25f",
"created_at": "2022-07-06T01:14:01.354366Z",
"updated_at": "2022-07-06T02:12:26.927293Z",
"origin_airport_code": "BWI",
"destination_airport_code": "LAX",
"link": "https://www.example.com/flights/tt0080339/4",
"description": "Flight BWI to LAX",
"price": {
"value": "295.00",
"currency": "USD"
},
"main_media": {
"url": "https://storage.snap-flights-example.com/flights-assets/image1.jpg",
"tags": [
"banner"
]
},
"icon_media": {
"url": "https://storage.snap-flights-example.com/flights-assets/icon.jpg",
},
"additional_media": [
{
"url": "https://storage.snap-flights-example.com/flights-assets/image2.jpg",
}
],
"origin_city": "Baltimore",
"destination_city": "Los Angeles",
"ios_app_link": {
"url": "myapp://a/random/path",
"app_store_id": "427916203",
"app_name": "Snap Flight App"
},
"android_app_link": {
"url": "https://snapairplanedeeplink.com",
"package": "com.movie.airplane",
"app_name": "Snap Flight App"
},
"custom_labels": {}
}
},
]
}
Product Set
A product set is a group of products from your catalog defined by filters.
Create a Product Set
Parameter | Description |
---|---|
name | Name of the Product Set |
filter | Filter rule to be applied. See table below |
Product Set Filter
Parameter | Description |
---|---|
operator | At most 1 type of logical operator (AND, OR) |
product attribute | The attribute of the product to filter on |
filter operator | The operator to be used |
filter value | The value to be matched |
Filter Operator
Operator | Description | Can be used with |
---|---|---|
EQ | Equal to | Integer, Float, String |
NEQ | Not Equal to | Integer, Float, String |
GT | Greater than | Integer, Float |
GTE | Greater than or equal to | Integer, Float |
LT | Less than | Integer, Float |
LTE | Less than or equal to | Integer, Float |
CONTAINS | Contains | String |
NOT_CONTAINS | Does not contain | String |
I_CONTAINS | Contains - Case insensitive | String |
I_NOT_CONTAINS | Does not contain - Case insensitive | String |
STARTS_WITH | Starts with | String |
I_STARTS_WITH | Starts with - Case insensitive | String |
IS_ANY | Is any of the list. Only works with strings containing alphanumeric characters | List of Strings |
IS_NOT_ANY | Is not any of the list. Only works with strings containing alphanumeric characters | List of Strings |
I_IS_ANY | Is any of the list - Case insensitive. Only works with strings containing alphanumeric characters | List of Strings |
I_IS_NOT_ANY | Is not any of the list - Case insensitive. Only works with strings containing alphanumeric characters | List of Strings |
Product attributes And Supported Filters
Product Attribute | Filter Operators Supported | Filter Value |
---|---|---|
AGE_GROUP | EQ, NEQ | NEWBORN, INFANT, TODDLER, KIDS, ADULT |
AVAILABILITY | EQ, NEQ | IN_STOCK, OUT_OF_STOCK, PREORDER, DISCONTINUED, AVAILABLE_FOR_ORDER |
BRAND | ALL | String, List of Strings |
COLOR | ALL | String, List of Strings |
CONDITION | EQ, NEQ | NEW, REFURBISHED, USED |
CUSTOM_LABEL_0 | ALL | String, List of Strings |
CUSTOM_LABEL_1 | ALL | String, List of Strings |
CUSTOM_LABEL_2 | ALL | String, List of Strings |
CUSTOM_LABEL_3 | ALL | String, List of Strings |
CUSTOM_LABEL_4 | ALL | String, List of Strings |
GENDER | EQ, NEQ | MALE, FEMALE, UNISEX |
GOOGLE_PRODUCT_CATEGORY | ALL | String, List of Strings |
ID | ALL | String, List of Strings |
ITEM_GROUP_ID | ALL | String, List of Strings |
MATERIAL | ALL | String, List of Strings |
PATTERN | ALL | String, List of Strings |
PRICE_AMOUNT | EQ, NEQ, GT, GTE, LT, LTE | Number, 2 decimals |
PRICE_CURRENCY | EQ, NEQ | ISO 4217 currency code |
PRODUCT_TYPE | ALL | String, List of Strings |
SIZE | ALL | String, List of Strings |
TITLE | ALL | String, List of Strings |
API Limits
- Max # of product sets per catalog: 50
- Max # of product sets per batch: 50
- Number of filter rules chained by a logical operator (AND, OR) per product set: 10
- Product set name length: 3-255
- List of Strings for all IS_ANY queries max length: 10
- Any string filter value length: 1-255
Product Set Filter Entry Examples
TITLE contains “Red Shoes"
{"TITLE": {
"CONTAINS": "Red Shoes"
}
}
BRAND is any of “brand1”, “brand2”
{"BRAND": {
"IS_ANY": ["brand1", "brand2"]
}
}
AVAILABILITY is IN_STOCK
Note: Caps separated by underscore should be used for enums.
{"AVAILABILITY": {
"EQ": "IN_STOCK"
}
}
PRICE_AMOUNT greater than US$15.50
Note: Float value should be wrapped in a string
{"AND": [
{"PRICE_AMOUNT": {
"GT": "15.50"
}
},
{"PRICE_CURRENCY": {
"EQ": "US"
}
}
]
}
Filter chaining
Price greater than $15.50 and availability is in stock. Only one operator is allowed at a time.
{"AND": [
{"PRICE_AMOUNT": {
"GT": "15.50"
}
},
{"AVAILABILITY": {
"EQ": "IN_STOCK"
}
}
]
}
Create a Product Set
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"product_sets": [{"name": "In Stock", "filter": {"AVAILABILITY": {"EQ": "IN_STOCK"}}}]}' \
https://adsapi.snapchat.com/v1/catalogs/306544db-be30-472c-ab87-c277b4d61d0f/product_sets
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "caf894e2-3bd1-420a-ae3a-5b1a19289488",
"product_sets": [
{
"sub_request_status": "SUCCESS",
"product_set": {
"id": "8d2d659e-0e3c-4938-a417-09d1a8fa4348",
"catalog_id": "306544db-be30-472c-ab87-c277b4d61d0f",
"name": "In Stock",
"filter": {
"AVAILABILITY": {
"EQ": "IN_STOCK"
}
},
"created_at": "2019-06-14T18:38:49.640871Z",
"updated_at": "2019-06-14T18:38:49.640871Z"
}
}
]
}
This creates an Product Set within a Catalog.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | Name of the Product Set | Yes | |
filter | Filter rule to be applied | Yes | See tables above |
HTTP Request
POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/product_sets
Parameters
Parameter | Default | Description |
---|---|---|
catalog_id | Catalog ID |
ERRORS
Error | Cause |
---|---|
CAT_VALIDATION_ERROR_INVALID_PRODUCT_SET_FILTER | Thrown when the product set filter provided is invalid |
CAT_VALIDATION_ERROR_MAX_PRODUCT_SET_COUNT_FOR_CATALOG_REACHED | Thrown when the maximum product set count for catalog has been reached |
CAT_VALIDATION_ERROR_MAX_PRODUCT_SET_FILTER_ENTRY_COUNT_REACHED | Thrown if the max product set filter entry count is reached |
CAT_VALIDATION_ERROR_TOO_MANY_PRODUCT_SETS_IN_BATCH | Thrown when there are too many product sets in a batch |
CAT_VALIDATION_ERROR_PRODUCT_SET_NAME_LENGTH_INVALID | Thrown if the product set name length is not valid |
CAT_VALIDATION_ERROR_INVALID_PRODUCT_SET_ID | Thrown if the product set id provided is invalid |
CAT_VALIDATION_ERROR_INVALID_PAGINATION_READ_LIMIT | Thrown if the read limit specified by user is invalid |
CAT_VALIDATION_ERROR_READ_LIMIT_MUST_BE_SPECIFIED | Thrown if only pagination cursor is provided but not an explicit read limit |
CAT_VALIDATION_ERROR_INVALID_CURSOR | Thrown if the pagination cursor provided by the user is invalid |
Update a Product Set
curl -X PUT -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"product_sets": [{ "id": "8d2d659e-0e3c-4938-a417-09d1a8fa4348","name": "In Stock & Red","filter": {"AND": [{"AVAILABILITY": {"EQ": "IN_STOCK"}},{"COLOR": {"IS_ANY": ["red"]}}]}}]}' \
https://adsapi.snapchat.com/v1/product_sets
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "caf894e2-3bd1-420a-ae3a-5b1a19289488",
"product_sets": [
{
"sub_request_status": "SUCCESS",
"product_set": {
"id": "8d2d659e-0e3c-4938-a417-09d1a8fa4348",
"catalog_id": "306544db-be30-472c-ab87-c277b4d61d0f",
"name": "In Stock & Red",
"filter": {
"AND": [
{
"AVAILABILITY": {
"EQ": "IN_STOCK"
}
},
{
"COLOR": {
"IS_ANY": ["red"]
}
}
]
},
"created_at": "2019-06-14T18:38:49.640871Z",
"updated_at": "2019-06-14T20:38:49.640871Z"
}
}
]
}
This endpoint will update a specified Product Set.
HTTP Request
PUT https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/product_sets
Parameters
Parameter | Default | Description |
---|---|---|
catalog_id | Catalog ID |
Delete a Product Set
curl -X DELETE -H https://adsapi.snapchat.com/v1/product_sets/8d2d659e-0e3c-4938-a417-09d1a8fa4348 \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "caf894e2-3bd1-420a-ae3a-5b1a19289488",
"product_sets": []
}
This endpoint will delete a specified Product Set.
HTTP Request
PUT https://adsapi.snapchat.com/v1/product_sets/{product_set_id}
Parameters
Parameter | Default | Description |
---|---|---|
catalog_id | Catalog ID |
Get All Product Sets
curl
"https://adsapi.snapchat.com/v1/catalogs/306544db-be30-472c-ab87-c277b4d61d0f/product_sets?cursor=abc123&limit=50" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "caf894e2-3bd1-420a-ae3a-5b1a19289488",
"product_sets": [
{
"sub_request_status": "SUCCESS",
"product_set": {
"id": "8d2d659e-0e3c-4938-a417-09d1a8fa4348",
"catalog_id": "306544db-be30-472c-ab87-c277b4d61d0f",
"name": "In Stock",
"filter": {
"AVAILABILITY": {
"EQ": "IN_STOCK"
}
},
"created_at": "2019-06-14T18:38:49.640871Z",
"updated_at": "2019-06-14T18:38:49.640871Z"
}
}
],
"paging": {
"next_link": "https://adsapi.snapchat.com/v1/catalogs/306544db-be30-472c-ab87-c277b4d61d0f/product_sets?cursor=def456&limit=50"
}
}
This endpoint will get all the Product Sets within the Catalog.
HTTP Request
GET https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/product_sets?cursor=abc123&limit=50
Parameters
Parameter | Default | Description |
---|---|---|
catalog_id | Catalog ID |
Get a Product Set by ID
curl
"https://adsapi.snapchat.com/v1/product_sets/8d2d659e-0e3c-4938-a417-09d1a8fa4348" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "caf894e2-3bd1-420a-ae3a-5b1a19289488",
"product_sets": [
{
"sub_request_status": "SUCCESS",
"product_set": {
"id": "8d2d659e-0e3c-4938-a417-09d1a8fa4348",
"catalog_id": "306544db-be30-472c-ab87-c277b4d61d0f",
"name": "In Stock",
"filter": {
"AVAILABILITY": {
"EQ": "IN_STOCK"
}
},
"created_at": "2019-06-14T18:38:49.640871Z",
"updated_at": "2019-06-14T18:38:49.640871Z"
}
}
]
}
This endpoint will get a specified Product Set.
HTTP Request
GET: https://adsapi.snapchat.com/v1/product_sets/{product_set_id}
Parameters
Parameter | Default | Description |
---|---|---|
product_set_id | Product Set ID |
Create the Campaign
For DPA, the following fields have been updated or added to the Campaign object:
Attribute | Description | Required | Possible Values |
---|---|---|---|
product_properties | Product Properties to be associated with the Campaign | Yes | See table below |
product_properties
Attribute | Description | Required | Possible Values |
---|---|---|---|
catalog_id | The Product Catalog ID to be associated with the Campaign | Yes | “product_properties”: {“catalog_id”: “1bcfb8cd-2e57”} |
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '"campaigns": [{"name": "First DPA campaign", "ad_account_id": "497979f0-ed17-4971-8288-054883f1cbca","daily_budget_micro": "100000000000","status": "PAUSED","start_time": "2019-12-01T17:12:49.707Z","end_time": "2019-12-12T17:12:49.707Z","product_properties" : {"catalog_id": "079d2a83-e422-4c0e-918b-8db17f087205"}}]}' \
"https://adsapi.snapchat.com/v1/adaccounts/{ad_acount_id}/campaigns"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5d8bd65100ff0d03b71380cd950001737e616473617069736300016275696c642d34353936393233352d312d3239312d3100010119",
"campaigns": [
{
"sub_request_status": "SUCCESS",
"campaign": {
"id": "41b98396-4aaa-4a8e-acd4-50d25ac87488",
"updated_at": "2019-09-25T21:04:18.433Z",
"created_at": "2019-09-25T21:04:18.433Z",
"name": "First DPA campaign",
"ad_account_id": "497979f0-ed17-4971-8288-054883f1cbca",
"daily_budget_micro": 100000000000,
"status": "PAUSED",
"objective": "BRAND_AWARENESS",
"start_time": "2019-12-01T17:12:49.707Z",
"end_time": "2019-12-12T17:12:49.707Z",
"product_properties": {
"catalog_id": "079d2a83-e422-4c0e-918b-8db17f087205"
}
}
}
]
}
Pixel
The Pixel associated with the Ad Account will be the one assumed as the event source for targeting.
Create the Ad Squad
DPA Ad Squads have specific requirements for the targeting
and optimization_goal
attributes, DPA Ad Squads also require the product_properties
attribute.
Attribute | Description | Required | Possible Values |
---|---|---|---|
campaign_id | Campaign ID | R | |
bid_micro | Max Bid (micro-currency) | R | Minimum value 10000 , Maximum value 1000000000 |
billing_event | Billing Event | R | IMPRESSION |
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 | R | |
optimization_goal | Optimization Goal | R | For prospecting; IMPRESSIONS, SWIPES, APP_INSTALLS, VIDEO_VIEWS, VIDEO_VIEWS_15_SEC, PIXEL_PAGE_VIEW, PIXEL_ADD_TO_CART, PIXEL_PURCHASE, PIXEL_SIGNUP, APP_ADD_TO_CART, APP_PURCHASE, APP_SIGNUP , For re-targeting; PIXEL_PURCHASE, PIXEL_PAGE_VIEW, PIXEL_ADD_TO_CART, APP_PURCHASE, APP_SIGN_UP, APP_ADD_TO_CART, SWIPES |
placement_v2 | Placement | R | Json object containing advanced placement options See placement_v2 |
start_time | Start time | O | |
status | Ad Squad status | R | 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 | Must contain product_audiences array for retargeting. For prospecting, omit the product_audiences array, also see App Install states targeting |
type | Ad Squad Type | R | SNAP_ADS |
cap_and_exclusion_config | The frequency cap and exclusion spec | O | |
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 minimum ROAS for the MIN_ROAS BidStrategy | R if BidStrategy = MIN_ROAS | Minimum desired ROAS |
pixel_id | Pixel to be associated with the Ad Squad | Required for retargeting, Optional for prospecting | |
measurement_provider_names | approved measurement provider | O | MOAT_SS, DOUBLEVERIFY |
delivery_constraint | Type of delivery | R | DAILY_BUDGET (when using daily_budget_micro), LIFETIME_BUDGET (when using lifetime_budget_micro) |
pacing_type | Type of pacing | O | STANDARD (default), ACCELERATED |
event_sources | Snap App Id to be associated with the Ad Squad | O | Availble for Dynamic Product Ads when using APP_INSTALL / DEEP_LINK, see App Install states |
For DPA, the following attribute has been added to the Ad Squad object. Only retargeting and prospecting are supported now, cross-sell and upsell use cases will be supported soon.
Attribute | Description | Required | Possible Values |
---|---|---|---|
product_properties | Product Properties to be associated with the Ad Squad | R | See table below |
product_properties
Attribute | Description | Required | Possible Values |
---|---|---|---|
product_set_id | The Product Set ID to be associated with the Ad Squad | R | “product_properties”: {“catalog_id”: “1bcfb8cd-2e57”} |
catalog_vertical | Catalog vertical, automatically set by the Catalog | Read-only | COMMERCE, HOTELS, PLACES, FLIGHTS |
product_audiences
Attribute | Description | Required | Possible Values |
---|---|---|---|
event_type | The Pixel or App event type to be targeted | R | Only PAGE_VIEW, VIEW_CONTENT, ADD_CART, PURCHASE are supported |
product_set | The Product Set ID used to track pixel events against | R | For retargeting, product_set must match product_set_id on the Ad Squad |
retention_seconds | Retention in seconds | R | Min 86400 (1 day), Max 2592000 (30 days) |
operation | Operation to be applied | R | INCLUDE or EXCLUDE |
Prospecting Ad Squad
Prospecting does not require that the Snap Pixel is activated at Ad Account level and associated with the Ad Squad, having a pixel however will allow you to track PIXEL_PURCHASE events which along with the purchase value and transaction id will allow you to calculate a Return on Ad Spend.
Prospecting Example
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adsquads": [{"name": "DPA Prospecting Ad Squad example","optimization_goal": "IMPRESSIONS","status": "ACTIVE","campaign_id": "4114749d-7362-42e8-b05d-48ef7984a91d","type": "SNAP_ADS","targeting": {"regulated_content": false,"geos": [{"country_code": "us"}],"product_audiences": [{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "PAGE_VIEW","retention_seconds": 1209600,"operation": "EXCLUDE"},{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "ADD_CART","retention_seconds": 1209600,"operation": "EXCLUDE"},{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "PURCHASE","retention_seconds": 1209600,"operation": "EXCLUDE"},{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "VIEW_CONTENT","retention_seconds": 1209600,"operation": "EXCLUDE"}],"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": "2020-06-16T23:25:34.370Z","end_time": "2020-06-21T06:59:59.000Z","pixel_id": "9315b2c2-3680-411d-b6c1-d17de25fc1e0","delivery_constraint": "DAILY_BUDGET","pacing_type": "STANDARD","product_properties": {"product_set_id": "da17a495-0392-448f-b4f4-f027ecdcb794"}}]}' \
https://adsapi.snapchat.com/v1/campaigns/4114749d-7362-42e8-b05d-48ef7984a91d/adsquads
The above example request for Prospecting returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eea238500ff08f85033418b420001737e616473617069736300016275696c642d37316537353330622d312d3335392d3300010129",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "5d9556b8-eb0c-4209-b23a-385a79918e6b",
"updated_at": "2020-06-17T14:07:02.933Z",
"created_at": "2020-06-17T14:07:02.933Z",
"name": "DPA Prospecting Ad Squad example",
"status": "ACTIVE",
"campaign_id": "4114749d-7362-42e8-b05d-48ef7984a91d",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"geos": [
{
"country_code": "us"
}
],
"product_audiences": [
{
"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
"event_type": "PAGE_VIEW",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
},
{
"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
"event_type": "ADD_CART",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
},
{
"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
"event_type": "PURCHASE",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
},
{
"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
"event_type": "VIEW_CONTENT",
"retention_seconds": 2592000,
"operation": "EXCLUDE"
}
],
"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": "2020-06-16T23:25:34.370Z",
"end_time": "2020-06-21T06:59:59.000Z",
"optimization_goal": "IMPRESSIONS",
"pixel_id": "9315b2c2-3680-411d-b6c1-d17de25fc1e0",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"product_properties": {
"product_set_id": "da17a495-0392-448f-b4f4-f027ecdcb794",
"catalog_vertical": "COMMERCE"
}
}
}
]
}
In the following example of product_audiences
we target all users who haven’t triggered the specific events PAGE_VIEW, ADD_CART, PURCHASE, VIEW_CONTENT on your website/app for the past 14 days = 1209600 seconds.
"product_audiences": [
{
"product_set": "{{product_set_id}}",
"event_type": "PAGE_VIEW",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
},
{
"product_set": "{{product_set_id}}",
"event_type": "ADD_CART",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
},
{
"product_set": "{{product_set_id}}",
"event_type": "PURCHASE",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
},
{
"product_set": "{{product_set_id}}",
"event_type": "VIEW_CONTENT",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
}
]
Retargeting Ad Squad
Retargeting requires that you have a Pixel activated and associated with the Ad Squad.
Retargeting Example 1
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adsquads": [{"name": "DPA Retargeting Ad Squad - Viewers and Add Cart","optimization_goal": "SWIPES","status": "ACTIVE","campaign_id": "4114749d-7362-42e8-b05d-48ef7984a91d","type": "SNAP_ADS","targeting": {"regulated_content": false,"geos": [{"country_code": "us"}],"product_audiences": [{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "PAGE_VIEW","retention_seconds": 1209600,"operation": "INCLUDE"},{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "ADD_CART","retention_seconds": 1209600,"operation": "INCLUDE"},{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "PURCHASE","retention_seconds": 1209600,"operation": "EXCLUDE"},{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "VIEW_CONTENT","retention_seconds": 1209600,"operation": "INCLUDE"}],"auto_expansion_options":{"interest_expansion_option":{"enabled": true},"custom_audience_expansion_option":{"enabled": true}}},"placement_v2": {"config": "AUTOMATIC"},"billing_event": "IMPRESSION","bid_strategy": "TARGET_COST","bid_micro": 1000000,"daily_budget_micro": 50000000,"start_time": "2020-06-16T23:25:34.370Z","end_time": "2020-06-21T06:59:59.000Z","pixel_id": "9315b2c2-3680-411d-b6c1-d17de25fc1e0","delivery_constraint": "DAILY_BUDGET","pacing_type": "STANDARD","product_properties": {"product_set_id": "da17a495-0392-448f-b4f4-f027ecdcb794"}}]}' \
https://adsapi.snapchat.com/v1/campaigns/4114749d-7362-42e8-b05d-48ef7984a91d/adsquads
The above request for Retargeting Example 1 returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eea3a9800ff07b42dbea034bf0001737e616473617069736300016275696c642d37316537353330622d312d3335392d3300010122",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "a7171164-12b0-4576-a441-52eb57679ede",
"updated_at": "2020-06-17T03:44:19.788Z",
"created_at": "2020-06-17T00:44:19.486Z",
"name": "DPA Retargeting Ad Squad - Viewers and Add Cart",
"status": "ACTIVE",
"campaign_id": "4114749d-7362-42e8-b05d-48ef7984a91d",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"geos": [
{
"country_code": "us"
}
],
"product_audiences": [
{
"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
"event_type": "PAGE_VIEW",
"retention_seconds": 1209600,
"operation": "INCLUDE"
},
{
"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
"event_type": "ADD_CART",
"retention_seconds": 1209600,
"operation": "INCLUDE"
},
{
"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
"event_type": "PURCHASE",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
},
{
"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
"event_type": "VIEW_CONTENT",
"retention_seconds": 1209600,
"operation": "INCLUDE"
}
],
"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,
"bid_strategy": "TARGET_COST",
"daily_budget_micro": 50000000,
"start_time": "2020-06-16T23:25:34.370Z",
"end_time": "2020-06-21T06:59:59.000Z",
"optimization_goal": "SWIPES",
"pixel_id": "9315b2c2-3680-411d-b6c1-d17de25fc1e0",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"product_properties": {
"product_set_id": "da17a495-0392-448f-b4f4-f027ecdcb794",
"catalog_vertical": "COMMERCE"
}
}
}
]
}
In the following example of product_audiences
we target all users who have triggered the specific events PAGE_VIEW, ADD_CART, VIEW_CONTENT, but not triggered a PURCHASE event on your website/app in the past 14 days = 1209600 seconds.
"product_audiences": [
{
"product_set": "{{product_set_id}}",
"event_type": "PAGE_VIEW",
"retention_seconds": 1209600,
"operation": "INCLUDE"
},
{
"product_set": "{{product_set_id}}",
"event_type": "VIEW_CONTENT",
"retention_seconds": 1209600,
"operation": "INCLUDE"
},
{
"product_set": "{{product_set_id}}",
"event_type": "ADD_CART",
"retention_seconds": 1209600,
"operation": "INCLUDE"
},
{
"product_set": "{{product_set_id}}",
"event_type": "PURCHASE",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
}
]
Retargeting Example 2
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adsquads": [{"name": "DPA Retargeting Ad Squad - Add Cart","optimization_goal": "PIXEL_PURCHASE","status": "ACTIVE","campaign_id": "4114749d-7362-42e8-b05d-48ef7984a91d","type": "SNAP_ADS","targeting": {"regulated_content": false,"geos": [{"country_code": "us"}],"product_audiences": [{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "ADD_CART","retention_seconds": 2592000,"operation": "INCLUDE"},{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "PURCHASE","retention_seconds": 2592000,"operation": "EXCLUDE"}],"auto_expansion_options":{"interest_expansion_option":{"enabled": true},"custom_audience_expansion_option":{"enabled": true}}},"placement_v2": {"config": "AUTOMATIC"},"billing_event": "IMPRESSION","bid_strategy": "TARGET_COST","bid_micro": 1000000,"daily_budget_micro": 50000000,"start_time": "2020-06-16T23:25:34.370Z","end_time": "2020-06-21T06:59:59.000Z","pixel_id": "9315b2c2-3680-411d-b6c1-d17de25fc1e0","delivery_constraint": "DAILY_BUDGET","pacing_type": "STANDARD","product_properties": {"product_set_id": "da17a495-0392-448f-b4f4-f027ecdcb794"}}]}' \
https://adsapi.snapchat.com/v1/campaigns/4114749d-7362-42e8-b05d-48ef7984a91d/adsquads
The above request for Retargeting Example 2 returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eea3a9800ff07b42dbea034bf0001737e616473617069736300016275696c642d37316537353330622d312d3335392d3300010122",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "a7171164-12b0-4576-a441-52eb57679ede",
"updated_at": "2020-06-15T03:44:19.788Z",
"created_at": "2020-06-15T00:44:19.486Z",
"name": "DPA Retargeting Ad Squad - Add Cart",
"status": "ACTIVE",
"campaign_id": "4114749d-7362-42e8-b05d-48ef7984a91d",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"geos": [
{
"country_code": "us"
}
],
"product_audiences": [
{
"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
"event_type": "ADD_CART",
"retention_seconds": 2592000,
"operation": "INCLUDE"
},
{
"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
"event_type": "PURCHASE",
"retention_seconds": 2592000,
"operation": "EXCLUDE"
}
],
"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,
"bid_strategy": "TARGET_COST",
"daily_budget_micro": 50000000,
"start_time": "2020-06-18T23:25:34.370Z",
"end_time": "2020-06-21T06:59:59.000Z",
"optimization_goal": "PIXEL_PURCHASE",
"pixel_id": "9315b2c2-3680-411d-b6c1-d17de25fc1e0",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"product_properties": {
"product_set_id": "da17a495-0392-448f-b4f4-f027ecdcb794"
}
}
}
]
}
In the following example of product_audiences
we target all users who have triggered ADD_CART, but not triggered a PURCHASE event on your website/app, in the past 30 days = 2592000 seconds.
"product_audiences": [
{
"product_set": "{{product_set_id}}",
"event_type": "ADD_CART",
"retention_seconds": 2592000,
"operation": "INCLUDE"
},
{
"product_set": "{{product_set_id}}",
"event_type": "PURCHASE",
"retention_seconds": 2592000,
"operation": "EXCLUDE"
}
]
Create a Creative
For DPA, the following fields have been updated or added to the Creative object. Only Creatives of type WEB_VIEW, APP_INSTALL and DEEP_LINK are supported now.
Attribute | Description | Required | Possible Values |
---|---|---|---|
render_type | Render Type | Yes | DYNAMIC (required for DPA) |
type | Type of the Creative | Yes | Must be set to WEB_VIEW, APP_INSTALL or DEEP_LINK for render_type=DYNAMIC. If type is APP_INSTALL or DEEP_LINK, Campaign must contain “measurement_spec” for proper tracking. |
dynamic_render_properties | Properties to be set when render_type is DYNAMIC | Yes | See table below |
url_macro_parameters | Property that provides url macro parameters appended to all product urls | O | Supported macros:
Format eg: utm_campaign={{campaign.id}}&utm_term={{ad.name}} |
dynamic_render_properties
Attribute | Description | Required | Possible Values |
---|---|---|---|
dynamic_template_id | ID of the Dynamic template to be used | R | Dynamic Template ID |
product_set_id | ID of the Product Set from which products will be selected to be shown in the ads | Yes | Valid Product Set ID. Product Set must exist. Product Set must have products. Must match Ad Squad’s product_set_id. |
curl -X POST \
-d '{"creatives": [{"name": "DPA Ad", "ad_account_id": "497979f0-ed17-4971-8288-054883f1cbca", "type": "WEB_VIEW", "headline": "Shopping Forever", "brand_name": "DPA Brand", "call_to_action": "SHOP_NOW", "render_type": "DYNAMIC", "url_macro_parameters": "utm_campaign={{adset.name}}&utm_content={{ad.id}}", "dynamic_render_properties": {"dynamic_template_id": "75aa5c00-cabf-4b37-991a-7462ecf9a1cc", "product_set_id": "62984de1-0c0c-46e6-a21b-14e9cf5e2523"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/497979f0-ed17-4971-8288-054883f1cbca/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5d8c2f9c00ff051b94bb93a0a70001737e616473617069736300016275696c642d35653536303765312d312d3239312d3500010124",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "bb0c57ca-8bf2-4f15-8162-704e9c33d88e",
"updated_at": "2019-09-26T03:25:16.459Z",
"created_at": "2019-09-26T03:25:16.459Z",
"name": "DPA Ad",
"ad_account_id": "497979f0-ed17-4971-8288-054883f1cbca",
"type": "WEB_VIEW",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Shopping Forever",
"brand_name": "DPA Brand",
"call_to_action": "SHOP_NOW",
"render_type": "DYNAMIC",
"dynamic_render_properties": {
"dynamic_template_id": "75aa5c00-cabf-4b37-991a-7462ecf9a1cc",
"product_set_id": "62984de1-0c0c-46e6-a21b-14e9cf5e2523"
},
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD"
}
}
]
}
Create the Ad
For DPA, the following fields have been updated or added to the Ad object.
Attribute | Description | Required | Possible Values |
---|---|---|---|
creative_id | ID of the Creative to be used | Yes | product_set_id of the Creative used must match the product_set_id on the Ad Squad associated with this Ad. |
ad_squad_id | ID of the Ad Squad | Yes | Ad Squad must have a product_set_id associated with it. And product_set_id of the Creative used must match the product_set_id on the Ad Squad associated with this Ad. |
type | Type of the Ad | Yes | Must be set to REMOTE_WEBPAGE, APP_INSTALL or DEEP_LINK. If type is APP_INSTALL or DEEP_LINK, Campaign must contain “measurement_spec” for proper tracking. |
render_type | The render type for the Dynamic Product Ad | Required | DYNAMIC |
curl -X POST \
-d '{"ads": [{"name": "DPA Ad", "ad_squad_id": "57d7ad65-1a40-40da-9443-6eafb15b0273", "creative_id": "bb0c57ca-8bf2-4f15-8162-704e9c33d88e", "status": "PAUSED", "type": "REMOTE_WEBPAGE", "render_type": "DYNAMIC"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/57d7ad65-1a40-40da-9443-6eafb15b0273/ads
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5d8c331f00ff0a2bc7749e4dbc0001737e616473617069736300016275696c642d35653536303765312d312d3239312d3500010145",
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "1c0deb89-bf95-458f-9c57-32c736046135",
"updated_at": "2019-09-26T03:40:16.264Z",
"created_at": "2019-09-26T03:40:16.264Z",
"name": "DPA Ad",
"ad_squad_id": "57d7ad65-1a40-40da-9443-6eafb15b0273",
"creative_id": "bb0c57ca-8bf2-4f15-8162-704e9c33d88e",
"status": "PAUSED",
"type": "REMOTE_WEBPAGE",
"render_type": "DYNAMIC",
"review_status": "APPROVED"
}
}
]
}
Dynamic Templates
Dynamic Templates allows you to construct your own product template for use with your Dynamic Ads. The Dynamic Template entity is made up of a combination of Overlays and Text Overlays which define what the template will look like when it renders.
Dynamic Template Attributes
Name | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
name | Template Name | R | Max length 375 characters |
ios_url | The URL which will render the Ad | R | https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html |
android_url | The URL which will render the Ad | R | https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html |
layout | Layout of the template | R | AUTOMATIC, FILL_WIDTH, FILL_HEIGHT, FIT, HEADER, TILT, CAROUSEL*, SLIDESHOW* |
text_fields | Text field out of Catalog attributes | R | Array with a maximum of two Text fields from the Catalog attributes |
background_color | Background color of template | O | Represented as three- or six-digit hexadecimal number |
preferred_image_tags | Array of Image tags out of your Product Feed | O | A list of Image tags from your product feed, see section on preferred_image_tags |
overlay_specs | Array of Overlay elements | O | See Overlay table |
* The CAROUSEL and SLIDESHOW layout requires that the Creative is a Collection Ad.
Overlay Attributes
Name | Description | Required | Possible Values |
---|---|---|---|
type | The type of overlay | R | IMAGE, FRAME, TEXT |
media_id | Media ID of an IMAGE/FRAME type overlay | O, R when type is IMAGE/FRAME | Media ID |
text | The text of a TEXT type overlay | O | Max length 34 characters |
position | Position of the overlay | R | BOTTOM_MIDDLE, BOTTOM_LEFT, BOTTOM_RIGHT, CENTER, TOP_MIDDLE, TOP_LEFT, TOP_RIGHT, must be CENTER if type is FRAME |
opacity | Opacity of the overlay | O | Integer, between 75-100 |
text_overlay_properties | Text Overlay | O | See Text Overlay table |
Text Overlay Attributes
Name | Description | Required | Possible Values |
---|---|---|---|
shape | Background shape of text overlay, NONE means no shape underneath text | R | NONE, CIRCLE, PILL, RECTANGLE |
shape_color | Color of background of text overlay | O | Represented as three- or six-digit hexadecimal number |
text_color | Color of the text in the text overlay | R | Represented as three- or six-digit hexadecimal number |
Preferred Image Tags
If your product feed includes additional image you have the option of using preferred_image_tags
for your Dynamic Template.
When your Dynamic Template includes the preferred_image_tags
attribute the Template will first attempt to fetch the image url as specified by your product feed and none of the other features within the Dynamic Template will be used. If no corresponding image url can be found in your product feed the Overlay will be used.
Preferred Image Tags Example
Product Feed Column | Value | Description |
---|---|---|
image[0].url | https://www.renderingurl.com?tag=x | url to be rendered when tag[0] is specified |
image[0].tag[0] | x | tag value mapping to image[0] |
image[1].url | https://www.renderingurl.com?tag=y | url to be rendered when tag[1] is specified |
image[1].tag[0] | y | tag value mapping to image[1] |
Given the above Product Feed specification the Dynamic Template can make use of the following preferred_image_tags
attribute:
"preferred_image_tags": [ "x", "y" ]
The behaviour of the Dynamic Template in this scenario would be to first check if there is a corresponding value for the tag x, in this case the url https://www.renderingurl.com?tag=x is available, this would be requested and it would return a rendered image to be used in place of the Overlay.
Assuming there had been no corresponding image url for the listed tags the Dynamic Template would instead have used the Overlay.
Media Requirements
The Media used for IMAGE/FRAME overlays within a Dynamic Template have the following requirements.
File Requirements
Name | Description | File Type | File Dimension | File size |
---|---|---|---|---|
Overlay Frame | Used as frame | JPG or PNG | 1080px * 1920px | maximum 2mb |
Overlay Image | Used as logo | JPG or PNG | 200px * 200px | maximum 2mb |
Media Requirements
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
name | Media name | R | |
type | Media Type | R | IMAGE |
visibility | R | INVISIBLE |
Create Dynamic Template
curl -X POST \
-d '{"dynamic_templates": [{"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2","name": "Test Template III","ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html","android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html","layout": "FILL_WIDTH","text_fields": ["title","price"],"background_color": "FFFF00","overlay_specs": [{"type": "IMAGE","media_id": "e292db69-139f-41fb-b79b-4cb7ab2e9840","position": "BOTTOM_LEFT"},{"type": "FRAME","media_id": "e8aa0151-9a6f-48a0-bcaa-82fc4f714161","position": "CENTER","opacity": "80"},{"type": "TEXT","text": "meow meow","position": "BOTTOM_RIGHT","opacity": "80","text_overlay_properties": {"shape": "CIRCLE","shape_color": "09C","text_color": "4287F5"}},{"type": "TEXT","text": "woof woof","position": "TOP_RIGHT","opacity": "80","text_overlay_properties": {"shape": "PILL","shape_color": "09C","text_color": "000"}}]}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/dynamic_templates
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ee4011200ff030f7b28c958f70001737e616473617069736300016275696c642d32313965343130312d312d3335382d310001010a",
"dynamic_templates": [
{
"sub_request_status": "SUCCESS",
"dynamic_template": {
"id": "a523ad2d-226a-40c1-8645-4420cac49b76",
"updated_at": "2020-06-12T22:26:26.638Z",
"created_at": "2020-06-12T22:26:26.638Z",
"name": "Test Template III",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
"android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
"layout": "FILL_WIDTH",
"text_fields": [
"title",
"price"
],
"background_color": "FFFF00",
"overlay_specs": [
{
"type": "IMAGE",
"media_id": "e292db69-139f-41fb-b79b-4cb7ab2e9840",
"position": "BOTTOM_LEFT"
},
{
"type": "FRAME",
"media_id": "e8aa0151-9a6f-48a0-bcaa-82fc4f714161",
"position": "CENTER",
"opacity": 80
},
{
"type": "TEXT",
"text": "meow meow",
"position": "BOTTOM_RIGHT",
"opacity": 80,
"text_overlay_properties": {
"shape": "CIRCLE",
"shape_color": "09C",
"text_color": "4287F5"
}
},
{
"type": "TEXT",
"text": "woof woof",
"position": "TOP_RIGHT",
"opacity": 80,
"text_overlay_properties": {
"shape": "PILL",
"shape_color": "09C",
"text_color": "000"
}
}
]
}
}
]
}
This request creates a Dynamic Template.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/dynamic_templates
URL Parameters
Parameter | Description |
---|---|
ad_account_id | The ID of the Ad Account where the Dynamic Template will be created |
Update Dynamic Template
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"dynamic_templates": [{"id": "c2987693-f5c3-43b1-90bd-31445493cef1","name": "Grey Seal Template","ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2","ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html","android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html","layout": "FILL_WIDTH","text_fields": ["title","price"],"background_color": "FFFFFF","preferred_image_tags": ["tag1","tag2"],"overlay_specs": [{"type": "IMAGE","media_id": "e292db69-139f-41fb-b79b-4cb7ab2e9840","position": "TOP_LEFT"},{"type": "FRAME","media_id": "e8aa0151-9a6f-48a0-bcaa-82fc4f714161","position": "CENTER","opacity": 75},{"type": "TEXT","text": "Diving Equipment","position": "BOTTOM_RIGHT","opacity": 80,"text_overlay_properties": {"shape": "CIRCLE","shape_color": "09C","text_color": "4287F5"}},{"type": "TEXT","text": "Sliding Attire","position": "BOTTOM_LEFT","opacity": 80,"text_overlay_properties": {"shape": "PILL","shape_color": "09C","text_color": "6342F5"}}]}]}'
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/dynamic_templates
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ee7660600ff0b01c7922c0efc0001737e616473617069736300016275696c642d32313965343130312d312d3335382d310001011e",
"dynamic_templates": [
{
"sub_request_status": "SUCCESS",
"dynamic_template": {
"id": "c2987693-f5c3-43b1-90bd-31445493cef1",
"updated_at": "2020-06-15T12:13:59.179Z",
"created_at": "2020-06-10T15:19:27.803Z",
"name": "Grea Seal Template",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
"android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
"layout": "FIT",
"text_fields": [
"title",
"price"
],
"background_color": "FFFFFF",
"preferred_image_tags": [
"tag1",
"tag2"
],
"overlay_specs": [
{
"type": "IMAGE",
"media_id": "e292db69-139f-41fb-b79b-4cb7ab2e9840",
"position": "TOP_LEFT"
},
{
"type": "FRAME",
"media_id": "e8aa0151-9a6f-48a0-bcaa-82fc4f714161",
"position": "CENTER",
"opacity": 75
},
{
"type": "TEXT",
"text": "Diving Equipment",
"position": "BOTTOM_RIGHT",
"opacity": 80,
"text_overlay_properties": {
"shape": "CIRCLE",
"shape_color": "09C",
"text_color": "4287F5"
}
},
{
"type": "TEXT",
"text": "Sliding Attire",
"position": "BOTTOM_LEFT",
"opacity": 80,
"text_overlay_properties": {
"shape": "PILL",
"shape_color": "09C",
"text_color": "6342F5"
}
}
]
}
}
]
}
This request updates a Dynamic Template.
HTTP Request
PUT https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/dynamic_templates
URL Parameters
Parameter | Description |
---|---|
ad_account_id | The ID of the Ad Account |
Get Dynamic Template by ID
curl "https://adsapi.snapchat.com/v1/dynamic_templates/baf5c1d9-7a86-4453-aba1-b27a9ce8348b" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ee3ec5000ff0553580d379f2c0001737e616473617069736300016275696c642d32313965343130312d312d3335382d3100010133",
"dynamic_templates": [
{
"sub_request_status": "SUCCESS",
"dynamic_template": {
"id": "baf5c1d9-7a86-4453-aba1-b27a9ce8348b",
"updated_at": "2020-06-11T18:07:20.968Z",
"created_at": "2020-06-11T18:07:20.968Z",
"name": "Test Template II",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
"android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
"layout": "FILL_WIDTH",
"text_fields": [
"title",
"price"
],
"background_color": "FFFFFF",
"preferred_image_tags": [
"tag1",
"tag2"
],
"overlay_specs": [
{
"type": "IMAGE",
"media_id": "e292db69-139f-41fb-b79b-4cb7ab2e9840",
"position": "TOP_LEFT"
},
{
"type": "FRAME",
"media_id": "e8aa0151-9a6f-48a0-bcaa-82fc4f714161",
"position": "CENTER",
"opacity": 75
},
{
"type": "TEXT",
"text": "meow meow",
"position": "BOTTOM_RIGHT",
"opacity": 80,
"text_overlay_properties": {
"shape": "CIRCLE",
"shape_color": "09C",
"text_color": "4287F5"
}
},
{
"type": "TEXT",
"text": "woof woof",
"position": "BOTTOM_LEFT",
"opacity": 80,
"text_overlay_properties": {
"shape": "PILL",
"shape_color": "09C",
"text_color": "6342F5"
}
}
]
}
}
]
}
This request gets a Template by it’s template id.
HTTP Request
GET https://adsapi.snapchat.com/v1/dynamic_templates/{dynamic_template_id}
URL Parameters
Parameter | Description |
---|---|
dynamic_template_id | The ID of the Dynamic Template to retrieve |
Get Dynamic Templates by Ad Account ID
curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/dynamic_templates" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ee4060700ff0d381e5ae4f67a0001737e616473617069736300016275696c642d32313965343130312d312d3335382d3100010107",
"paging": {},
"dynamic_templates": [
{
"sub_request_status": "SUCCESS",
"dynamic_template": {
"id": "a523ad2d-226a-40c1-8645-4420cac49b76",
"updated_at": "2020-06-12T22:26:26.638Z",
"created_at": "2020-06-12T22:26:26.638Z",
"name": "Fox Template",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
"android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
"layout": "FILL_WIDTH",
"text_fields": [
"title",
"price"
],
"background_color": "FFFF00",
"overlay_specs": [
{
"type": "IMAGE",
"media_id": "e292db69-139f-41fb-b79b-4cb7ab2e9840",
"position": "BOTTOM_LEFT"
},
{
"type": "FRAME",
"media_id": "e8aa0151-9a6f-48a0-bcaa-82fc4f714161",
"position": "CENTER",
"opacity": 80
},
{
"type": "TEXT",
"text": "meow meow",
"position": "BOTTOM_RIGHT",
"opacity": 80,
"text_overlay_properties": {
"shape": "CIRCLE",
"shape_color": "09C",
"text_color": "4287F5"
}
},
{
"type": "TEXT",
"text": "woof woof",
"position": "TOP_RIGHT",
"opacity": 80,
"text_overlay_properties": {
"shape": "PILL",
"shape_color": "09C",
"text_color": "000"
}
}
]
}
},
{
"sub_request_status": "SUCCESS",
"dynamic_template": {
"id": "baf5c1d9-7a86-4453-aba1-b27a9ce8348b",
"updated_at": "2020-06-11T18:07:20.968Z",
"created_at": "2020-06-11T18:07:20.968Z",
"name": "Honey Bear Template",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
"android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
"layout": "FILL_WIDTH",
"text_fields": [
"title",
"price"
],
"background_color": "FFFFFF",
"preferred_image_tags": [
"tag1",
"tag2"
],
"overlay_specs": [
{
"type": "IMAGE",
"media_id": "e292db69-139f-41fb-b79b-4cb7ab2e9840",
"position": "TOP_LEFT"
},
{
"type": "FRAME",
"media_id": "e8aa0151-9a6f-48a0-bcaa-82fc4f714161",
"position": "CENTER",
"opacity": 75
},
{
"type": "TEXT",
"text": "meow meow",
"position": "BOTTOM_RIGHT",
"opacity": 80,
"text_overlay_properties": {
"shape": "CIRCLE",
"shape_color": "09C",
"text_color": "4287F5"
}
},
{
"type": "TEXT",
"text": "woof woof",
"position": "BOTTOM_LEFT",
"opacity": 80,
"text_overlay_properties": {
"shape": "PILL",
"shape_color": "09C",
"text_color": "6342F5"
}
}
]
}
}
]
}
This request gets all Dynamic Templates under an Ad Account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/dynamic_templates
URL Parameters
Parameter | Description |
---|---|
ad_account_id | The ID of the Ad Account |
Reporting
All standard reporting metrics and granularities are supported for DPA. Please refer to the DPA reporting section for more details
Dynamic Collections Ads Guide
Collection ads can be used to market products dynamically, these Ads can either be made fully Dynamic or partly Dynamic.
- A fully dynamic Collection ad selects both the top snap and the creative elements dynamically based on the associated Product Set.
- A partly dynamic Collection ad will have a static Top Snap Media (Video/Image), only the creative elements will be dynamically picked based on the associated product set.
Both variants of the Dynamic Collection Ad need an Interaction zone with 2-4 Creative Elements, the Creative Elements will dynamically select Products out of an associated Product Set.
Assuming you have an existing Product feed and Product set, the order of creation from the bottom of the hierarchy is:
- Creative Elements
- Interaction Zone
- Creative
- Ad Squad
- Ad entity
Product feed - Interaction support
Before setting up the Creative Elements you should ensure the chosen interaction is supported by the product feed and product set you intend to use. The Product Search method along with the parameter ELIGIBLE_AD_TYPE can be used to evaluate this. Refer to Product Search
The three Ad formats supported by product search and ELIGIBLE_AD_TYPE are APP_INSTALL, DEEP_LINK_ATTACHMENT and REMOTE_WEBPAGE.
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"filter":{"AND":[{"ELIGIBLE_AD_TYPE":{"EQ":"DEEP_LINK_ATTACHMENT"}},{"PRODUCT_SET_ID":{"EQ":"8dc5f3ff-ab02-460b-bbbd-1ade8bb3da38"}},{"OR":[{"AVAILABILITY":{"EQ":"IN_STOCK"}},{"AVAILABILITY":{"EQ":"PREORDER"}},{"AVAILABILITY":{"EQ":"AVAILABLE_FOR_ORDER"}}]}]}}'
https://adsapi.snapchat.com/v1/catalogs/82225ba6-7559-4000-9663-bace8adff5f8/product_search?limit=0
{
"request_status": "SUCCESS",
"request_id": "5ff70e2b00ff08056236e672d10001737e616473617069736300016275696c642d33343532666138312d312d3431312d300001013d",
"summary": {
"total_products": {
"count": "47",
"relation": "EQ"
}
},
"paging": {},
"products": [
{ ...}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/product_search?limit=0
Creative Elements
The Creative element is a holder for the Product Feed images which will be picked dynamically from the Product set defined in dynamic_render_properties.product_set_id at the Creative level.
The Creative Element also specifies the interaction triggered when the user taps the Element (webview/app install/deep link) via the attribute interaction_type.
Once the Creative Element entity has been created it cannot be updated.
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"creative_elements":[{"name":"Product tile 1","type":"BUTTON","interaction_type":"WEB_VIEW","render_type":"DYNAMIC"},{"name":"Product tile 2","type":"BUTTON","interaction_type":"WEB_VIEW","render_type":"DYNAMIC"},{"name":"Product tile 3","type":"BUTTON","interaction_type":"WEB_VIEW","render_type":"DYNAMIC"}]}'
https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f8/creative_elements
{
"request_status": "SUCCESS",
"request_id": "5fda1dd300ff0d787cd06ea62b0001737e616473617069736300016275696c642d66306132623635382d312d3430392d3200010160",
"creative_elements": [
{
"sub_request_status": "SUCCESS",
"creative_element": {
"id": "5bc30331-9428-46a6-8d4c-5093124c6d03",
"updated_at": "2020-12-16T14:46:44.152Z",
"created_at": "2020-12-16T14:46:44.152Z",
"name": "Product tile 1",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f8",
"type": "BUTTON",
"interaction_type": "WEB_VIEW",
"render_type": "DYNAMIC"
}
},
{
"sub_request_status": "SUCCESS",
"creative_element": {
"id": "83d7b96d-bdb1-4e46-83b2-1a6d61a36b56",
"updated_at": "2020-12-16T14:46:44.454Z",
"created_at": "2020-12-16T14:46:44.454Z",
"name": "Product tile 2",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f8",
"type": "BUTTON",
"interaction_type": "WEB_VIEW",
"render_type": "DYNAMIC"
}
},
{
"sub_request_status": "SUCCESS",
"creative_element": {
"id": "578e3f05-a87d-4af5-a389-55c086277dad",
"updated_at": "2020-12-16T14:46:44.727Z",
"created_at": "2020-12-16T14:46:44.727Z",
"name": "Product tile 3",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f8",
"type": "BUTTON",
"interaction_type": "WEB_VIEW",
"render_type": "DYNAMIC"
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creative_elements
Creative Elements Parameters
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | Creative Element name | R | |
type | R | BUTTON | |
title | Creative Element title | O | |
description | Creative Element description | O | |
interaction_type | Defines the behaviour of the Creative Elements | R | WEB_VIEW, APP_INSTALL, DEEP_LINK |
render_type | R | DYNAMIC |
Interaction Zones
The Interaction zone is mainly a holder where the Dynamic Creative Elements will be shown, it also holds the call to action for the Snap Ad under the attribute headline. The 2-4 Creative Elements that are added to the Interaction Zone should have the same interaction_type.
Once created the Interaction Zone entity cannot be updated.
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"interaction_zones":[{"name":"The Badger Shop Interaction Zone","render_type":"DYNAMIC","creative_element_ids":["5bc30331-9428-46a6-8d4c-5093124c6d03","83d7b96d-bdb1-4e46-83b2-1a6d61a36b56","578e3f05-a87d-4af5-a389-55c086277dad"],"headline":"MORE"}]}'
https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f8/interaction_zones
{
"request_status": "SUCCESS",
"request_id": "5fda1f3300ff0c89632e43f2c20001737e616473617069736300016275696c642d66306132623635382d312d3430392d3200010128",
"interaction_zones": [
{
"sub_request_status": "SUCCESS",
"interaction_zone": {
"id": "51d12f07-8690-4a41-b201-6a99335bbaa2",
"updated_at": "2020-12-16T14:52:36.057Z",
"created_at": "2020-12-16T14:52:36.057Z",
"name": "The Badger Shop Interaction Zone",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f8",
"headline": "MORE",
"creative_element_ids": [
"5bc30331-9428-46a6-8d4c-5093124c6d03",
"83d7b96d-bdb1-4e46-83b2-1a6d61a36b56",
"578e3f05-a87d-4af5-a389-55c086277dad"
],
"render_type": "DYNAMIC"
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/interaction_zones
Interaction Zones Parameters
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | Interaction Zone name | R | |
render_type | R | DYNAMIC | |
creative_elements | An array of 2-4 Creative Element ids, these elements should be of the same interaction_type | R | |
headline | This is used as the CTA for the Collection Ad | R | APPLY_NOW, BOOK_NOW, BUY_TICKETS, DONATE, DOWNLOAD, GET_NOW, INSTALL_NOW, LISTEN, MORE, OPEN_APP, ORDER_NOW, PLAY, READ, RESPOND, SHOP_NOW, SHOW, SHOWTIMES, SIGN_UP, TRY, USE_APP, VIEW, WATCH |
Fully Dynamic Collection Ad Creative
The Top Snap media will be a product picked dynamically based on the Product Catalog (product_set) like in an ordinary Dynamic Product Ad.
The 2-4 Creative Elements displayed at the bottom of the Top Snap are inserted via the Interaction Zone and picked dynamically based on the Product Catalog (product_set).
The collection_properties.default_fallback_interaction_type should match the interaction_type of the Creative Elements used in the Interaction Zone.
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"creatives":[{"ad_account_id":"82225ba6-7559-4000-9663-bace8adff5f8","name":"Dynamic Collection Ad with Dynamic Top Snap","type":"COLLECTION","headline":"Badger Supplies","brand_name":"Badger Tunneling","shareable":true,"render_type":"DYNAMIC","dynamic_render_properties":{"dynamic_template_id":"013cb00d-7b8a-467a-a6be-614c269dafe2","product_set_id":"b6d35541-d5b6-4e06-a400-03f9937392cc"},"collection_properties":{"interaction_zone_id":"51d12f07-8690-4a41-b201-6a99335bbaa2","default_fallback_interaction_type":"WEB_VIEW"}}]}'
https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f8/creatives
{
"request_status": "SUCCESS",
"request_id": "5fda234d00ff02f5557aba61770001737e616473617069736300016275696c642d66306132623635382d312d3430392d3200010123",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "de8a165e-f031-4a94-a56b-d0b5b4e1c20f",
"updated_at": "2020-12-16T15:10:05.566Z",
"created_at": "2020-12-16T15:10:05.566Z",
"name": "Dynamic Collection Ad with Dynamic Top Snap",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f8",
"type": "COLLECTION",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Badger Supplies",
"brand_name": "Badger Tunneling",
"render_type": "DYNAMIC",
"dynamic_render_properties": {
"dynamic_template_id": "013cb00d-7b8a-467a-a6be-614c269dafe2",
"product_set_id": "b6d35541-d5b6-4e06-a400-03f9937392cc"
},
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"collection_properties": {
"interaction_zone_id": "51d12f07-8690-4a41-b201-6a99335bbaa2",
"default_fallback_interaction_type": "WEB_VIEW"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Creative - Collection Creative with Dynamic Top Snap - Parameters
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
name | Creative name | R | |
type | Creative type | R | COLLECTION |
headline | 34 characters max | R | |
brand_name | 25 characters max | R | |
shareable | Allow Users to Share with Friends | O | true (default), false |
render_type | DYNAMIC | R | |
dynamic_render_properties.dynamic_template_id | Dynamic Template ID | R | |
dynamic_render_properties.product_set_id | Product Set ID used for Products | R | |
collection_properties.interaction_zone_id | Interaction Zone ID | R | |
collection_properties.default_fallback_interaction_type | Defines Interaction behaviour for the Creative | R | WEB_VIEW, APP_INSTALL, DEEP_LINK |
Partly Dynamic Collection Ad
The Top Snap media is uploaded as a separate Media (image/video) and has its own set of attributes at the Creative level (WEB_VIEW, APP_INSTALL, DEEP_LINK), this attribute should match the interaction_type of the Creative Elements.
The 3-4 Creative Elements displayed at the bottom of the Top Snap are inserted via the Interaction Zone and picked dynamically based on the Product Catalog (product_set).
The collection_properties.default_fallback_interaction_type should match the interaction_type of the Creative Elements used in the Interaction Zone.
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"creatives":[{"ad_account_id":"82225ba6-7559-4000-9663-bace8adff5f8","name":"Dynamic Collection Ad with Static Top Snap","type":"COLLECTION","headline":"Badger Supplies","brand_name":"Badger Tunneling","shareable":true,"render_type":"STATIC","top_snap_media_id":"e02308fd-ab84-4b6e-8c71-4fe1fc2f1ae2","dynamic_render_properties":{"product_set_id":"b6d35541-d5b6-4e06-a400-03f9937392cc"},"collection_properties":{"interaction_zone_id":"51d12f07-8690-4a41-b201-6a99335bbaa2","default_fallback_interaction_type":"WEB_VIEW","web_view_properties":{"url":"https://www.example.com/bookingfolder/linkedpage.html","allow_snap_javascript_sdk":false,"use_immersive_mode":false,"deep_link_urls":[],"block_preload":false}}}]}'
https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f8/creatives
{
"request_status": "SUCCESS",
"request_id": "5fda252200ff00ff08972bb0da7a0001737e616473617069736300016275696c642d66306132623635382d312d3430392d3200010119",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "8eec06bd-d3fd-4841-b330-d04b82dfd862",
"updated_at": "2020-12-16T15:17:54.396Z",
"created_at": "2020-12-16T15:17:54.396Z",
"name": "Dynamic Collection Ad with Static Top Snap",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f8",
"type": "COLLECTION",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Badger Supplies",
"brand_name": "Badger Tunneling",
"render_type": "STATIC",
"top_snap_media_id": "e02308fd-ab84-4b6e-8c71-4fe1fc2f1ae2",
"dynamic_render_properties": {
"product_set_id": "b6d35541-d5b6-4e06-a400-03f9937392cc"
},
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"collection_properties": {
"interaction_zone_id": "51d12f07-8690-4a41-b201-6a99335bbaa2",
"default_fallback_interaction_type": "WEB_VIEW",
"web_view_properties": {
"url": "https://www.example.com/bookingfolder/linkedpage.html",
"allow_snap_javascript_sdk": false,
"use_immersive_mode": false,
"deep_link_urls": [],
"block_preload": false
}
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Creative - Collection Creative with uploaded Top Snap - Parameters
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
name | Creative name | R | |
type | Creative type | R | COLLECTION |
headline | 34 characters max | R | |
brand_name | 25 characters max | R | |
shareable | Allow Users to Share with Friends | O | true (default), false |
render_type | R | STATIC | |
top_snap_media_id | Media ID of Top Snap, the Media type can be either VIDEO or IMAGE | R | |
dynamic_render_properties.product_set_id | Product Set id | R | |
collection_properties.interaction_zone_id | Interaction Zone id | R | |
collection_properties.default_fallback_interaction_type | Defines Interaction behaviour for the Creative | R | WEB_VIEW, APP_INSTALL, DEEP_LINK |
For a partly dynamic Collection Ad you need to specify the properties for the top snap, these properties are defined within the JSON of the collection_properties and
Webview attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
collection_properties.web_view_properties.url | Web view URL | R | |
collection_properties.web_view_properties.allow_snap_javascript_sdk | O | true, false (default) | |
collection_properties.web_view_properties.use_immersive_mode | O | true, false (default) | |
collection_properties.web_view_properties.block_preload | Block Snapchat from preloading the web page | O | true, false (default) |
App Install attributes
Attribute | Description | Required |
---|---|---|
collection_properties.app_install_properties.app_name | App name | R |
collection_properties.app_install_properties.ios_app_id | iOS App ID | R |
collection_properties.app_install_properties.android_app_url | Google Play Store ID | R |
collection_properties.app_install_properties.icon_media_id | Icon Media ID | R |
collection_properties.app_install_properties.product_page_id | iOS App Store Custom Product Page ID | O |
Deep Link attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
collection_properties.deep_link_properties.deep_link_uri | Deep link URL for App | R | |
collection_properties.deep_link_properties.app_name | App name | R | |
collection_properties.deep_link_properties.ios_app_id | iOS App ID | R | |
collection_properties.deep_link_properties.android_app_url | Google Play Store ID | R | |
collection_properties.deep_link_properties.icon_media_id | Icon Media ID | R | |
collection_properties.deep_link_properties.fallback_type | Behaviour for user that doesn’t have app installed | R | APP_INSTALL, WEB_SITE |
collection_properties.deep_link_properties.web_view_fallback_url | Required if fallback_type is WEB_SITE | R | |
collection_properties.deep_link_properties.deep_link_uri | Deep link URL for App | R | |
collection_properties.deep_link_properties.product_page_id | iOS App Store Custom Product Page ID | O |
Ad Squad
The Ad Squad follows the exact requirements of an Ad Squad used for Dynamic Product Ads, there are no additional parameters for using Dynamic Collection Ads. Refer Create Ad Squad
Ad
The Ad entity links the Creative and the Ad Squad together, the type and render_type needs to use the below specified values, the only attribute that differs from Dynamic Product Ads is the type attribute which needs to be set to the value COLLECTION.
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"ads":[{"id":"6fca9a40-08e9-44e4-8ac2-de40d604af1f","name":"Dynamic Collection Ad with Dynamic Top Snap","ad_squad_id":"ea47539a-dd29-4957-b24c-2624957fa7e7","creative_id":"de8a165e-f031-4a94-a56b-d0b5b4e1c20f","status":"ACTIVE","type":"COLLECTION","render_type":"DYNAMIC"}]}'
https://adsapi.snapchat.com/v1/adsquads/ea47539a-dd29-4957-b24c-2624957fa7e7/ads
{
"request_status": "SUCCESS",
"request_id": "5fda26e300ff0eeb712b8d14d80001737e616473617069736300016275696c642d66306132623635382d312d3430392d3200010160",
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "e88eb5f7-d4da-4c8e-b1c8-d98f81ae3801",
"updated_at": "2020-12-16T15:25:25.109Z",
"created_at": "2020-12-16T15:25:25.109Z",
"name": "Dynamic Collection Ad with Dynamic Top Snap",
"ad_squad_id": "ea47539a-dd29-4957-b24c-2624957fa7e7",
"creative_id": "de8a165e-f031-4a94-a56b-d0b5b4e1c20f",
"status": "ACTIVE",
"type": "COLLECTION",
"render_type": "DYNAMIC",
"review_status": "PENDING",
"review_status_reasons": [],
"delivery_status": [
"INVALID_EFFECTIVE_INVALID",
"INVALID_PENDING_REVIEW_STATUS"
]
}
}
]
}
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | Ad name | R | |
ad_squad_id | Ad squad ID | R | |
creative_id | Creative ID | R | |
status | Ad status | R | ACTIVE, PAUSED |
type | Ad type | R | COLLECTION |
render_type | Rendering type | R | DYNAMIC |
Please refer to the FAQ section for FAQs on Dynamic Collection Ads
Carousel and Slideshow Templates
The Dynamic Collection Ad supports two different Creative experiences via Dynamic Templates, these experiences are activated by specifying CAROUSEL or SLIDESHOW as the layout
type.
layout | Description |
---|---|
CAROUSEL | Product images are displayed as thumbnails and rotated in a main image slot |
SLIDESHOW | Product images are rotated in a main image slot |
Example 1 - Create a CAROUSEL Dynamic Template
curl -X POST \
-d '{"dynamic_templates": [{"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2","name": "Dynamic Collection Carousel Template","ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html","android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html","layout": "CAROUSEL","text_fields": ["title","price"]}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/dynamic_templates
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ee4011200ff030f7b28c958f70001737e616473617069736300016275696c642d32313965343130312d312d3335382d310001010a",
"dynamic_templates": [
{
"sub_request_status": "SUCCESS",
"dynamic_template": {
"id": "a523ad2d-226a-40c1-8645-4420cac49b76",
"updated_at": "2020-06-12T22:26:26.638Z",
"created_at": "2020-06-12T22:26:26.638Z",
"name": "Dynamic Collection Carousel Template",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
"android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
"layout": "CAROUSEL",
"text_fields": [
"title",
"price"
]
}
}
]
}
This request creates a Dynamic Template for a Dynamic Collection Ad using the CAROUSEL layout.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/dynamic_templates
URL Parameters
Parameter | Description |
---|---|
ad_account_id | The ID of the Ad Account where the Dynamic Template will be created |
Example 2 - Create a SLIDESHOW Dynamic Template
curl -X POST \
-d '{"dynamic_templates": [{"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2","name": "Dynamic Collection Carousel Template","ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html","android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html","layout": "SLIDESHOW","text_fields": ["title","price"]}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/dynamic_templates
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ee4011200ff030f7b28c958f70001737e616473617069736300016275696c642d32313965343130312d312d3335382d310001010a",
"dynamic_templates": [
{
"sub_request_status": "SUCCESS",
"dynamic_template": {
"id": "a523ad2d-226a-40c1-8645-4420cac49b76",
"updated_at": "2020-06-12T22:26:26.638Z",
"created_at": "2020-06-12T22:26:26.638Z",
"name": "Dynamic Collection Carousel Template",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
"android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
"layout": "SLIDESHOW",
"text_fields": [
"title",
"price"
]
}
}
]
}
This request creates a Dynamic Template for a Dynamic Collection Ad using the CAROUSEL layout.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/dynamic_templates
URL Parameters
Parameter | Description |
---|---|
ad_account_id | The ID of the Ad Account where the Dynamic Template will be created |
Showcase Experience
The Showcase Experience for DPA collection Ads is a new format which delivers a native commerce experience on Snapchat. It allows users to swipe up to a collection of products, rendered natively, for a seamless, delightful shopping experience.
The setup for the Showcase Experience is identical to the DPA collection ads setup with creative elements, interaction zones, ad squads and ad objects. The primary difference is in the setup of the creative object.
Showcase Creative
The showcase creative is a creative of type COLLECTION and render_type DYNAMIC. It contains a new property within collection_properties called showcase_properties.
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{
"creatives": [
{
"ad_account_id": "497979f0-ed17-4971-8288-0548abcdcbca",
"name": "Dynamic Collection Ad with Dynamic Top Snap for showcase API",
"type": "COLLECTION",
"headline": "Badger Supplies",
"brand_name": "Badger Tunneling",
"shareable": true,
"render_type": "DYNAMIC",
"dynamic_render_properties":
{
"dynamic_template_id": "186491f9-abcd-4322-9bf5-42bc0b2a79b8",
"product_set_id": "0ae60e22-5764-abcd-88ad-5f77f8f286dd"
},
"collection_properties":
{
"interaction_zone_id": "618ef9f7-abcd-abcd-abcd-9b2eda44eb04",
"default_fallback_interaction_type": "SHOWCASE",
"showcase_properties": {
"product_set_id": "0ae60e22-abcd-abcd-88ad-5f77f8f286dd",
"interaction_type": "WEB_VIEW",
"callout_text": "20% off",
"web_view_properties": {
"url": "http://www.bananas.com"
}
}
}
}]
}'
https://adsapi.snapchat.com/v1/adaccounts/497979f0-ed17-4971-8278-054883f1cbca/creatives
{
"request_status": "SUCCESS",
"request_id": "60bff16b00ff09d211e5b48ed40001737e616473617069736300016275696c642d63313332343265352d312d3435332d3000010155",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative":
{
"id": "5970d72e-abcd-abcd-90f8-496f6091bb3b",
"updated_at": "2021-06-08T22:38:35.974Z",
"created_at": "2021-06-08T22:38:35.974Z",
"created_by_app_id": "faaabe40-abcd-abcd-abcd-b88f802dc3d2",
"created_by_user": "9b50736f-abcd-abcd-abcd-21f99554aa31",
"last_updated_by_app_id": "faaabe40-abcd-abcd-837d-b88f802dc3d2",
"last_updated_by_user": "9b50736f-abcd-abcd-abcd-21f99554aa31",
"name": "Dynamic Collection Ad with Dynamic Top Snap for showcase API",
"ad_account_id": "497979f0-abcd-abcd-abcd-054883f1cbca",
"type": "COLLECTION",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Badger Supplies",
"brand_name": "Badger Tunneling",
"render_type": "DYNAMIC",
"dynamic_render_properties":
{
"dynamic_template_id": "186491f9-abcd-abcd-abcd-42bc0b2a79b8",
"product_set_id": "0ae60e22-abcd-abcd-abcd-5f77f8f286dd"
},
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"collection_properties":
{
"interaction_zone_id": "618ef9f7-abcd-abcd-abcd-9b2eda44eb04",
"default_fallback_interaction_type": "SHOWCASE",
"showcase_properties":
{
"product_set_id": "0ae60e22-abcd-abcd-abcd-5f77f8f286dd",
"interaction_type": "WEB_VIEW",
"callout_text": "20% off",
"web_view_properties":
{
"url": "http://www.baanas.com",
"allow_snap_javascript_sdk": false,
"use_immersive_mode": false,
"deep_link_urls": [],
"block_preload": false
}
}
}
}
}]
}
Property Name | Required | Description | Possible Values |
---|---|---|---|
product_set_id | R | The product set ID to be associated to generate the Showcase unit | Product set ID eg: 0ae60e22-5764-4d34-88ad-5f77f8f286ad |
interaction_type | R | WEB_VIEW, DEEP_LINK | |
callout_text | O | Text shown in the banner at the top of the Showcase experience Max length: 30 | |
web_view_properties | Required when interaction_type is web_view | Defines the url for “Shop Now” button Required when interaction_type == WEB_VIEW. Only url in web_view_properties can be used | refer to web_view_properties table |
deep_link_properties | Required when interaction_type is deep_link | Defines the url for “Shop Now” button Required when interaction_type == DEEP_LINK. Only deeplinkUri, iosAppId, AndroidAppUrl and webViewFallbackUrl in deep_link_properties can be used. FallbackType must be WEB_SITE | refer to deep_link_properties table |
Validations
Some important validations to take note of.
- showcase_properties cannot be null
- For Web_view and Deep_link interaction types, the corresponding web_view and deep_link Properties are required
- The interaction_type in the creativeElement should match the interaction_type in showcase_properties
- The product set ID must be the same in ad squad and the creative
- Ad Squad type must be SNAP_ADS
- The ad squad targeting must be set to US only
- The ad squad optimization goal can be one of the following - IMPRESSIONS || SWIPES || VIDEO_VIEWS || VIDEO_VIEWS_15_SEC || PIXEL_PURCHASE || PIXEL_SIGNUP || PIXEL_PAGE_VIEW || PIXEL_ADD_TO_CART
- The Ad Squad Billing Event must be IMPRESSIONS
Dynamic Story Ads Guide
Story Ads are a Dynamic Ad format that allows advertisers to dynamically display a series of 3-10 product ads pulled directly from a Catalog.
This opens an opportunity to leverage Dynamic Ads campaigns within another placement across Snapchat, within our Discover tab where the Dynamic Story Ad will display.
Dynamic Story Ads are available for Website and Deep Link campaigns with both prospecting and retargeting audience targeting, and available for App Install campaigns with prospecting audience targeting.
Dynamic Story Ads currently has four possible variants.
- A non-dynamic Preview Creative, a non-dynamic Creative and ten Dynamic Ads that make up the story
- A non-dynamic Preview Creative and a set of ten Dynamic Ads that make up the story
- A dynamic Preview Creative, a non-dynamic Creative and ten Dynamic Ads that make up the story
- A dynamic Preview Creative and a set of ten Dynamic Ads that make up the story
Assuming you have an existing Product feed and Product set, the order of creation from the the top of the hierarchy is the following;
- Preview Creative
- Static Creative (Optional)
- 10x Dynamic Creatives
- Composite Creative
- Ad Squad (including product_audiences)
- Ad (Story type)
Product Feed - Interaction support
Before setting up the Creative Elements you should ensure the chosen interaction is supported by the product feed and product set you intend to use. The Product Search method along with the parameter ELIGIBLE_AD_TYPE can be used to evaluate this. Refer to Product Search
The three Ad formats supported by product search and ELIGIBLE_AD_TYPE are APP_INSTALL, DEEP_LINK_ATTACHMENT and REMOTE_WEBPAGE.
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"filter":{"AND":[{"ELIGIBLE_AD_TYPE":{"EQ":"DEEP_LINK_ATTACHMENT"}},{"PRODUCT_SET_ID":{"EQ":"8dc5f3ff-ab02-460b-bbbd-1ade8bb3da38"}},{"OR":[{"AVAILABILITY":{"EQ":"IN_STOCK"}},{"AVAILABILITY":{"EQ":"PREORDER"}},{"AVAILABILITY":{"EQ":"AVAILABLE_FOR_ORDER"}}]}]}}'
https://adsapi.snapchat.com/v1/catalogs/82225ba6-7559-4000-9663-bace8adff5f8/product_search?limit=0
{
"request_status": "SUCCESS",
"request_id": "5ff70e2b00ff08056236e672d10001737e616473617069736300016275696c642d33343532666138312d312d3431312d300001013d",
"summary": {
"total_products": {
"count": "47",
"relation": "EQ"
}
},
"paging": {},
"products": [
{ ...}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/product_search?limit=0
Preview Creative
This Creative constitutes the tile that is used in the discover feed, it consists of the tile itself and a logo on top of the tile. The tile can either be a non-dynamic image, or the image can be fetched dynamically from a Product Set.
When the preview creative is non-dynamic it uses two Media entities of the type IMAGE
preview_media_id
- The id of the Preview Media image used in the Discover Feed tab of Snapchatlogo_media_id
- The id of the Logo Media Image which is overlaid on top of the Preview Media
The Preview Media ID and Logo Media ID are defined in the preview_properties
of this Creative, the preview_properties
also contains a headline which can hold up to 55 characters and allows for the use of emoji Unicode characters.
When the preview creative is dynamic it needs to have the attribute dynamic_render_properties
which specifies the product_set_id
to be used, and the dynamic_template
formulated on the Composite Creative.
Preview Media
This is a MEDIA creation request, the image dimension and size should be 360px x 600px PNG format, 2 MB maximum, detailed Media spec.
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | Media name | R | |
type | Media Type | R | IMAGE |
ad_account_id | Ad Account ID | R |
Logo Media
This is a normal MEDIA creation request, the image dimension and size should be 993px x 284px PNG format on transparent background, 2 MB maximum, detailed Media spec.
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | Media name | R | |
type | Media Type | R | IMAGE |
ad_account_id | Ad Account ID | R |
Example 1 - Preview Creative that uses a preview_media_id (IMAGE)
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"creatives":[{"name":"Preview Creative - STATIC - Badger Story Ad","ad_account_id":"82225ba6-7559-4000-9663-bace8adff5f2","type":"PREVIEW","shareable":true,"render_type":"STATIC","preview_properties":{"preview_media_id":"6774e417-c3b8-4bd5-9573-aee33658e7d8","logo_media_id":"16ddfd33-0e87-484b-9b6c-47d07724df78","preview_headline":"The latest Tunneling Gear 🛠"}}]}'
https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/creatives
{
"request_status": "SUCCESS",
"request_id": "60d34e6200ff0101c629819b530001737e616473617069736300016275696c642d63616365343036622d312d3435362d3200010149",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "5a63e6bd-6641-4d43-b4f8-484518f6d0e8",
"updated_at": "2021-06-23T15:08:20.170Z",
"created_at": "2021-06-23T15:08:20.170Z",
"name": "Preview Creative - STATIC - Badger Story Ad",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"type": "PREVIEW",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"render_type": "STATIC",
"top_snap_crop_position": "MIDDLE",
"preview_properties": {
"preview_media_id": "6774e417-c3b8-4bd5-9573-aee33658e7d8",
"logo_media_id": "16ddfd33-0e87-484b-9b6c-47d07724df78",
"preview_headline": "The latest Tunneling Gear 🛠"
},
"ad_product": "SNAP_AD"
}
}
]
}
Example 2 - Preview Creative that uses a Dynamically picked image from a Product Set ID
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"creatives":[{"name":"Preview Creative - DYNAMIC - Badger Story Ad","ad_account_id":"22225ba6-7559-4000-9663-bace8adff5f2","type":"PREVIEW","shareable":true,"render_type":"DYNAMIC","top_snap_crop_position":"MIDDLE","dynamic_render_properties":{"dynamic_template_id":"c2987693-f5c3-43b1-90bd-31445493cef1","product_set_id":"b6d35541-d5b6-4e06-a400-03f9937392cc"},"preview_properties":{"logo_media_id":"16ddfd33-0e87-484b-9b6c-47d07724df70","preview_headline":"The latest Tunneling Gear 🛠"}}]}'
https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/creatives
{
"request_status": "SUCCESS",
"request_id": "611fe31700ff0e87127c39c75e0001737e616473617069736300016275696c642d39323666386331392d312d3437322d3000010108",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "3cb19304-4df3-446e-ac9d-b415b116e136",
"updated_at": "2021-08-20T17:15:04.368Z",
"created_at": "2021-08-20T17:15:04.368Z",
"name": "Preview Creative - DYNAMIC - Badger Story Ad",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2",
"type": "PREVIEW",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"render_type": "DYNAMIC",
"dynamic_render_properties": {
"dynamic_template_id": "c2987693-f5c3-43b1-90bd-31445493cef1",
"product_set_id": "b6d35541-d5b6-4e06-a400-03f9937392cc"
},
"top_snap_crop_position": "MIDDLE",
"preview_properties": {
"logo_media_id": "16ddfd33-0e87-484b-9b6c-47d07724df70",
"preview_headline": "The latest Tunneling Gear 🛠"
},
"ad_product": "SNAP_AD"
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/{ad_account_id}/creatives
Preview Creative Parameters
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | Creative name | R | |
ad_account_id | Ad Account ID | R | |
type | Creative type | R | PREVIEW |
shareable | Allows sharing of the Story Ad on iOS, Android sharing is currently not available | O | true (default), false |
render_type | R | STATIC, DYNAMIC | |
preview_properties.preview_media_id | Preview Media ID, required when render_type is STATIC |
O | |
preview_properties.logo_media_id | Logo Media ID | R | |
preview_properties.preview_headline | 55 Character limit, emoji unicode characters allowed | R | |
dynamic_render_properties.dynamic_template_id | Must match Dynamic Template ID set on the Composite creative, required when render_type is DYNAMIC |
O | |
dynamic_render_properties.product_set_id | Must match Product Set ID set at Ad Squad level, required when render_type is DYNAMIC |
O |
Dynamic Creatives
When creating a Dynamic Story Ad you will need 10 x Dynamic Creatives, these Dynamic Creatives need to be of the same Creative type (WEB_VIEW, APP_INSTALL, DEEP_LINK). It’s not possible to mix different Creative types within one Dynamic Story Ad.
The Dynamic Creatives follows the creation outlined here, the Dynamic Creatives will be listed in within an array of the Composite creative, even though a Dynamic Story Ad requires 10x Dynamic Creatives, at the point of serving 3-10 of these Creatives will be used to pull in Products from the Product feed.
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"creatives":[{"ad_account_id":"82225ba6-7559-4000-9663-bace8adff5f2","name":"DPA Story Ad Position 1","type":"WEB_VIEW","headline":"Tunneling Tools","brand_name":"Badger Tunneling","shareable":true,"call_to_action":"SHOP_NOW","render_type":"DYNAMIC","dynamic_render_properties":{"dynamic_template_id":"09d8d60b-1d05-423a-8d52-c2f52cf2c7dc","product_set_id":"10e7d339-0ff1-434a-996a-94d34918c948"}},{"name":"DPA Story Ad Position 2","ad_account_id":"82225ba6-7559-4000-9663-bace8adff5f2","type":"WEB_VIEW","shareable":true,"headline":"Tunneling Tools","brand_name":"Badger Tunneling","call_to_action":"SHOP_NOW","render_type":"DYNAMIC","dynamic_render_properties":{"dynamic_template_id":"09d8d60b-1d05-423a-8d52-c2f52cf2c7dc","product_set_id":"10e7d339-0ff1-434a-996a-94d34918c948"}}]}'
https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/creatives
{
"request_status": "SUCCESS",
"request_id": "60d4737600ff00ffde2766270dc80001737e616473617069736300016275696c642d63616365343036622d312d3435362d320001011d",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "885b4c1d-b496-40b9-9543-bd75bf1af010",
"updated_at": "2021-06-24T11:58:46.929Z",
"created_at": "2021-06-24T11:58:46.929Z",
"name": "DPA Story Ad Position 1",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"type": "WEB_VIEW",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Tunneling Tools",
"brand_name": "Badger Tunneling",
"call_to_action": "SHOP_NOW",
"render_type": "DYNAMIC",
"dynamic_render_properties": {
"dynamic_template_id": "09d8d60b-1d05-423a-8d52-c2f52cf2c7dc",
"product_set_id": "10e7d339-0ff1-434a-996a-94d34918c948"
},
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD"
}
},
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "0ed1c7b0-4bfc-49cd-8037-0e20174ae51a",
"updated_at": "2021-06-24T11:58:49.364Z",
"created_at": "2021-06-24T11:58:49.364Z",
"name": "DPA Story Ad Position 2",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"type": "WEB_VIEW",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Tunneling Tools",
"brand_name": "Badger Tunneling",
"call_to_action": "SHOP_NOW",
"render_type": "DYNAMIC",
"dynamic_render_properties": {
"dynamic_template_id": "09d8d60b-1d05-423a-8d52-c2f52cf2c7dc",
"product_set_id": "10e7d339-0ff1-434a-996a-94d34918c948"
},
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD"
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/{ad_account_id}/creatives
Dynamic Creative Parameters
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | Creative Name | R | |
ad_account_id | Ad Account ID | R | |
type | Requires corresponding attribute in the product feed | R | WEB_VIEW, APP_INSTALL, DEEP_LINK |
headline | Max 34 characters with spaces | R | |
brand_name | Max 25 characters with spaces | R | |
shareable | O | true (default), false | |
call_to_action | As per the Creative type and Call to action mapping | R | |
render_type | R | DYNAMIC | |
dynamic_render_properties.dynamic_template_id | Must match Dynamic Template ID set on Composite creative | R | |
dynamic_render_properties.product_set_id | Must match Product Set ID set at Ad Squad level | R |
Non-Dynamic Creative Parameters
When creating a Story Ad you have the option of including one non-dynamic Creative in the story, this Creative can be of the types APP_INSTALL, WEB_VIEW or DEEP_LINK and should match the Dynamic Creatives type.
The creation of the non-dynamic Snap follows the regular creation of a Snap Ad with the corresponding attachment APP_INSTALL, WEB_VIEW and DEEP_LINK.
Composite Creative
The Composite creative contains information about the Tile (Preview Creative) and the Individual Snaps (Dynamic Creatives).
- The
preview_creative_id
attribute holds information about the Preview Creative. - The
creative_ids
attribute withincomposite_properties
holds information about the Dynamic Creatives. - The
creative_ids
is an array which can consist of 1 non-Dynamic Creative and 10 Dynamic Creatives or just 10 Dynamic Creatives - If you use the combination of 1 non-Dynamic + 10 Dynamic Creatives, the non-dynamic Creative needs to be of one of the types APP_INSTALL, WEB_VIEW or DEEP_LINK.
The headline
and brand_name
attributes on the Composite Creative are required but not used.
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"creatives":[{"name":"DPA Story Ad - Badger Tunneling Equipment","ad_account_id":"22225ba6-7559-4000-9663-bace8adff5f2","type":"COMPOSITE","headline":"Tunneling Tools","brand_name":"Badger Tunneling","render_type":"DYNAMIC","dynamic_render_properties":{"dynamic_template_id":"09d8d60b-1d05-423a-8d52-c2f52cf2c7dc","product_set_id":"10e7d339-0ff1-434a-996a-94d34918c948"},"composite_properties":{"creative_ids":["39283f04-3f1e-4c3a-89a7-2a8b7e15a58b","023ef23d-f3c9-4be1-a3fc-ec8dd76c6c88","b14f7e15-1c1f-4675-8c6d-0c8634bc9f58","d4b33aeb-1c8a-4a64-b46f-b3dd2c1dc208","aa982224-d78d-4400-8113-ff63cb309988","8fdb61d8-360e-4093-b6eb-a1d8f7bd45b8","abfdefb8-79a2-4b28-8de7-db4307c04948","a35c610b-75bf-40fc-87f3-08d82dec3108","5acecee9-ad03-4867-a319-e6dcb13b65d8","c75af576-1210-4a12-b9c1-7f2f6be71da8","1dae3e3e-75c7-4602-b9fa-05f98dbd7bf8"]},"preview_creative_id":"5a63e6bd-6641-4d43-b4f8-484518f6d0e8"}]}'
https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/creatives
{
"request_status": "SUCCESS",
"request_id": "60d46ed500ff067b3ef470a1250001737e616473617069736300016275696c642d63616365343036622d312d3435362d320001014b",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "4dba4e6e-fd3a-4fe7-aff9-0d18ba82927b",
"updated_at": "2021-06-24T11:39:02.144Z",
"created_at": "2021-06-24T11:39:02.144Z",
"name": "DPA Story Ad - Badger Tunneling Equipment",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2",
"type": "COMPOSITE",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Tunneling Tools",
"brand_name": "Badger Tunneling",
"render_type": "DYNAMIC",
"dynamic_render_properties": {
"dynamic_template_id": "09d8d60b-1d05-423a-8d52-c2f52cf2c7dc",
"product_set_id": "10e7d339-0ff1-434a-996a-94d34918c948"
},
"top_snap_crop_position": "MIDDLE",
"composite_properties": {
"creative_ids": [
"39283f04-3f1e-4c3a-89a7-2a8b7e15a58b",
"023ef23d-f3c9-4be1-a3fc-ec8dd76c6c88",
"b14f7e15-1c1f-4675-8c6d-0c8634bc9f58",
"d4b33aeb-1c8a-4a64-b46f-b3dd2c1dc208",
"aa982224-d78d-4400-8113-ff63cb309988",
"8fdb61d8-360e-4093-b6eb-a1d8f7bd45b8",
"abfdefb8-79a2-4b28-8de7-db4307c04948",
"a35c610b-75bf-40fc-87f3-08d82dec3108",
"5acecee9-ad03-4867-a319-e6dcb13b65d8",
"c75af576-1210-4a12-b9c1-7f2f6be71da8",
"1dae3e3e-75c7-4602-b9fa-05f98dbd7bf8"
]
},
"ad_product": "SNAP_AD",
"preview_creative_id": "5a63e6bd-6641-4d43-b4f8-484518f6d0e8"
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/{ad_account_id}/creatives
Composite Creative Parameters
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | R | ||
ad_account_id | Ad Account ID | R | |
type | Creative type | R | COMPOSITE |
headline | Not used | R | |
brand_name | Not used | R | |
render_type | R | DYNAMIC | |
preview_creative_id | Preview Creative ID | R | |
dynamic_render_properties.dynamic_template_id | Dynamic Template ID | R | |
dynamic_render_properties.product_set_id | Product Set ID | R | |
composite_properties.creative_ids | Array of Creative IDs used in the Story, can be 1 x non-dynamic Creative + 10 x Dynamic Creativesor10 x Dynamic Creatives | R |
Individual Dynamic Snap Ad Creatives
The individual Dynamic Snap Ads that make up the story follow the exact same requirements as Dynamic Snap Ad Creatives.
Ad Squad
The Ad Squad follows the same requirements of an Ad Squad used for Dynamic Product Ads with the addition of the attribute story_ad_creative_type
, this attribute is used to determine what type of Dynamic Creatives are used within the story.
Ad Squad Additional Parameter
Attribute | Description | Required | Possible Values |
---|---|---|---|
story_ad_creative_type | Indicates the type of Creatives used within the Story | R | APP_INSTALL, WEB_VIEW, DEEP_LINK |
Ad
The Ad entity links the Creative and the Ad Squad together, the type
and render_type
needs to use the values specified in the table below, the only attribute that differs from Dynamic Product Ads is the type
attribute which needs to be set to the value STORY.
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"ads":[{"name":"Dynamic Story Ad - Tunneling equipment","ad_squad_id":"54d79fbc-8ada-47cc-ae03-c044df05db3c","creative_id":"3f72ffee-5a3e-4d59-9893-2885dd983bea","status":"ACTIVE","type":"STORY","render_type":"DYNAMIC"}]}'
https://adsapi.snapchat.com/v1/adsquads/54d79fbc-8ada-47cc-ae03-c044df05db3c/ads
{
"request_status": "SUCCESS",
"request_id": "60d4765600ff0f3dbb82dac5e60001737e616473617069736300016275696c642d63616365343036622d312d3435362d3200010112",
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "3aa9cf43-661e-45ad-a593-cc8e1daabe3a",
"updated_at": "2021-06-24T12:11:04.612Z",
"created_at": "2021-06-24T12:11:04.612Z",
"name": "Dynamic Story Ad - Tunneling equipment",
"ad_squad_id": "54d79fbc-8ada-47cc-ae03-c044df05db3c",
"creative_id": "3f72ffee-5a3e-4d59-9893-2885dd983bea",
"status": "ACTIVE",
"type": "STORY",
"render_type": "DYNAMIC",
"review_status": "PENDING",
"review_status_reasons": [],
"delivery_status": [
"INVALID_PENDING_REVIEW_STATUS",
"INVALID_EFFECTIVE_INVALID"
]
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | Ad name | R | |
ad_squad_id | Ad squad ID | R | |
creative_id | Creative ID | R | |
status | Ad status | R | ACTIVE, PAUSED |
type | Ad type | R | STORY |
render_type | Rendering type | R | DYNAMIC |
Lead Generation Ads Guide
Lead Generation Ads allow you to present the user with a form when they interact with the ad.
Lead Generation Ads Entities
The following entities are added to the creative
entity when creating a Lead Generation creative.
Lead Generation Properties
JSON Example of the Lead Generation Ads entities
"lead_generation_properties": {
"privacy_policy_url": "https://www.example.com/",
"description": "This is my lead gen form",
"form_fields": [
{
"type": "FIRST_NAME",
},
{
"type": "LAST_NAME",
},
{
"type": "EMAIL",
},
{
"type": "CUSTOM",
"custom_form_field_properties": {
"type": "TEXT",
"description": "What is your favorite color?"
}
}
],
"legal_disclosures": {
"title": "My terms",
"description": "These are my terms",
"consent_form_fields": [
{
"consent_description": "I agree to the terms",
"required": true
}
]
},
"banner_media_id": "a0bc123d-d4ab-4ecc-b4eb-1a23bc4567d2"
}
Attribute | Description | Required | Possible Values |
---|---|---|---|
privacy_policy_url | URL that points to your brand’s Privacy Policy. A link to this page will appear on the confirmation screen before the user submits their entries. | Yes | A URL string. For example: "https://www.example.com" |
description | A description of the lead generation form. This appears on the form before its question fields. | Yes | A text string. Max length is 180 characters. |
form_fields | A list of the questions in the form. | Yes (See Form Requirements below.) | A list of JSON objects that represent the questions in the form. Each element of the list must be a JSON object that contains a type attributed. For example: {"type": "COMPANY_NAME"} Possible values for type :FIRST_NAME , LAST_NAME , EMAIL , PHONE_NUMBER , ADDRESS , POSTAL_CODE , BIRTHDAY_DATE , JOB_TITLE , COMPANY_NAME , CUSTOM . If type is CUSTOM , the object must also include the custom_form_field_properties property. |
legal_disclosures | An object that describes that legal disclosures in the form. | No | A Legal Disclosure Properties object that contains information about the legal disclosures in the form. |
banner_media_id | Media ID of the form’s banner image. | No | A text string that contains a media ID. Minimum Image Size: 750x230 Maximum Image Size: 1875x575 Aspect Ratio: 75:23 Max File Size: 5 MB |
Legal Disclosure Properties
Attribute | Description | Required | Possible Values |
---|---|---|---|
title | Title of the legal disclosure. | Yes, if legal_disclosures is non-null. |
A text string. For example: “Terms of Service”. Max length is 35 characters. |
description | A description of the terms that the user must agree to. | Yes, if legal_disclosures is non-null. |
A text string. Max length is 80 characters. |
consent_form_fields | Description of the consent needed and if it is required. | No | A list of JSON objects that represent consents that must be given by the user when submitting the form. Each element of the list is a simple object that contains a text string consent_description and a boolean property required : {"consent_description": "I agree to the terms", "required": true } Can contain up to two elements. |
Custom Form Field Properties
Attribute | Description | Required | Possible Values |
---|---|---|---|
type | Type of the form field. | Yes | TEXT , DATE , MULTIPLE_CHOICE_SINGLE_SELECTION , MULTIPLE_CHOICE_MULTI_SELECTION |
description | Description of the question being asked | Yes | A text string. |
multiple_choice_descriptions | Description of the consent needed and if it is required. | Yes if type is MULTIPLE_CHOICE_SINGLE_SELECTION or MULTIPLE_CHOICE_MULTI_SELECTION |
A list of strings that represent choices that a user can answer this question with. The choices will appear in the same order as in the list. The list must contain between 2-4 elements. The max length of each string is 25 characters. |
Form Requirements
FIRST_NAME
andLAST_NAME
fields must be included- At least one of the
EMAIL
field or thePHONE_NUMBER
field must be included. - The
ADDRESS
andPOSTAL_CODE
fields cannot both be included in the same form.
How to create a Lead Generation Ad
Creating a Lead Generation Ad consists of the following steps:
- Create a header banner image for your form. (Only required if the form contains a banner header)
- Create a Lead Generation Form creative.
- Use the creative created in step 2 to create a Lead Generation ad.
Creating a header banner image for your form
Use the Create Media endpoint to create a media object for your banner’s header image. Refer to the Media entity documentation for more details.
Banner images must have a minimum size of 750x230, a maximum size of 1875x575, and a 75:23 aspect ratio. The max file size for a banner image is 5 MB.
Creating a Lead Generation creative
curl -X POST \
-d '{"creatives":[{"ad_account_id":"8adc3db7-8148-4fbf-999c-8d2266369d74","name":"My Lead Gen Creative","type":"LEAD_GENERATION","headline":"This is my headline","brand_name":"Great brand","shareable":true,"call_to_action":"SIGN_UP","top_snap_media_id":"3m08b7ea-2dc6-4854-a44f-b3am70665b32","lead_generation_properties":{"privacy_policy_url":"https://www.example.com","description":"Please answer these questions!","form_fields":[{"type":"FIRST_NAME"},{"type":"LAST_NAME"},{"type":"PHONE_NUMBER"},{"type":"ADDRESS"},{"type":"BIRTHDAY_DATE"},{"type":"JOB_TITLE"},{"type":"COMPANY_NAME"},{"type":"CUSTOM","custom_form_field_properties":{"type":"TEXT","description":"What is your favorite word?"}},{"type":"CUSTOM","custom_form_field_properties":{"type":"MULTIPLE_CHOICE_MULTI_SELECTION","description":"What is your favorite color?","multiple_choice_descriptions":["Red","Blue","Green"]}}],"legal_disclosures":{"title":"legal title","description":"legal description","consent_form_fields":[{"consent_description":"Do you consent to the terms?","required":true}]},"banner_media_id":"d5cf309c-d4ab-4ecc-b4eb-3u63ba3314c2"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "92a44c1234ff0a974099d7d46d0001737e616473617069736300016275696c642d61353730363532632d312d3531322d3000012345",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "35fce3af-e1c7-46d4-a075-79180a3073ef",
"updated_at": "2022-01-28T20:00:05.465Z",
"created_at": "2022-01-28T20:00:05.465Z",
"name": "My Lead Gen Creative",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "LEAD_GENERATION",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "This is my headline",
"brand_name": "Great brand",
"call_to_action": "SIGN_UP",
"render_type": "STATIC",
"top_snap_media_id": "1f08b7ea-2dc6-4854-a44f-z1xc23456b32",
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"lead_generation_properties": {
"privacy_policy_url": "https://www.example.com",
"description": "Please answer these questions!",
"form_fields": [
{
"type": "FIRST_NAME",
"is_required": true
},
{
"type": "LAST_NAME",
"is_required": true
},
{
"type": "PHONE_NUMBER",
"is_required": true
},
{
"type": "ADDRESS",
"is_required": true
},
{
"type": "BIRTHDAY_DATE",
"is_required": true
},
{
"type": "JOB_TITLE",
"is_required": true
},
{
"type": "COMPANY_NAME",
"is_required": true
},
{
"type": "CUSTOM",
"is_required": true,
"custom_form_field_properties": {
"type": "TEXT",
"description": "What is your favorite word?"
}
},
{
"type": "CUSTOM",
"is_required": true,
"custom_form_field_properties": {
"type": "MULTIPLE_CHOICE_MULTI_SELECTION",
"description": "What is your favorite color?",
"multiple_choice_descriptions": [
"Red",
"Blue",
"Green"
]
}
}
],
"legal_disclosures": {
"title": "legal title",
"description": "legal description",
"consent_form_fields": [
{
"consent_description": "Do you consent to the terms?",
"required": true
}
]
},
"banner_media_id": "d1cf309c-d4ab-4ecc-b4eb-1f23zx4564c1"
}
}
}
]
}
The following properties must be added to the creative entity to create a Lead Generation creative.
Attribute | Description | Required | Possible Values |
---|---|---|---|
lead_generation_properties | Properties that describe the lead generation form. | Yes | Lead Generation Properties JSON entity. |
legal_disclosures | Custom Legal Disclosures that users can consent to when submitting the form. | Yes | Legal Disclosures JSON entity. |
banner_media_id | Media ID of the form’s banner image. | No | A media ID string. For example: “a1cf456c-d4ab-4ecc-b4eb-7a63bc1234d2” |
Creating a Lead Generation Ad using a creative
curl -X POST \
-d '{"ads":[{"ad_squad_id":"123456bd-8300-45f9-b335-9a3592b5f95c","creative_id":"35fce3af-e1c7-46d4-a075-79180a3073ef","name":"My Lead Generation Ad","type":"LEAD_GENERATION","status":"ACTIVE"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/123456bd-8300-45f9-b335-9a3592b5f95c/ads
{
"request_status": "SUCCESS",
"request_id": "61f48d3000ff091ecf5f32b8c10001737e616473617069736300016275696c642d61353730363532632d312d3531322d3000010125",
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "52328535-5947-4213-a8c0-da47d144f5ec",
"updated_at": "2022-01-29T00:41:21.303Z",
"created_at": "2022-01-29T00:41:21.303Z",
"effective_status": "ACTIVE",
"name": "My Lead Generation Ad",
"ad_squad_id": "123456bd-8300-45f9-b335-9a3592b5f95c",
"creative_id": "35fce3af-e1c7-46d4-a075-79180a3073ef",
"status": "ACTIVE",
"type": "LEAD_GENERATION",
"render_type": "STATIC",
"review_status": "PENDING",
"review_status_reasons": [],
"review_rejection_ids": [],
"approval_type": "NONE",
"conditional_approval_reason_ids": [],
"conditional_approval_reason_texts": [],
"delivery_status": [
"INVALID_PENDING_REVIEW_STATUS",
"INVALID_EFFECTIVE_INVALID"
]
}
}
]
}
For Lead Generation Ads, type
property must be set to LEAD_GENERATION
.
Example 1 - Form with a header banner, and three multiple choice questions.
curl -X POST \
-d '{"creatives":[{"ad_account_id":"8adc3db7-8148-4fbf-999c-8d2266369d74","name":"Form with lots of information","type":"LEAD_GENERATION","headline":"This is my headline","brand_name":"Great brand","shareable":true,"call_to_action":"SIGN_UP","top_snap_media_id":"3m08b7ea-2dc6-4854-a44f-b3am70665b32","lead_generation_properties":{"privacy_policy_url":"https://www.example.com","description":"Please answer these questions!","form_fields":[{"type":"FIRST_NAME"},{"type":"LAST_NAME"},{"type":"EMAIL"},{"type":"CUSTOM","custom_form_field_properties":{"type":"MULTIPLE_CHOICE_SINGLE_SELECTION","description":"What is your age range?","multiple_choice_descriptions":["0-14","15-25","25-50","Over 50"]}},{"type":"CUSTOM","custom_form_field_properties":{"type":"MULTIPLE_CHOICE_MULTI_SELECTION","description":"Which of these foods do you like?","multiple_choice_descriptions":["Hamburgers","Pizza","Salad","Steak"]}},{"type":"CUSTOM","custom_form_field_properties":{"type":"TEXT","description":"What is your favorite movie?"}}],"banner_media_id":"d5cf309c-d4ab-4ecc-b4eb-3u63ba3314c2"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "61f9c69900ff00ff783c74d19a860001737e616473617069736300016275696c642d37353461666336622d312d3531332d3000010162",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "35fce3af-e1c7-46d4-a075-79180a3073ef",
"updated_at": "2022-02-01T23:47:38.213Z",
"created_at": "2022-02-01T23:47:38.213Z",
"name": "Form with lots of information",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "LEAD_GENERATION",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "This is my headline",
"brand_name": "Great brand",
"call_to_action": "SIGN_UP",
"render_type": "STATIC",
"top_snap_media_id": "1f08b7ea-2dc6-4854-a44f-z1xc23456b32",
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"lead_generation_properties": {
"privacy_policy_url": "https://www.example.com",
"description": "Please answer these questions!",
"form_fields": [
{
"type": "FIRST_NAME",
"is_required": true
},
{
"type": "LAST_NAME",
"is_required": true
},
{
"type": "EMAIL",
"is_required": true
},
{
"type": "CUSTOM",
"is_required": true,
"custom_form_field_properties": {
"type": "MULTIPLE_CHOICE_SINGLE_SELECTION",
"description": "What is your age range?",
"multiple_choice_descriptions": [
"0-14",
"15-25",
"25-50",
"Over 50"
]
}
},
{
"type": "CUSTOM",
"is_required": true,
"custom_form_field_properties": {
"type": "MULTIPLE_CHOICE_MULTI_SELECTION",
"description": "Which of these foods do you like?",
"multiple_choice_descriptions": [
"Hamburgers",
"Pizza",
"Salad",
"Steak"
]
}
},
{
"type": "CUSTOM",
"is_required": true,
"custom_form_field_properties": {
"type": "TEXT",
"description": "What is your favorite movie?"
}
}
],
"banner_media_id": "d5cf309c-d4ab-4ecc-b4eb-3u63ba3314c2"
}
}
}
]
}
Example 2 - Form with no header banner and two consent fields.
curl -X POST \
-d '{"creatives":[{"ad_account_id":"8adc3db7-8148-4fbf-999c-8d2266369d74","name":"Form with consent","type":"LEAD_GENERATION","headline":"This is my headline","brand_name":"Great brand","shareable":true,"call_to_action":"SIGN_UP","top_snap_media_id":"3m08b7ea-2dc6-4854-a44f-b3am70665b32","lead_generation_properties":{"privacy_policy_url":"https://www.example.com","description":"Please answer these questions!","form_fields":[{"type":"FIRST_NAME"},{"type":"LAST_NAME"},{"type":"PHONE_NUMBER"}],"legal_disclosures":{"title":"Legal Terms","description":"These are our terms","consent_form_fields":[{"consent_description":"I read your terms","required":true},{"consent_description":"I agree your terms","required":true}]}}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "61f9cbe000ff06c274effe15af0001737e616473617069736300016275696c642d37353461666336622d312d3531332d3000010135",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "35fce3af-e1c7-46d4-a075-79180a3073ef",
"updated_at": "2022-02-02T00:10:09.887Z",
"created_at": "2022-02-02T00:10:09.887Z",
"name": "Form with consent",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "LEAD_GENERATION",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "This is my headline",
"brand_name": "Great brand",
"call_to_action": "SIGN_UP",
"render_type": "STATIC",
"top_snap_media_id": "1f08b7ea-2dc6-4854-a44f-a8da70665b32",
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"lead_generation_properties": {
"privacy_policy_url": "https://www.example.com",
"description": "Please answer these questions!",
"form_fields": [
{
"type": "FIRST_NAME",
"is_required": true
},
{
"type": "LAST_NAME",
"is_required": true
},
{
"type": "PHONE_NUMBER",
"is_required": true
}
],
"legal_disclosures": {
"title": "Legal Terms",
"description": "These are our terms",
"consent_form_fields": [
{
"consent_description": "I read your terms",
"required": true
},
{
"consent_description": "I agree your terms",
"required": true
}
]
}
}
}
}
]
}
FAQ
Setting up your app
Can I use this API without a redirect url?
You cannot use this API without a redirect_uri, but this part of the API is only used for authentication. part, it’s fully possible for you to carry out the authentication part only once per user of the API.
How can I edit an existing redirect_url
You cannot edit an existing redirect_uri instead you will need to set up a new app with the redirect_uri that you wish to use.
Can I use this API to make server to server requests?
Yes, only the user authorization process of this API requires you to use a client (browser), this is needed in order to obtain the tokens that makes it possible to query the API (Access token and Refresh token). Once you have these two tokens, you can use them alongside your API client specific details in order to query the API in a server to server fashion.
What should the redirect url be? Do you have any rules around it?
The redirect URL should be a SSL hosted URL you control, or that you can set up. The purpose of the URL is to pass the code parameter which you will need in order to set up your first access token and refresh token.
You may choose to just copy the code out of a browser and then set up the tokens using a tool like POSTMan, or you might choose to build an application that is hosted on the redirect_uri itself, where the application will read the GET code parameter and then generate the tokens.
For example, let’s say you specify this redirect URL:
https://www.example.com/index.html
After successful authentication the code parameter will be attached on the end of the URL the following way:
https://www.example.com/index.html?code=1234567890
If you are building a Web based tool using a UI where several users will log in to fetch data via the API it might make sense to make the redirect URL part of your application, and let the application fetch and read the GET parameter and then automatically proceed to the next step where the Application generates an access and refresh token for the user.
If you are building a “server to server” application, then you could specify any URL you control and that can display a GET parameter so that you may manually copy and save the code parameter from the URL and then execute the next step manually, using software such as POSTMAN.
A step-by-step instruction for the full Authentication process can be found here: https://marketingapi.snapchat.com/docs/#full-web-flow-example
I can’t see OAuth apps section in Business Manager*
- The user account which you are logged into needs to be an Organization admin
- The URL where the Oauth App Dashboard can be found on the following URL where YOUR_ORGANIZATION_ID needs to be replaced with your Organization ID:
https://business.snapchat.com/YOUR_ORGANIZATION_ID/settings/business-details
User Permissions and OAuth
When does the Access token and the Refresh token expire?
The refresh token does not expire, but will cease to function if the user it is tied to has their access removed.
The access token has an attribute expires_in
which specifies the duration in seconds, a new access token will be valid for 1800 seconds = 30 minutes.
Do I need to generate a new access token if my user gets added to a new Organization/Ad Accounts?
No, the access token is specific to the Snapchat account used, so if ad accounts are added or removed, it is reflected without the need to generate new tokens. However if you are added to a new Organization you will need to accept the invitation in the Welcome email.
We previously had access to the Ads API but lost access after the user who set it up left
It’s possible that the employee used their own account when setting up the Access and Refresh token. If this is the case you need to generate new tokens, for a user account which you need to maintain and store the details for so that they do not get lost if an employee leaves your company.
You will need to set up a new Snapchat account for this purpose
You will need to log in with a user that has the Organisation Admin role at https://business.snapchat.com
- That user will be able to invite the new Snapchat account to the Organization and assign an appropriate Role based on the actions you want to carry out via the Snap Ads API, Roles and Permissions
Note that if you use the Organisation Admin role for the new Snapchat account this role comes with powerful permissions as it can Create/Edit/Delete entities in any of the Ad accounts under the org.
How do I revoke access for an App?
You need to log in to the Snapchat account which has authorised the OAuth App access in order to revoke the access for that App.
- Navigate to this URL in a browser https://accounts.snapchat.com
- Log in as the user that granted access to the OAuth App in question
- Choose MANAGE APPS from the menu you are presented with https://accounts.snapchat.com/accounts/welcome Alternatively access the page directly by using this url https://accounts.snapchat.com/accounts/oauth2/apps
- The page will show you a list of all Applications that has been authorised to use your Ads API permissions on your behalf.
- Delete the app in question from the list.
Making API requests and interpreting responses
Can I use the Python requests library
Yes, however when using the Python requests library to upload Media files you need to remove one of the headers.
When using the Python requests library to upload files you should not include the header Content-Type':'multipart/form-data
When setting the headers in requests this should be sufficient:
headers = {'Authorization': 'Bearer ACCESS_TOKEN'}
Is the updated_at attribute on Ad level affected by Ad Review?
Yes it is, the updated_at attribute is updated when the review status of the Ad changes.
When requesting an entity I get the error message “Resource can not be found - error_code: E3003” what does it mean?
This type of error message (E3003) shows up in two different situations:
- The user/token making the request does not have permission to access the resource.
- The entity requested in the request doesn’t exist, this means either the entity was deleted or the entity ID hasn’t been entered correctly.
Was the entity deleted or misspelled?
To check if the entity has been deleted you can use the Audit logs for the entity in question. Audit logs are available for Campaigns/AdSquads/Ads/Creatives; https://developers.snapchat.com/docs/#audit-logs
If you can request the Audit logs successfully for the entity you will be able to see the actions taken on this entity, if the entity has been deleted then the final action on the entity will be;
"action": "DELETED"
If the Audit log request was successful, but all you get is an empty array, there is a possibility that the entity was deleted before audit logs were made available.
If the Audit log request was rejected with a “error_code”: “E3002” response it means you do not have permissions to access the Audit logs for the given entity.
This response means you do not have permission to access the Audit logs for the given entity
{
"request_status": "ERROR",
"request_id": "UNIQUE_ID",
"debug_message": "None of the requested actions READ_CHANGE_LOG_RECORDS can be authorized. Current user principal: MEMBER_ID",
"display_message": "We're sorry, but the requested resource is not available at this time",
"error_code": "E3002"
}
- If the Audit log request was rejected with a “error_code”: “E3003” response it means the entity ID is incorrect, in other words there has never been an entity with that ID.
This response means the entity ID is incorrect, there has never been an entity with this ID
{
"request_status": "ERROR",
"request_id": "UNIQUE_ID",
"debug_message": "Resource can not be found",
"display_message": "We're sorry, but the requested resource is not available at this time",
"error_code": "E3003"
}
Do you have permission to the Ad Account where the entity lives?
Assuming you know the Ad Account that you are attempting to access, you can carry out the following checks.
This request shows which user the token represents, and the Organizations that the User is a Member of, the request is fully described in the User section.
GET https://developers.snapchat.com/docs/#user
This request will show you the Ad Accounts and the roles the user has within those Ad Accounts.
GET https://adsapi.snapchat.com/v1/me/organizations?with_ad_accounts?true
The User permission request is explained in our section on fetching all Organizations with Ad Accounts.
If the user doesn’t have access to the Ad Account they are attempting to access it’s possible for an Organization Admin to add them via Snap Business Manager.
If the user in question has access to the Ad Account already, but has got incorrect permissions, you can amend their Role to match the permissions they need to carry out the intended task.
Fetching Reporting via the API
What Role do I need to fetch Campaign reporting from an Ad Account?
- The user in question needs to be a Member of the Organization where the Ad Account lives, this also means they have to accept the invitation which is sent to the Member email
- The user also needs to be a Member of the Ad Account
- The user also needs to have the Role type reports in the Ad Account
This can be managed by using the API for Members and Roles, or it can be handled within Snap Busines Manager where the role is referred to as Data Manager.
Is there a way to get dummy data from the API whilst developing my reporting App?
Yes, you can get dummy data if you add test=true to any reporting API request, that will return dummy data.
My daily reporting job has started failing.
If your reporting was working, and then suddenly started failing, there is a possibility that daylight savings are the cause of this.
When you make your request to the API you need to take into account that we save all our timings in UTC, so you will need to add/subtract hours in order to make up a 24 hour period that corresponds to the setting in your Ad Account.
If we assume an account is set to Europe/Berlin (Central European Time). During daylight savings Europe/Berlin will be +1 hour ahead of UTC, prior to Daylight savings Europe/Berlin will be +2 hours ahead of UTC.
This means that if you added 2 hours to your start_time and end_time during the daylight savings period, you will now need to add just 1 hour to the start_time and end_time once daylight savings are
In the situation that you request a report where the start_time is in a period when daylight savings were active, and where the end_time is in the period where daylight savings ended you will need to +2 hours to the start_time and +1 hour to the end_time.
You should take daylight savings into account for your application when structuring reporting requests.
How do metrics in the Snap Ads Manager map to fields in the Snap Marketing API?
The following table shows how some of the common metrics in the Snap Ads Manager translate to fields in the Marketing API. Calculated Metrics in the Snap Ads Manager do not directly map to fields in the Marketing API. A description of how these metrics are calculated in the Ad Manager can be found in the Notes column.
Ads Manager Metric | Marketing API Field | Metric Type | Notes |
---|---|---|---|
Start Time | start_time |
Entity Attribute | Ad squad attribute |
End Time | end_time |
Entity Attribute | Attribute in campaign and ad squad object |
ID | id |
Entity Attribute | The entity ID for a campaign, ad squad or ad object |
Campaign/Ad Squad/Ad Name | name |
Entity Attribute | The entity name for a campaign, ad squad, or ad object. |
Status | status |
Entity Attribute | The entity status for a campaign, ad squad, or ad object. |
Spend | spend |
Raw Metric | |
Paid Reach | uniques |
Raw Metric | |
Paid Impressions | impressions |
Raw Metric | |
Paid Frequency | frequency |
Raw Metric | |
Paid eCPM | - | Calculated Metric | Effective cost per thousand impressions. Calculated by taking the average cost for every 1,000 impressions. |
Swipe Ups | swipes |
Raw Metric | |
Swipe Up Rate | - | Calculated Metric | The average number of swipes per impression. Shows as a percentage. |
eCPSU | - | Calculated Metric | Effective cost per swipe up. Calculated by taking the average cost per each swipe up. |
Video Views | video_views |
Raw Metric | |
eCPV | - | Calculated Metric | Effective cost per video view. Calculated by taking the average cost per qualified video view. |
Completions | view_completion |
Raw Metric | |
Avg Screen Time | - | Calculated Metric | The average number of seconds spent watching your ad across all paid impressions. |
ROAS | - | Calculated Metric | Return on ad spend. The value of generated sales relative to your media spend. |
Attachment Frequency | attachment_frequency |
Raw Metric | |
Attachment Reach | attachment_uniques |
Raw Metric | |
Purchases Value | conversion_purchases_value |
Raw Metric | |
Purchases | conversion_purchases |
Raw Metric |
Marketing API Newsletter
The Snapchat Marketing API Newsletter provides updates on new launches and deprecations for the Marketing API and the Conversions API. Marketing API Newsletter Sign up
Change Log
Date | Description |
---|---|
2024-02-29 | Updated Creatives to require the profile_properties field |
2024-02-08 | Added new Organization level Role data_admin , this is a reporting only role |
2024-02-08 | Added new placement PUBLIC_STORIES_INSTREAM |
2024-01-30 | Added new delivery_status LEARNING_PHASE for Ad Squads |
2024-01-30 | Added method to update Pixel at Organization level |
2024-01-30 | Removed deprecated attributes allow_snap_javascript_sdk and use_immersive_mode from webview properties |
2024-01-30 | Added new call to action VIEW_PROFILE |
2024-01-27 | Added Public Profile stats supported granularities, SPOTLIGHT stats fields, and new authorized data sharing endpoints |
2023-12-26 | Added FAVORITES to the list of supported metrics for STORY and SAVED_STORY |
2023-01-10 | Added documentation for Public Profile Search API tier parameter |
2023-01-09 | Added documentation for visibility parameter in Public Profile Saved Stories API |
2023-11-17 | Added new section introducing the Public Profile Search API |
2023-11-06 | Added new section introducing the Transactions entity |
2023-10-24 | Document Dynamic Template Changelogs |
2023-07-24 | Added update on the European Digital Service Act |
2023-07-24 | Added CAROUSEL and SLIDESHOW layout for Dynamic Collection Ads |
2023-07-24 | Updated the Ad Squad section, added conversion_window, updated Placement to Ad type, Optimisation goal to Ad type |
2023-07-24 | Snapcode Preview now supports Dynamic Ads |
2023-07-24 | Following deprecation in February Audience filters (FILTER), Longform video (LONGFORM_VIDEO) and Lens Longform video (LENS_LONGFORM_VIDEO) have been removed from the docs, Ad type specific metrics associated with these Ad types can still be fetched |
2023-06-08 | Added discover Public Profile stats documentation |
2023-06-08 | Update documentation of the Profile media upload API |
2023-06-01 | Added discover Public Profile Lenses documentation |
2023-05-29 | Added discover Public Profile Saved Stories documentation |
2023-05-25 | Added discover Public Profile Spotlights documentation |
2023-05-22 | Updated documentation for spotlight posting |
2023-05-18 | Added discover Public Profile documentation |
2023-05-04 | Added announcement for pagination enforcement |
2023-04-03 | Added possible objective values for campaign creation |
2023-02-28 | Add new INTERSTITIAL_SPOTLIGHT position to PlacementV2 |
2023-01-24 | Updated CAPI Business SDK copy and removed beta |
2022-12-23 | Added Targeting Auto Expansion update in Announcements and Targeting section |
2022-12-23 | Added Long form Video deprecation in Announcements |
2022-12-23 | Added new First party Shopper Interest targeting (shp) |
2022-12-23 | Added new Dynamic Template option AUTOMATIC |
2022-12-23 | Updated Reporting Insights and Dimensions, breakdown by Country and Operating System is now available |
2022-12-23 | Deprecated Placed Interest targeting (plc) |
2022-12-23 | Deprecated the reporting parameter platform_stats |
2022-12-23 | Deprecated the placement_v2 snapchat_positions option GAMES |
2022-12-23 | Deprecated the placement_v2 snapchat_positions option AUDIENCE_EXTENSION |
2022-09-29 | Updated Ad Squad section, added currency aware bids, maximum value of bid_micro is now dependent on the currency of the Ad account |
2022-09-29 | Updated Measurement Section, all conversion events now have an equivalent value metric |
2022-09-29 | Updated Measurement section, added new metric profile_clicks |
2022-09-29 | Updated Role Section, how to update the Role type |
2022-09-29 | Updated User section, the response now includes the snapchat_username of the user |
2022-09-29 | Updated Interest Targeting section, interest targeting for SCLS and VAC now has a new endpoints and parameters |
2022-09-29 | Updated Targeting section, fetching targeting options per Country now has a new endpoint and a new parameter for non-US countries |
2022-09-15 | Added “post saved story” documentation in Profile API. |
2022-09-14 | Add “locale” in the post spotlight documentation in Profile API. |
2022-09-02 | Added “get spotlight” and “post spotlight” documentation in Profile API. |
2022-08-24 | Corrected some parameter terms in curl example and Best Practices section. |
2022-08-22 | Update Conversion API docs to improve language and fix typos on how to get started |
2022-08-18 | Corrected Snap Lifestyle Categories API to reflect updated country code param |
2022-07-14 | Updated Conversion API event_type with LEVEL_COMPLETE |
2022-07-13 | Updated public profile APIs |
2022-07-06 | Updated parameter best practices information |
2022-07-06 | Updated Product Search and Facets sections to include new travel endpoints (/products/search, /flights/search, /hotels/search) and associated attributes |
2022-05-24 | Updated creatives section to include instructions on attaching a profile |
2022-05-23 | Updated AdSquad SKAdNetwork section with critical changes to SKAdnetwork tracking and introduction of ecid_status |
2022-05-23 | Updated Measurement section, deprecated Reporting Insights for Conversion metrics for region, dma, lifestyle_category, product and make |
2022-05-23 | Added new section for the Marketing API Newsletter |
2022-04-07 | Renamed SAM (Snap Audience Match) to “Customer List” to align naming with other parts of the platform. |
2022-01-10 | Updated Ad Squad Section, Pixel/App Optimization goals no longer require conversions to unlock |
2022-01-06 | Updated Measurement section to include Lead Gen Reporting |
2021-11-12 | Added a new scopes table for coversion API and updated the auth docs to support multiple scopes |
2021-10-25 | Updated announcements, timelines and reference documentation for Ad squad targeting updates |
2021-10-25 | Updated entire Conversion API section |
2021-10-25 | Updated Ad Squad section, placement_v2, Story Ads can now serve in between User stories and Publisher stories |
2021-10-05 | Added the new Showcase Creative type to the Dynamic Collections Ads Guide |
2021-10-05 | Updated the Targeting Spec entity to include behaviour pre- and post 27 November 2021 |
2021-09-23 | Updated Ad Squad section, the bid_strategy AUTOBID is now available to all App and Pixel Optimization Goals |
2021-09-13 | Updated Measurement section, SKAd reporting section updated with Ad level metrics (estimated) availability |
2021-08-23 | Added new section for Dynamic Story Ads |
2021-08-23 | Updated Measurement section, the granularity TOTAL is now available for frequency, uniques, attachment_uniques, attachment_frequency, total_reach, earned_reach |
2021-08-23 | Updated Measurement section, deprecated the HOUR granularity for frequency, uniques, attachment_uniques, attachment_frequency, total_reach, earned_reach |
2021-08-23 | Updated Measurement section, deprecated the metrics position_uniques and position_frequency |
2021-08-23 | Updated Entity Pagination section to include additional entities where pagination is supported |
2021-06-17 | Updated Ad Squad section with new attributes child_ad_type and forced_view_setting |
2021-05-26 | Updated SKAd Network Reporting to include VIEW conversions |
2021-05-25 | Deprecation of Story Ad metrics position_uniques and position_frequency announced |
2021-05-25 | Added new metric native_leads under Additional Metrics in the Measurement section |
2021-05-25 | Added new Media Rating Council accredited metrics in the Measurement section |
2021-05-25 | Updated Snap App ID section to include method to fetch all Snap App IDs under an Ad Account |
2021-05-25 | Updated Creative section specifying Snapcode Preview availability |
2021-05-25 | Updated Creative section, Story Ads now hold 1-20 individual Snaps |
2021-05-25 | Updated the Measurement section to consolidate Lens and Filter specific metrics under Additional metrics |
2021-04-27 | Added Apple Transparent Tracking changes to the Reporting and measurement API docs |
2021-04-22 | Updated DPA creative creation with url macros information |
2021-04-12 | Updated Ad, Ad Squad and Campaign sections to include new deleted attribute and new parameter read_deleted_entities |
2021-04-12 | Updated Roles section to include Catalog Roles |
2021-03-12 | Updated Ad Squad section to include SKAd Network attributes |
2021-03-12 | Updated Measurement section to include SKAd Network metrics and reporting |
2021-03-03 | Added new CTAs and delivery statuses |
2021-02-03 | Added a new section for Snap App ID |
2021-02-03 | Updated Ad Squad section to include new attribute event_sources |
2021-02-03 | Updated Dynamic Product Ads Guide to include new attribute event_sources |
2021-02-03 | Updated Targeting section to include new targeting option app_install_states |
2021-02-03 | Updated Targeting examples to include several examples of using app_install_states |
2021-02-03 | Updated available countries for Reach & Frequency Campaigns |
2021-01-08 | Added a new section for collection ads for DPA |
2020-11-18 | Added a new section under measurement for DPA reporting |
2020-10-29 | Updated section on Dynamic Ad products - Feed Upload to include UPSERT option |
2020-10-23 | Updated section on lookalike audience creation spec to support multi country targetting |
2020-10-22 | Added the parameter action_report_time (conversion, impression) for measurement requests |
2020-10-22 | Added the offline dimension to conversion_source_types for measurement requests |
2020-10-19 | Added new section for Conversion API |
2020-10-12 | Added new section for Dynamic Product Ads, introducing Feed Upload |
2020-10-12 | Added new section for Dynamic Product Ads, introducing Product Feeds |
2020-10-12 | Updated Dynamic Product Ads catalog section to include Create/Update/Delete |
2020-09-22 | Added test attribute for Ad Account creation in the /adaccounts endpoint |
2020-09-22 | Updated authentication section to call out the expiry of the Access token |
2020-09-22 | Updated section on Lookalike audience creation to include information on lookalike updating when seed audience is updated |
2020-08-17 | Updated Measurement section to include platform_stats attribute for use with the Snapchat Audience Network |
2020-08-17 | Updated Ad Squad section, placement_v2, Automatic Placement now mentions the Snapchat Audience Network |
2020-07-27 | Updated Dynamic Product Ads introducing Product Search and examples |
2020-07-27 | Added new section introducing the attribute delivery_status |
2020-07-27 | Added new section introducing the Invoice entity |
2020-06-18 | Updated Dynamic Product Ads introducing Dynamic Templates |
2020-06-18 | Updated Dynamic Product Ads introducing Catalog Diagnostics |
2020-06-18 | Updated Dynamic Product Ads with new examples of Prospecting and Retargeting Ad Squads |
2020-06-18 | Updated Creative and Lens section with new values for the Call To Action attribute |
2020-06-18 | Updated Ad Squad section to include clarification and example use of MIN_ROAS |
2020-06-18 | Updated Ad Squad section with additional Optimization Goals for use with Frequency Capping |
2020-06-18 | Updated Optimization Goals to include new goal APP_REENGAGE_OPEN |
2020-06-18 | Added example of SLC targeting exclusion to Example Targeting Spec section |
2020-06-18 | Added new table listing INCLUDE/EXCLUDE options for Targeting spec |
2020-05-04 | Added new section introducing the Role entity |
2020-05-04 | Added new section introducing the Member entity |
2020-05-04 | Added new section introducing the Billing Center entity |
2020-05-04 | Updated Ad Account Section with Ad Account Creation, Updating an Ad Account, assigning a Funding Source |
2020-05-04 | Updated the Ad Account attributes, to include political advertising, CHE and French Advertisers |
2020-05-04 | Updated Targeting section for Demographics, Age Range to list deprecated 35+ setting |
2020-04-09 | Updated bid_strategy section to clarify details on the sunsetting of auto_bid and target_bid |
2020-04-09 | Updated AdSquad spec daily_budget_micro, lowered from 20000000 to 5000000 (from £/€/$20 to 5) |
2020-04-09 | Updated AdSquad spec to clarify possible values of delivery_constraint |
2020-04-02 | Updated Commercials section to include videos longer than six seconds |
2020-03-30 | Updated targeting section to include multi-country targeting |
2020-03-30 | Updated targeting spec examples to include an example of multi-country targeting |
2020-03-30 | Added GAMES to placement_v2 including an example for GAMES placement via snapchat_positions |
2020-03-30 | Updated Commercials section based on new GAMES placement_v2 for snapchat_positions |
2020-03-20 | Added new section announcing upcoming breaking changes |
2020-03-20 | Added new section on bid_strategy and the new bid type MIN_ROAS |
2020-03-20 | Added new Creative types, AD_TO_CALL and AD_TO_MESSAGE |
2020-03-20 | Added new section for verifying phone number for AD_TO_CALL, AD_TO_MESSAGE Creative types |
2020-03-20 | Added new Insights and Dimensions section including new parameter report_dimension |
2020-03-20 | Updated placement_v2 section to include more examples and table comparing with placement |
2020-03-20 | Updated Ad Squad section with list of available Ad Types / Optimization Goal |
2020-03-02 | Updated Commercials section, two new countries Kuwait and Ireland |
2020-03-02 | Updated Creative section to list Filter and Lens |
2020-02-13 | Added docs for Lenses |
2020-02-13 | Updated Reach and Frequency to include additional launched countries |
2020-02-13 | Updated Audience source type to include MOBILE audiences |
2020-01-21 | Updated Authentication section - App set up and access to the API is now managed via Snap Business Manager |
2019-12-19 | Added docs for Dynamic Product Ads |
2019-11-29 | Added conversion_source_types parameter for breakout of conversions |
2019-11-29 | Added omit_empty parameter for reporting requests |
2019-11-07 | Added new section Commercials - How to set up and target Creatives to run as Commercials |
2019-11-07 | Updated Snap Audience Match - Update an Audience Segment |
2019-11-07 | Updated Targeting Demographics - Added min_age and max_age to Age Range |
2019-11-07 | Updated Targeting Section - Added enable_targeting_expansion |
2019-11-07 | Updated Measurement - Metrics and supported granularities table updated |
2019-11-07 | Updated Measurement section - Added 19 new Pixel conversion events |
2019-11-07 | Updated Measurement API patterns - Added Pagination |
2019-11-07 | Updated Ad Squad - pacing_type attribute at is now immutable |
2019-11-07 | Updated Audience Geofilters - Optimization goal IMPRESSIONS is now available |
2019-11-07 | Updated Bid Estimate - Added additional optimization goals |
2019-11-07 | Updated AdSquad - New measurement_provider_names DOUBLEVERIFY |
2019-11-07 | Updated AdSquad - New Third-Party Tracking Tags DOUBLEVERIFY |
2019-11-01 | Updated Ad - Upcoming changes to Third-party tracking fields |
2019-10-03 | Added new AdSquad optimization goal, video_views_15s |
2019-10-03 | Added new metrics video_views_time_based, video_views_15s |
2019-10-03 | Removed MOAT from Ad level third party tracking |
2019-09-19 | Updated Ad Account, Ad entities - added paying_advertiser_name for political ads |
2019-09-19 | Updated Campaign - added attribute candidate_ballot_information for political ads |
2019-09-19 | Updated Ad Account to include billing type attribute, |
2019-09-10 | Added new section under AdSquad - Third-Party tracking tags - MOAT |
2019-09-10 | Updated AdSquad - added attribute measurement_provider_names for Third-Party tracking |
2019-09-10 | Updated AdSquad - added parameter to return placement_v2 |
2019-09-10 | Updated AdSquad - added content type GAMING |
2019-09-10 | Updated AdSquad - pacing_type is immutable once set |
2019-09-10 | Updated Campaign - added regulations attribute for Credit/Housing/Employment Ads |
2019-08-09 | Added On Demand Geofilter sunsetting announcement |
2019-07-31 | Added redirect_uri parameter to access token call |
2019-07-31 | Added docs for pacing_type |
2019-07-31 | Removed Innovid |
2019-07-26 | Added new section for Audit logs |
2019-07-26 | Updated pagination section to include change logs |
2019-07-26 | Updated metrics additional metrics available in real time |
2019-07-26 | Updated metrics removed WEEK and MONTH granularities |
2019-07-18 | Added docs for placement v2 |
2019-06-26 | Added information on Entity Request Limits for Creating/Updating Entities |
2019-06-26 | Additional information on multipart media upload v2 |
2019-06-26 | Pagination support for additional endpoints, All accounts under Organization, All Segments under Ad account |
2019-06-26 | Additional Optimization Goals for pixel and app added |
2019-06-13 | Updated multipart media upload to v2 |
2019-01-30 | Changed daily_budget_micro to minimum value 20000000 |
2019-01-30 | Added definition for response attribute finalized_data_end_time |
2019-01-30 | Updated campaign measurement_spec with relevant ad types |
2019-01-30 | Added clarification position_stats metric only available at LIFETIME granularity |
2019-01-24 | Updated the styling |
2019-01-11 | Added documentation for target cost bidding |
2019-01-11 | Added method for updating a Creative |
2018-11-15 | Added documentation for Collection creatives |
2018-11-15 | Added documentation for AdSquad mutability |
2018-11-15 | Removed targeting by country table in favor of the targeting by country endpoint |
2018-11-06 | Added Story Ad position metrics and updated Audience Filter bidding properties |
2018-10-18 | Added new Creative and Ad types for Lens with attachments |
2018-10-18 | Autobidding is allowed for Audience filters |
2018-10-18 | Added API method to retrieve SLC by country |
2018-10-18 | Added new source types PIXEL and FOOT_TRAFFIC_INSIGHTS for SAM audience |
2018-10-08 | Added documentation for Measurement for retrieving position metrics for Snap Ads within a Story Ad |
2018-09-13 | Added documentation for retrieving Placed Visitation Segments |
2018-09-13 | Added AUCTION as a buy_model type on Campaigns |
2018-09-13 | Added PHONE_SHA256 as a new schema for adding users to SAM segments |
2018-09-12 | Added documentation for Measurement for Ad types LENS, AD_TO_LENS, FILTER |
2018-09-12 | Added method for deleting an Audience segment |
2018-09-12 | Added method to retrieve roles for Ad Accounts for currently logged in user |
2018-09-12 | Added method for retrieving a thumbnail from Media of VIDEO type |
2018-09-12 | Called out our preferred gender targeting method in targeting examples |
2018-09-12 | Corrected the required fields for AdSquad creation and updating |
2018-09-12 | Corrected the http method for Audience Size v2 |
2018-08-01 | Added documentation for Reach and Frequency buying |
2018-08-01 | Added documentation for fallback to webview for deeplink ads |
2018-08-01 | Added documentation for Audience Size v2 |
2018-07-01 | Corrected minimum for radius targeting to 96 meters |
2018-07-19 | Added documentation for new optimization goals for pixel and app conversions |
2018-07-19 | Added documentation for new creative type and ad type AD_TO_LENS and media type LENS_PACKAGE |
2018-07-19 | Added documentation for min/max age targeting and modified targeting spec examples to include min_age and max_age |
2018-07-19 | Removed auto-fill SDK guidelines. Auto-fill no longer requires SDK to be installed |
2018-07-06 | Added documentation in API Patterns on how to retrieve paginated results when fetching many entities |
2018-07-03 | Added optimizaton goal STORY_OPENS |
2018-06-26 | Added documentation for Nielsen targeting categories |
2018-06-26 | Removed the word DLX from Advanced Demographics targeting options as it also includes Experian categories now |
2018-06-26 | Updated max radius for radius targeting to 100km |
2018-06-26 | Added documentation for auto bidding |
2018-06-25 | Added documentation for fetching a single audience segment by id |
2018-06-13 | Added documentation for audience insights |
2018-06-13 | Added documentation for new metric conversion_purchases_value |
2018-06-13 | Added note that new geofilter integrations will not be supported |
2018-06-13 | Added information about deprecated boolean flag for targeting dimensions |
2018-06-13 | Added link to supported currencies |
2018-06-13 | Ad Account timezones no longer need to be America/Los Angeles |
2018-04-30 | Added documentation for Story Ads, new creative types PREVIEW and COMPOSITE, new ad type STORY, new placement DISCOVER_FEED |
2018-04-30 | Added story_opens and story_completes metrics for Story Ads |
2018-04-30 | Added that for Story Ads the only optimization_goal supported is IMPRESSIONS |
2018-04-30 | Updated that Ad Scheduling is now available |
2018-04-05 | Added that Integral Ad Science (IAS) tags are now supported |
2018-04-05 | Added documentation for location categories |
2018-04-05 | Added documentation for point radius targeting |
2018-03-15 | Added measurement_spec into the campaign object attributes, required for all ads that need app tracking and post install conversion reporting |
2018-03-15 | Added notice that python SDK is not available yet and coming soon |
2018-03-13 | Added documentation on how to retrieve a preview for a Media |
2018-03-08 | Added documentation on how to retrieve a Snapcode preview for a Creative |
2018-03-05 | Added documentation that top snap media can now be of type IMAGE |
2018-02-22 | Added documentation for ad scheduling |
2018-02-22 | Updated that bid estimate can be used for all optimization goals |
2018-02-22 | Updated default retention_in_days for SAM is lifetime |
2018-02-22 | Updated that headline is required for geofilters and audience filters but never displayed |
2018-02-22 | Added FOOD, SPORTS, YOUNG_BOLD to included and excluded content types |
2018-02-07 | Updated call for generating a new access token from refresh token |
2018-02-07 | Updated that audience size endpoint returns estimated sizes |
2018-02-07 | Updated instructions for getting OAuth credentials |
2017-11-30 | Updated frequency cap time_interval maximum to 30 days or 720 hours |
2017-11-28 | Added documentation for attribution windows |
2017-11-28 | Added Paypal as a funding source option |
2017-11-28 | Updated that audience filters and geofilter media needs to be at least 50% transparent |
2017-11-28 | Removed granularity from Additional metrics table, refer Metrics and supported granularities table |
2017-11-28 | Removed goal_type from old API responses for Ad Squad object |
2017-11-22 | Updated MOAT tag |
2017-11-20 | Added lifetime_spend_cap_micro for the Campaign object |
2017-11-20 | Added DEEP_LINK to ad type options |
2017-11-20 | Added note that MOAT tagging is available for all snap ads products |
2017-11-20 | Updated geofilter and audience filter creative dimensions |
2017-11-13 | Added block_preload property for creatives with web view |
2017-11-07 | Removed pixel implementation details and added reference to Business Help Center guide for Snap Pixel |
2017-11-07 | Updated output for Get Pixel endpoint with pixel_javascript parameter |
2017-11-07 | Added new countries supported for Geofilters |
2017-11-07 | Updated impressions_composition and uniques_composition to impression_composition and unique_composition |
2017-10-11 | Updated that frequency caps can be edited once they are live |
2017-10-10 | Added documentation for frequency caps |
2017-10-10 | Added geopolygon support for geofilters |
2017-10-10 | Updated audience filter documentation to show zipcode targeting is allowed |
2017-09-13 | Updated fields for audience filter stats |
2017-09-07 | Added documentation for pixel stats endpoints |
2017-09-07 | Added documentation for reporting insights breakdowns |
2017-09-07 | Added new fields for Geofilter stats |
2017-08-20 | Added USER_STORIES placement option |
2017-08-20 | Added image specifications for app icon |
2017-08-20 | Added new countries: Oman, Bahrain, Malaysia, Philippines and Thailand |
2017-08-20 | Added note about campaign budgets being at least 0.25 of sum of its ad squad budgets |
2017-08-20 | Added minimum for ad squads daily budgets |
2017-08-10 | Added documentation for Audience Filters |
2017-08-01 | Added documentation for deep link creative type |
2017-07-31 | Added information about age_min targeting for geofilters |
2017-07-31 | Added geofilter schedule information. Geofilters can be bought 3 hours in advance on weekdays. |
2017-07-31 | Added note about max number of SAM segments allowed per ad account |
2017-07-31 | Updated third party tags section with examples and more information |
2017-07-31 | Updated language targeting example |
2017-07-19 | Added new fields upload_status and targetable_status for SAM segments |
2017-07-12 | Updated targeting geo matrix with new countries |
2017-07-10 | Added documentation for device make targeting |
2017-07-10 | Update documentation for creating an organization |
2017-06-28 | Added documentation and example for zipcode targeting |
2017-06-28 | Added note that deep_link_urls field is no longer needed |
2017-06-21 | Added new metrics fields video_views, screen_time_millis, avg_screen_time_millis |
2017-06-20 | Corrected examples for web view creatives to use “VIEW” call to action |
2017-06-19 | Removed pixel deletion |
2017-06-16 | Added that credit card funding sources can now be created via Business Manager |
2017-06-16 | Corrected content type enum from BEAUTY to BEAUTY_FASHION |
2017-06-16 | Added start_date and end_date fields for coupons in the funding source documentation |
2017-06-12 | Added that currency field on funding source object is only returned for line of credit and coupons |
2017-06-09 | Added documentation for included_content_types and excluded_content_types |
2017-06-06 | Added GBB for video views |
2017-05-25 | Added advertiser_organization_id to Ad Account attributes |
2017-05-25 | Corrected HTTP Request for creating pixels |
2017-05-25 | Updated targeting by country matrix with new countries |
2017-05-25 | Added documentation for new types of funding sources and updated GET fundingsources output |
2017-05-25 | Updated OS version targeting example to include os_version_min and os_version_max |
2017-05-25 | Added information that geofilters can now be bought 90 days in advance |
2017-05-25 | Updated geofilter radius limit |
2017-05-18 | Added documentation for language targeting |
2017-05-18 | Added OS version targeting and language example |
2017-05-18 | Added timestamp macro to supported macros for third party tracking urls |
2017-05-11 | Updated Pixel SDK code |
2017-05-11 | Added CONTENT placement |
2017-05-11 | Added OS version targeting |
2017-05-11 | Added information about creating ad accounts in Business Manager |
2017-05-11 | Removed old breaking change section |
2017-05-11 | Added documentation for conversion stats |
2017-05-11 | Updated old links |
2017-05-03 | Added documentation for Snap Pixel |
2017-05-03 | Added measurement spec field on the campaign object |
2017-05-02 | Modified MOAT tag example with new MOAT tag |
2017-05-02 | Added new countries support to the targeting options matrix |
2017-05-02 | Added new currecies supported |
2017-05-02 | Added details about DLXP targeting |
2017-05-02 | Added the stats granularity matrix |
2017-05-02 | Added Apsalar to the list of supported mobile measurement partner intergrations |
2017-05-02 | Added the supported countries for geofilters |
2017-05-02 | Corrected dimensions for geofilter creative spec |
2017-04-20 | Added default retention days for SAM |
2017-04-20 | Added min and max for geofilter targeting radius |
2017-04-20 | Added note that geofilters should run at least for an hour |
2017-04-20 | Added note that geofilters need to start and end by the hour |
2017-04-20 | Updated that geofilters need to be purchased at least 16 hours before intended delivery |
2017-04-20 | Clarified geofilter Ad Squads can only have one location in the targeting spec |
2017-04-17 | Updated SLC targeting abilities in the targeting by country matrix |
2017-04-17 | Updated SAM and Lookalike targeting abilities in the targeting by country matrix |
2017-04-17 | Added upload image media example for app icon and app icon specifications |
2017-04-17 | Added tracking_urls to attributes that can be updated for Ad object |
2017-04-17 | Added WATCH as CTA option for webview |
2017-04-17 | Added brand_name and headline to the creative example |
2017-04-17 | Added example for metro targeting |
2017-04-07 | Fixed example for geofilter price quote endpoint |
2017-04-06 | Added documentation for geofilter stats |
2017-04-06 | Added information about pausing geofilter ads |
2017-04-04 | Added docs for Geofilters |
2017-03-29 | Added note that Ad Squads targeting cannot be updated after review |
2017-03-29 | Added documentation for targeting options by country endpoint |
2017-03-29 | Added documentation for deep linking |
2017-03-29 | Added documentation for auto-fill |
2017-03-17 | Added example for third party view tracking |
2017-03-17 | Added documentation for lookalike type enum |
2017-03-17 | Added documentation for source_type ENGAGEMENT |
2017-03-17 | Fixed date for upcoming breaking changes to 1st April |
2017-03-17 | Added Finland to the targeting geo matrix |
2017-03-15 | Added GBB for APP_INSTALLS as an option coming soon |
2017-03-09 | Added list of allowed Third Party tracking URLs |
2017-03-09 | Added matrix for targeting types allowed by country |
2017-03-09 | Fixed example for targeting using carrier_id |
2017-03-09 | Fixed formatting issue in DLX targeting doc |
2017-03-09 | Fixed formatting in rate limits doc |
2017-03-08 | Added breaking change about Creative brand_name and headline |
2017-03-08 | Added Upcoming Breaking Changes section |
2017-02-28 | Fixed examples for bid estimate by targeting spec |
2017-02-28 | Added lifetime_spend_cap_micro |
2017-02-28 | Added DLXC examples |
2017-02-28 | Fixed errors in examples with bid_type |
2017-02-28 | Added delete and remove all users for SAM |
2017-02-28 | Added bid estimate API |
2017-02-28 | Update examples from daily_budget to daily_budget_micro |
2017-02-15 | Updated measurement metric availability details |
2017-02-15 | Added new CTA options for Web View Creative |
2017-02-08 | Added Mobile Measurement Setup Help Links to App Install Creative section |
2017-02-06 | Removed note regarding limited country availability |
2017-02-02 | Added Brand Name & Headline optional properties to Creative section |
2017-01-18 | Added OPTIMIZED crop option |
2017-01-18 | Added Bulk Fetch details for Ad Squads & Ads |
2017-01-12 | Added Third-Party Tracking details to Ad section |
2017-01-05 | Added targeting examples for DLX |
2017-01-05 | Added DLX Interests targeting details |
2017-01-05 | Added DLX Advanced Demographics targeting details |
2017-01-05 | Fixed typo in carrier targeting spec & example |
2016-12-07 | Added Audience Size section & usage examples |
2016-12-07 | Added Metro / DMA Targeting section & usage example |
2016-12-07 | Added Carrier Targeting section & usage example |
2016-11-11 | Added Goal-Based Bidding details to Ad Squad section |
2016-11-02 | Additional metrics (including attachment metrics) details updated |
2016-11-02 | Rate Limits section added |
2016-09-23 | Added Chunked Upload details to Media section |
2016-09-20 | Added Lookalike creation details to Snap Audience Match section |
2016-09-20 | Removed Creative Update section |
2016-09-20 | Added allowable “call_to_action” values for each Creative attachment type |
2016-09-16 | Changed “icon_media_id” property for App Install creative to Required |
2016-09-16 | Updated Ad Type options & Ad Type <-> Creative Type Mapping |
2016-09-14 | Added full web redirect OAuth2 Flow |
2016-09-14 | Added “review_status” and “review_status_reason” properties on Ad |
2016-09-14 | Added “total_budget_micro” and “budget_spent_micro” properties on Funding Source |
2016-09-14 | Added “breakdown” parameter to Measurement requests |
2016-09-14 | Added “test” parameter to Measurement requests for sample/fake stats response |
2016-09-14 | Added “regulated_content” property to Targeting on Ad Squad |
2016-09-14 | Removed “category_type” property from Interest Targeting on Ad Squad |
2016-09-08 | Updated targeting examples with updated age values |
2016-09-01 | Removed third party tracking URLs from Ad |
2016-08-30 | SAM - Added details on adding users + normalizing/hashing identifiers |
2016-08-30 | SAM - Removed “source_subtype” property |
2016-08-30 | Media objects now have a “download_link” property with full URL to file |
2016-08-15 | Snap Audience Segments ID property is now “id” instead of “segment_id” |
2016-08-15 | Updated Measurement examples |
2016-08-15 | Added Access Token Expiration section |
2016-08-15 | Fixed SCLS targeting examples |
2016-08-15 | Initial documentation released to partners |
Breaking Changes Log
April 2020
curl "https://adsapi.snapchat.com/v1/adsquads/079abe5b-8aa3-4009-9932-66e0b0a2c75c?return_placement_v2=true" \
-H "Authorization: Bearer meowmeowmeow"
Example, this Ad Squad using multi-country targeting is targeting the US and Canada:
{
"request_status": "SUCCESS",
"request_id": "5e821b1100ff00ff5566930ea67e0001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d61643137333166302d312d3333382d3000010145",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "079abe5b-8aa3-4009-9932-66e0b0a2c75c",
"updated_at": "2020-03-10T20:34:09.826Z",
"created_at": "2020-03-10T20:33:58.614Z",
"name": "Multi country Ad Squad Example",
"status": "ACTIVE",
"campaign_id": "f5b84e48-dc8b-4ddb-bf9b-edf07fadd6c6",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"languages": [
"en"
]
}
],
"geos": [
{
"country_code": "us",
"operation": "INCLUDE"
},
{
"country_code": "ca",
"operation": "INCLUDE"
}
],
"enable_targeting_expansion": 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": "2019-12-17T01:38:19.961Z",
"optimization_goal": "APP_INSTALLS",
"delivery_constraint": "DAILY_BUDGET"
}
}
]
}
Multi-country targeting
Multi-country targeting is available through the API starting April 1st! This will enable advertisers to set up Ad Squads targeting any combination of countries across the world.
Multi-country targeting will help extend reach and optimize ads globally to the best audience. While setting up multi-country Ad Squads has its advantages, we do not guarentee evenly distributed delivery. If you want to test audiences between countries, then we advise that you set up separate Ad Squads.
This will launch broadly in Ads Manager in late April, and you will start to see more Ad Squads with multiple geos
objects within their targeting_spec
as this rolls out. Each country needs to be placed in a geos
entry, a targeting spec that uses multi-country targeting needs to also include a demographics
entry that incorporates a single languages
entry.
If your app is updating the targeting_spec
of the AdSquad entity you should take multi-country targeting into consideration to allow multi-country.
March 2020
We are introducing breaking changes to our API. The deprecation date will be 90 days after the announcement date, with final end of life for legacy APIs and fields two weeks after the sunset date.
Deprecation of Insight parameters dimension
and pivots
Deprecation Schedule
Announcement Date: March 20th, 2020
Sunset Date: June 20th, 2020
- The parameters
dimension
andpivots
as described in the following section will be deprecated. - The new parameter
report_dimension
offers the same functionality with the added benefit of supporting DAY, TOTAL and LIFETIME granularity. - Delivery Insights via
report_dimension
are only available from January 1st, 2020. - After the deprecation you will still be able to use
dimension
andpivots
to retrieve data finalized prior to the 20th June 2020.
New bid_strategy
attribute replaces auto_bid
and target_bid
Deprecation Schedule
Announcement Date: March 20th, 2020
Sunset Date: June 20th, 2020
- The new
bid_strategy
attribute replaces the attributesauto_bid
andtarget_bid
bid_strategy
is an enumeration that holds the bid method for the Ad Squad- Apps should be adjusted to use only
bid_strategy
on Creation and Update requests, the attributesauto_bid
/target_bid
should not be sent in requests - During the 90 day transition period
bid_strategy
will co-exist withauto_bid
andtarget_bid
- See section on bid_strategy
Deprecation of placement
in favour of placement_v2
Deprecation Schedule
Announcement Date: March 20th, 2020
Sunset Date: June 20th, 2020
- All Ad Squads are required to use
placement_v2
- The attributes at
included_content_types
andexcluded_content_types
at AdSquad level will be deprecated in favour of the attributesinclusion
andexclusion
defined inplacement_v2
- During the 90 day transition period
placement
will co-exist withplacement_v2
- See section on placement_v2 for full information on how to implement