Introduction
Welcome to the Snapchat Marketing API!
We have code samples in Curl and Python (coming soon)! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.
Upcoming Breaking Changes
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",
"conversion_window": "SWIPE_28DAY_VIEW_1DAY",
"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 Sqauds 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 languages with at least one 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
dimensionandpivotsas described in the following section will be deprecated. - The new parameter
report_dimensionoffers the same functionality with the added benefit of supporting DAY, TOTAL and LIFETIME granularity.
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_strategyattribute replaces the attributesauto_bidandtarget_bid bid_strategyis an enumeration that holds the bid method for the Ad Squad- During the 90 day transition period
bid_strategywill co-exist withauto_bidandtarget_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 - During the 90 day transition period
placementwill co-exist withplacement_v2 - See section on placement_v2 for full information on how to implement
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 identifers 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
- Get all Ad Squads under an Ad Account
- Get all Creatives under an Ad Account
- Get all Media under an Ad Account
- Get all Campaigns under an Ad Account
- Get all Ad Accounts under an Organization
- Get all Audience Segments under an Ad Account
- Get Zipcode targeting options
- Get change logs request
| 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 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:
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
-H "Authorization: Bearer meowmeowmeow"
Make sure to replace
meowmeowmeowwith your access token.
Snapchat Marketing API uses access tokens to control access and authenticate requests.
The access token should be included in all API requests to the server in the Authorization header like so:
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 Marketing API terms and the Snap Audience Match Terms.
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. They will be presented with a login screen and confirmation prompt to grant access to their account.
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 | Must be “snapchat-marketing-api” | |
| state | Optional; Will be passed through in redirect; Used for verification of request authenticity |
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 to access their account, 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 you must have an Access Token. 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.
# With shell, you can just pass the correct header with each request
curl -X POST \
-d "grant_type=refresh_token" \
-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
from pprint import pprint
from requests_oauthlib import OAuth2Session
client_id = ''
client_secret = ''
scope = ['snapchat-marketing-api']
redirect_url = 'https://www.getpostman.com/oauth2/callback'
authorize_url = 'https://accounts.snapchat.com/login/oauth2/authorize'
access_token_url = 'https://accounts.snapchat.com/login/oauth2/access_token'
protected_url = 'https://adsapi.snapchat.com/v1/me/organizations'
extra = {
'client_id': client_id,
'client_secret': client_secret,
}
oauth = OAuth2Session(client_id,
redirect_uri=redirect_url,
scope=scope)
authorization_url, state = oauth.authorization_url(authorize_url)
print 'Please go to %s and authorize access.' % authorization_url
authorization_response = raw_input('Enter the full callback URL: ')
token = oauth.fetch_token(access_token_url,
authorization_response=authorization_response,
client_secret=client_secret,
scope=scope)
print "\n\nGREAT NEWS EVERYBODY! You've got a token: "
pprint(oauth.token)
print 'Getting protected URL: {}'.format(protected_url)
resp = oauth.get(protected_url)
print resp.status_code
print resp.content
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 generate response.
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.users.me()
curl "https://adsapi.snapchat.com/v1/me"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"me": {
"id": "2f5dd7e6-fcd1-4324-8455-1ea4d96caaaa",
"updated_at": "2016-08-12T01:56:39.841Z",
"created_at": "2016-08-12T01:56:39.842Z",
"email": "honey.badger@hooli.com",
"organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"display_name": "Honey Badger"
},
"request_id": "57ae093a00ff00ff43b8c63fda390001737e616473617069736300016275696c642d34363138393265642d312d31312d32000100"
}
This endpoint retrieves the authenticated user.
HTTP Request
GET https://adsapi.snapchat.com/v1/me
Organizations
Represents a partner, ad agency or a brand. Creation requires approval from Snap Inc.
Attributes
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| name | Organization name | R |
Create an Organization
The Partner Management team creates all Organizations on behalf of partners and advertisers. Please use this form to request an organization.
Get All Organizations
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.organizations.get()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.organizations.get()
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",
"partner_orgs": {
"507d7a57-94ae-4239-8a74-e93c00aa53e6": "Cyberdyne Corp. ",
"306bb6f4-e80c-4c9c-9e39-2a4d673998a8": "Initech Inc",
"8c68b16f-03a6-4203-9480-f969fa1492d9": "Nextably App",
"5b3e970a-fa32-4a6a-a51d-bbf483a6d405": "Givester App",
"94da8871-921a-4e45-b032-8045795aecaf": "Pied Piper corp"
},
"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 logged in user has access to and the ad accounts beneath each of those organizations.
HTTP Request
GET https://adsapi.snapchat.com/v1/me/organizations?with_ad_accounts=true
Get a Specific Organization
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.organizations.get('40d6719b-da09-410b-9185-0cc9c0dfed1d')
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.
Create a Funding Source
Funding sources using credit cards 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
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 |
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.funding_sources.get()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.funding_sources.get('d150c297-55a5-44e4-a4a0-37180a694ba8')
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/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the funding source to retrieve |
Ad Accounts
An Ad Account is owned by an Organization and contains Ad Campaigns. Ad Accounts have one or more Funding Sources (aka Lines of Credit).
Attributes
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| advertiser | Name of the Advertiser | R | |
| currency | Account currency | R | Supported currencies |
| funding_source_ids | List of Funding Source IDs | R | |
| billing_type | Type of billing | R | IO, REVOLVING |
| name | Account name | R | |
| organization_id | Organization ID | R | |
| timezone | Account timezone | R | |
| type | Account type | R | DIRECT, PARTNER |
| lifetime_spend_cap_micro | Lifetime Spend Limit for Account (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 ads | O | max 32 characters |
| regulations | Required if the Ad Account will contain ads for Credit, Housing or Employment | O | { “restricted_delivery_signals”: true } |
Create an Ad Account
Ad Accounts can be created via the Snapchat Business Manager.
Get All Ad Accounts
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.ad_accounts.get()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.ad_accounts.get('d150c297-55a5-44e4-a4a0-37180a694ba8')
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/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the ad account to retrieve |
Update an Ad Account’s Lifetime Spend Cap
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.ad_accounts.get('d150c297-55a5-44e4-a4a0-37180a694ba8')
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 IO.
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 | |
| 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 | Default: BRAND_AWARENESS |
| 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” } |
** 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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()
curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_acount_id}/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 |
Get a Specific Campaign
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get('92e1c28a-a331-45b4-8c26-fd3e0eea8c39')
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/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the campaign to retrieve |
Delete a Specific Campaign
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get('92e1c28a-a331-45b4-8c26-fd3e0eea8c39')
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 | |
| 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 20000000 |
| 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, LFV, 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 |
| 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 |
| targeting | Targeting spec | R | |
| type | Ad Squad Type | R | SNAP_ADS, LENS, FILTER |
| included_content_types | Content Type to be included | O | NEWS, ENTERTAINMENT, GAMING, 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, GAMING, SCIENCE_TECHNOLOGY, BEAUTY_FASHION, MENS_LIFESTYLE, WOMENS_LIFESTYLE, GENERAL_LIFESTYLE, FOOD, SPORTS, YOUNG_BOLD |
| cap_and_exclusion_config | The frequency cap and exclusion spec | O | |
| ad_scheduling_config | The schedule for running ads | O | |
| auto_bid attribute will be deprecated please use bid_strategy | 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 attribute will be deprecated please use bid_strategy | 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. |
| 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 | 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 | 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 |
| 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 |
** Coming soon. See Reach And Frequency
Bid Strategy
Example request setting
bid_strategyandbid_micro
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adsquads":[{"campaign_id":"88b76b40-5888-4086-a028-7d18a8e82988","name":"Postman - bid_strategy test LOWEST_COST_WITH_MAX_BID", "type":"SNAP_ADS","placement_v2":{"config": "AUTOMATIC"},"optimization_goal":"IMPRESSIONS","daily_budget_micro":50000000,"bid_strategy": "LOWEST_COST_WITH_MAX_BID","bid_micro":100000,"targeting":{"regulated_content":true,"geos":[{"country_code":"us"}], "demographics":[{"age_groups":["21-24","18-20","25-34","35+"]}]},"delivery_constraint":"DAILY_BUDGET", "start_time":"2020-07-13T21:12:45Z","status":"ACTIVE"}]}'
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": "5e722f8800ff07b4e7eea281bb0001737e616473617069736300016275696c642d63333065633630652d312d3333352d300001013d",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "88539b6b-93f2-4b3a-8181-ca869cb45088",
"updated_at": "2020-03-18T14:26:16.939Z",
"created_at": "2020-03-18T14:26:16.939Z",
"name": "Postman - bid_strategy test LOWEST_COST_WITH_MAX_BID",
"status": "ACTIVE",
"campaign_id": "88b76b40-5888-4086-a028-7d18a8e82988",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": true,
"demographics": [
{
"age_groups": [
"21-24",
"18-20",
"25-34",
"35+"
]
}
],
"geos": [
{
"country_code": "us"
}
]
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 100000,
"auto_bid": false,
"target_bid": false,
"bid_strategy": "LOWEST_COST_WITH_MAX_BID",
"daily_budget_micro": 50000000,
"start_time": "2020-07-13T21:12:45.000Z",
"optimization_goal": "IMPRESSIONS",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD"
}
}
]
}
On the 20th of March 2020 we announced the deprecation of the attributes auto_bid and target_cost, please ensure that you have switched to using bid_strategy by the 20th of 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 enumaration 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 | 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:1 |
| 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 |
Optimization Goals allowed per Bid Strategy.
| bid_strategy | Optimization goals |
|---|---|
| AUTO_BID | No restrictions |
| LOWEST_COST_WITH_MAX_BID | No restrictions |
| MIN_ROAS | APP_PURCHASE |
| TARGET_COST | APP_INSTALLS, LFV, WEB_VIEW, 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 |
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.
The below table outlines the relationship between placement and placement_v2.
| placement | placement_v2 - snapchat_positions |
|---|---|
| SNAP_ADS | interstitial_user, interstitial_content, 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, INSTREAM, FEED, GAMES, 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, 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, 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.
As we roll our placement v2 fully, for all new ad squads created with Ads Manager and for ad squads whose placement was updated in Ads Manager, placement field will be set to UNSUPPORTED.
Advertisers can continue to update all other properties of such ad squads until the 20th of June 2020 but will not be able to update the placement value itself. To update the placement value you will need to set it from Ads Manager, where the ad squad placement was created/updated.
For all ad squads created via the API without using placement_v2, placement field will contain the original value and can be read and updated as usual.
config
| Value | Description |
|---|---|
| AUTOMATIC | Snapchat will chose the optimal placement for your ad. All the other properties in placement_v2 cannot 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
| Value | Description |
|---|---|
| INTERSTITIAL_USER | Ads run between friend stories. Ad Squad type must be SNAP_ADS |
| INTERSTITIAL_CONTENT | Ads run before and after stories in publisher and our stories. Ad Squad type must be SNAP_ADS |
| INSTREAM | Ads run inside i.e. in between stories in publisher and our stories. Ad Squad type must be SNAP_ADS |
| FEED | “Tile-based” ads. Currently, only in Discover feed. Ad Squad type must be SNAP_ADS. Ad type must be STORY |
| CAMERA | Ads run in Filter or Lens carousel. Ad Squad type should either be LENS or FILTER |
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
Snap Ads running as commercials via premium content bundle and Snap Games
"placement_v2":{
"config":"CUSTOM",
"platforms":[
"SNAPCHAT"
],
"snapchat_positions":[
"INSTREAM",
"GAMES"
],
"inclusion":{
"premium_content_bundle_ids":[
"c7e251af-3606-4f03-91f1-98456161655d"
]
},
Example 7
Story Ad running in the Discover feed
"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"FEED"
]
},
Example 8
Lens/Filter Ad placed in the Camera
"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"CAMERA"
]
},
Pacing Types
Validations
If pacing_type is set to ACCELERATED for accelerated delivery the following validations apply:
bid_strategymust be set to ‘LOWEST_COST_WITH_MAX_BID’bid_micromust be setauto_bidmust be falsetarget_bidmust be falseoptimization_goalmust 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 |
| LFV | Target Cost per Longform 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 |
Optimization goals PIXEL_ADD_TO_CART, PIXEL_PURCHASE and PIXEL_SIGNUP are auto enabled only for ad accounts that meet the following criteria:
- Ad Account has Snap Pixel created and installed on website
- Relevant Pixel events like ADD_TO_CART, SIGNUP and PURCHASE have been configured successfully
- Hitting a minimum of 50 attributed events per week, based on a 28d swipe and 1d view attribution window.
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_LONGFORM_VIDEO, LENS_REMOTE_WEBPAGE, LONGFORM_VIDEO, REMOTE_WEBPAGE, STORY, AD_TO_CALL, AD_TO_MESSAGE |
| SWIPES | AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LONGFORM_VIDEO, REMOTE_WEBPAGE, AD_TO_CALL, AD_TO_MESSAGE |
| APP_INSTALLS | APP_INSTALL, COLLECTION, DEEP_LINK, STORY |
| VIDEO_VIEWS | SNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LONGFORM_VIDEO, REMOTE_WEBPAGE |
| VIDEO_VIEWS_15_SEC | SNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LONGFORM_VIDEO, REMOTE_WEBPAGE |
| LFV | LONGFORM_VIDEO |
| USES | FILTER, LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_LONGFORM_VIDEO, LENS_REMOTE_WEBPAGE |
| STORY_OPENS | STORY |
| PIXEL_PAGE_VIEW | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY |
| PIXEL_ADD_TO_CART | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY |
| PIXEL_PURCHASE | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY |
| PIXEL_SIGNUP | COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY |
| 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 |
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.
| 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 | Event to be frequency capped | string | IMPRESSIONS |
| 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"
}
]
}
NOTES
- All ads under the ad squad contribute to the frequency cap.
- Only allowed for Ad Squads where optimization_goal=“IMPRESSIONS”
- Only one frequency cap rule is allowed per ad squad
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()
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 |
| 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 |
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.ad_accounts.get()
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 |
Get a Specific Ad Squad
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get('f016fc4b-5b2d-44cf-be60-b9e7955829d2')
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/<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 |
Delete an Ad Squad
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get('f016fc4b-5b2d-44cf-be60-b9e7955829d2')
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 | |
| 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_reason | 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, 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* |
Ad Type <-> Creative Type Mapping
| Ad Type | Allowed Creative Type |
|---|---|
| APP_INSTALL | APP_INSTALL |
| LONGFORM_VIDEO | LONGFORM_VIDEO |
| 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 |
| FILTER | FILTER |
| LENS | LENS |
| LENS_REMOTE_WEBPAGE | LENS_WEB_VIEW |
| LENS_APP_INSTALL | LENS_APP_INSTALL |
| LENS_DEEP_LINK | LENS_DEEP_LINK |
| LENS_LONGFORM_VIDEO | LENS_LONGFORM_VIDEO |
| COLLECTION | COLLECTION |
Create an Ad
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()
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/1933aa48-249b-4ce4-8330-dfe3977312dd/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 updated an Ad within an Ad Squad.
HTTP Request
PUT https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_squad_id | Ad Squad ID |
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()
curl "https://adsapi.snapchat.com/v1/adsquads/{ad_squad_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 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 an Ad Account
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()
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 within 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 |
Get a Specific Ad
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.ads.get('e8d6217f-32ab-400f-9e54-39a86a7963e4')
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/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the ad to retrieve |
Delete an Ad
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get('f016fc4b-5b2d-44cf-be60-b9e7955829d2')
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/<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.
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.ads.create()
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
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 type ‘IMAGE’ can be used either for app icons used in APP INSTALL creatives or as top snap media for other Snap Ads. Snapchat hosts all media on behalf of the advertiser.
Specifications for app icon:
- File type should be png
- Image should be square
- Minimum resolution: 200x200
Specifications for top snap image:
- File type should be PNG, JPG or JPEG
- Minimum image size: 1080 x 1920 pixels
- Required Image Ratio: 9:16
- Max file size: 5MB
IMAGE type top snaps are converted into 5 sec videos and rendered on the client as videos. 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"
}
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get()
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 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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get(2)
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.
HTTP Request
GET https://adsapi.snapchat.com/v1/media/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the media to retrieve |
Get Preview for a Specific Media
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get(2)
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.
HTTP Request
GET https://adsapi.snapchat.com/v1/media/<ID>/preview
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the media to retrieve |
Get Thumbnail for a Specific Media
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get(2)
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/<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.
Attributes
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| ad_account_id | Ad Account ID | R | |
| brand_name | Brand Name | R | 25 characters max |
| call_to_action | Call to Action | O | BLANK, INSTALL_NOW, WATCH, VIEW_MORE |
| 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, APP_INSTALL, LONGFORM_VIDEO, WEB_VIEW, DEEP_LINK, AD_TO_LENS, AD_TO_CALL, AD_TO_MESSAGE, PREVIEW, COMPOSITE, FILTER, LENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_LONGFORM_VIDEO, COLLECTION |
| 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) | |
| playback_type | Specifies whether the creatives within the composite auto-advance or loop | O | AUTO_ADVANCING (default), LOOPING |
| ad_product | Type of Ad Product | Required only for R&F creatives | SNAP_AD (default), LENS, FILTER |
** LENS type will be available soon with Reach and Frequency buying. Please check Reach and Frequency guide for more details.
Create a Creative
See dedicated sections for examples on how to set up and launch FILTER and LENS creatives.
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"
}
}
]
}
Creative Attachments
A basic creative is comprised of a top snap only. Snap Ads can be enhanced by using one of the following attachments:
- Long-form Video
- Web View
- App Install
Create a Creative with Long-form Video
The Long Form video attachment can be up to 1 GB in size.
Additional Attributes
The following attributes should be added to the basic creative under the property longform_video_properties.
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| video_media_id | Long-form video media ID | R |
Allowed call_to_action Values
- WATCH
- WATCH EPISODE
curl -X POST \
-d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837", "name": "Creative LFV", "type": "LONGFORM_VIDEO", "shareable": true, "call_to_action": "WATCH", "longform_video_properties": {"video_media_id": "911dd85e-1de4-4460-a8ed-2d595226da01"}}]}' \
-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": "57b015bb00ff098ecdd8a6be5c0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010c",
"creatives": [
{
"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"
}
}
}
]
}
Create a Creative with App Install
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 |
Allowed call_to_action Values
- DOWNLOAD
- INSTALL_NOW
- PLAY
- SHOP_NOW
- SIGN_UP
- USE_APP
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"
}
}
}
]
}
Mobile Measurement Partners - Setup Details
Create a Creative with Web View
The web view allows you to embed an HTML 5 web experience under the top snap. The page will be pre-cached by default. You can see more details on preloading and recommendations for optimizations here.
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 |
Allowed call_to_action Values
- APPLY_NOW
- BOOK_NOW
- BUY_TICKETS
- GET_NOW
- LISTEN
- MORE
- ORDER_NOW
- PLAY
- READ
- SHOP_NOW
- SHOW
- SHOWTIMES
- SIGN_UP
- VIEW
- WATCH
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"
}
}
}
]
}
Create a Creative with Deep Links
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.
If you want to creative which allows direct deep link open upon swipe up, you must create a creative with type DEEP_LINK
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 |
Allowed call_to_action Values
- PLAY
- SHOP_NOW
- SIGN_UP
- USE_APP
- MORE
- OPEN_APP
Icon Media specifications
- Minimum 512 x 512 px, Maximum 1080 x 1090 px
- Must be square
- Should not have any borders or padding
- Must be PNG
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}}
}
}
}
]
}
Create a Creative with Web View - Auto Fill
Setting allow_snap_javascript_sdk to true, allows forms to be filled with one tap. With this feature you can request Name, Phone Number and Email to be auto filled if the user agrees.
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", "allow_snap_javascript_sdk": "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": "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",
"allow_snap_javascript_sdk": "true"
}
}
}
]
}
Create a Story Ad Creative
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 |
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) | Cannot reference creative type COMPOSITE. Creatives of SNAP_AD, APP_INSTALL, WEB_VIEW, DEEP_LINK, LONGFORM_VIDEO are supported |
Composite creation guidelines - You can have a minimum of 3 and a maximum of 20 creatives within a composite creative - Creative types within composite can be different as long as they are of supporred type listed above - Creatives are shown to the user in the order listed at creation - This order is immutable once created - shareable value 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, "playback_type": "AUTO_ADVANCING", "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,
"playback_type": "AUTO_ADVANCING",
"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 Creative with a Lens attachment
If you want to creative which opens a lens upon swipe up, you must create a creative with type AD_TO_LENS
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 |
The Media object is auto created by Lens Studio when lenses are “Finalized”. The lens_media_id can be found by filtering the media under an ad account by media type: “LENS_PACKAGE”
Allowed call_to_action Values
- PLAY
- TRY
- SHOP_NOW
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"
}
}
}
]
}
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 Attachments
Coming soon. See Reach and Frequency Guide
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, just 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 |
| LONGFORM_VIDEO | LONGFORM_VIDEO | longform_video_properties |
| DEEP_LINK | LENS_DEEP_LINK | deep_link_properties |
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",
"allow_snap_javascript_sdk": false,
"use_immersive_mode": false,
"deep_link_urls": [],
"block_preload": false
}
}
}
}
]
}
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.
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 Swipe to Call Creative
Call attachments allow Snapchatters to swipe up to initiate a call.
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 |
Allowed call_to_action Values
- OPEN_APP
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
}
}
}
]
}
Create a Swipe to Text Creative
Text attachments allow Snapchatters to swipe up to initiate a text message.
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 |
Allowed call_to_action Values
- OPEN_APP
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"
}
}
}
]
}
Update a Creative
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get()
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","allow_snap_javascript_sdk":false,"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}]}' \
-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",
"allow_snap_javascript_sdk": false,
"use_immersive_mode": false,
"deep_link_urls": [],
"block_preload": true
},
"ad_product": "SNAP_AD"
}
}
]
}
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 |
| allow_snap_javascript_sdk | R |
| block_preload | R |
| longform_video_properties | Required |
|---|---|
| video_media_id | R |
| app_install_properties | Required |
|---|---|
| app_name | R |
| ios_app_id | R |
| android_app_url | R |
| icon_media_id | R |
| 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 |
| 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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get(2)
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 creatives.
HTTP Request
GET https://adsapi.snapchat.com/v1/creatives/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the creative to retrieve |
Get Snapcode preview for a Creative
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get(2)
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 retrieves the snapcode preview for a specific creative.
HTTP Request
GET https://adsapi.snapchat.com/v1/creatives/<ID>/snapcode
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the creative to retrieve |
Commercials
Commercials are non-skippable six-second 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 and/or Snap Games, it will automatically run as a commercial within that content.
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 3-6 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-6 seconds |
Creative requirements
Only Snap Ads can run as Commercials, the only allowed attachments are Webview, Long Form Video and AR Lens.
| Creative attribute | Value |
|---|---|
| type | AD_TO_LENS, LONGFORM_VIDEO, 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 of any other type than AD_TO_LENS, LONGFORM_VIDEO, 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, LONGFORM_VIDEO, SNAP_AD, WEB_VIEW | FULL_DURATION | The full length of the video will be unskippable |
| any | APP_INSTALL, DEEP_LINK, PREVIEW, COMPOSITE, LENS, COLLECTION,LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_LONGFORM_VIDEO | 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; US, UK, AU, CA, FR, SA, AE, DE, NO, KW and IE.
Additionally the AdSquad needs to specify either INSTREAM in snapchat_positions and the premium_content_bundle_ids targeted, or GAMES in the snapchat_positions, this specifies the content that the Commercials are shown in.
| placement_v2 attribute | Value |
|---|---|
| config | CUSTOM |
| platforms | SNAPCHAT |
| snapchat_positions | INSTREAM, GAMES |
| inclusion | premium_content_bundle_ids |
Premium Content Bundles and Snap Games
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 |
Creatives can also run as Commercials within Snap Games, this placement is achieved by specifying GAMES within snapchat_positions.
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-6+ seconds 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.
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 bundle also includes Games.
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 |
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 |
|---|---|---|---|
| demographics | List of Demographic Targets | O | |
| 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 languages with at least one entry |
| interests | List of Interest Targets | O | |
| regulated_content | Flag to mark content within the Ad Squad as Regulated Content | O | FALSE (default), TRUE |
| segments | List of Snap Audience Match Segment Targets | O | |
| enable_targeting_expansion | Boolean, enabling this allows Snapchat to expand the audience beyond the selected targeting | O | FALSE, TRUE |
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 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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.get()
curl "https://adsapi.snapchat.com/v1/targeting/options/US" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "58db128000099520da4b9237",
"targeting_option": {
"snap_ads": [
"demographics:advanced_demographics",
"demographics:age_groups",
"demographics:gender",
"devices:carrier",
"devices:connection_type",
"devices:os_type",
"geos:country",
"geos:metro",
"geos:region",
"interests:dlxc",
"interests:dlxs",
"interests:slc",
"regulated_content",
"segments:ab_segments",
"segments:engagement",
"segments:first_party",
"segments:lookalike"
]
}
}
This endpoint retrieves all targeting options available for the specified country code.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/options/{country_code}
Parameters
| Parameter | Default | Description |
|---|---|---|
| country_code | ISO ALPHA-2 Country Code (lowercase) |
Demographics
Demographics targeting allows an advertiser to find a user based on a variety of criteria.
Demographics - Age Groups
Get Age Group Targeting Options
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.demographics.age_groups()
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 also 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 | 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 | 35 - 49 |
See the Targeting Spec Examples for usage examples.
Demographics - Gender
Get Gender Targeting Options
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.demographics.genders()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.demographics.languages()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.demographics.advanced_demographics()
curl "https://adsapi.snapchat.com/v1/targeting/demographics/advanced_demographics" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "57d1cb6900ff0c21bb32e920a00001737e616473617069736300016275696c642d66333735626434642d312d31332d3700010111",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"advanced_demographics": {
"name": "College Graduates",
"id": "DLXD_100"
}
},
{
"sub_request_status": "SUCCESS",
"advanced_demographics": {
"name": "Married People",
"id": "DLXD_300"
}
}
]
}
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.device.connection_types()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.device.os_types()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.device.os_types()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.device.carriers()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.device.marketingname()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.geo.countries()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.geo.regions(country_code='us')
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.geo.metros(country_code='us')
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.geo.zipcode()
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 or Oracle Datalogix (DLX) Interests.
Interests - Snap Lifestyle Categories
Interest targeting is based on Snap Lifestyle Categories.
Get Snap Lifestyle Categories Targeting Options
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.interests.scls()
curl "https://adsapi.snapchat.com/v1/targeting/interests/scls"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57acea61000484407b52009b",
"targeting_dimensions": [
{
"sub_request_status": "success",
"scls": {
"name": "Fashion & Style Gurus",
"id": "SLC_7"
}
},
{
"sub_request_status": "success",
"scls": {
"name": "Film & TV Fans",
"id": "SLC_8"
}
},
{
"sub_request_status": "success",
"scls": {
"name": "Comedy Fans",
"id": "SLC_36_8"
}
},
{
"sub_request_status": "success",
"scls": {
"name": "Serious Gamers",
"id": "SLC_45_13"
}
},
{
"sub_request_status": "success",
"scls": {
"name": "Music Fans",
"id": "SLC_19"
}
}
]
}
This endpoint retrieves the list of Snap Lifestyle Categories targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/interests/scls
Get Snap Lifestyle Categories By Country
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.interests.scls()
curl "https://adsapi.snapchat.com/v1/targeting/interests/us/scls"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5bce471800ff020b339480a1fc0001737e616473617069736300016275696c642d64636363373137632d312d3231342d3000010141",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_1",
"name": "Adventure Seekers",
"path": "/Adventure Seekers",
"parentId": "SLC_0",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_10",
"name": "Do-It-Yourselfers",
"path": "/Do-It-Yourselfers",
"parentId": "SLC_0",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_100",
"name": "Talent & Competition Show Fans",
"path": "/Film & TV Fans/Talent & Competition Show Fans",
"parentId": "SLC_12",
"source": "SNAPCHAT"
}
},
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_101",
"name": "Talk Show Fans",
"path": "/Film & TV Fans/Talk Show Fans",
"parentId": "SLC_12",
"source": "SNAPCHAT"
}
},
<<snip>>
{
"sub_request_status": "SUCCESS",
"scls": {
"id": "SLC_102",
"name": "Teen & Young Adult Genre Fans",
"path": "/Film & TV Fans/Teen & Young Adult Genre Fans",
"parentId": "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/interests/<targeting-country-code>/scls
Interests - Oracle Datalogix (DLX)
Interest targeting can also be based on Oracle Datalogix (DLX) Interests.
Get Oracle Datalogix DLXS Interest Targeting Options
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.interests.dlxs()
curl "https://adsapi.snapchat.com/v1/targeting/interests/dlxs"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57acea61000484407b52009b",
"targeting_dimensions": [
{
"sub_request_status": "success",
"dlxs": {
"name": "Apparel Shoppers",
"id": "DLXS_1"
}
},
{
"sub_request_status": "success",
"dlxs": {
"name": "Small & Mid-size SUV Shoppers",
"id": "DLXS_100"
}
}
]
}
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.interests.dlxc()
curl "https://adsapi.snapchat.com/v1/targeting/interests/dlxc"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57acea61000484407b52009b",
"targeting_dimensions": [
{
"sub_request_status": "success",
"dlxc": {
"name": "Home Movie Viewers (Action)",
"id": "DLXC_101"
}
},
{
"sub_request_status": "success",
"dlxc": {
"name": "TV Viewers (Variety Shows)",
"id": "DLXC_133"
}
}
]
}
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.interests.dlxp()
curl "https://adsapi.snapchat.com/v1/targeting/interests/dlxp"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "590850dd00ff05d022b1d7a5c50001737e616473617069736300016275696c642d62663930383438312d312d36322d320001013e",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"dlxp": {
"id": "DLXP_107",
"name": "Ford Dealers"
}
},
{
"sub_request_status": "SUCCESS",
"dlxp": {
"id": "DLXP_108",
"name": "Foreign Vehicle Dealers"
}
},
{
"sub_request_status": "SUCCESS",
"dlxp": {
"id": "DLXP_109",
"name": "Honda Dealers"
}
}
]
}
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.interests.nln()
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
Interests - Placed Visitation Segments
Interest targeting based on Placed Visitation Segments.
Get Placed Visitation Segments
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.interests.plcs()
curl "https://adsapi.snapchat.com/v1/targeting/interests/plc"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b9aa65c00ff02fdc17b1cdd170001737e616473617069736300016275696c642d33346634346232622d312d3230302d3200010158",
"paging": {},
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"plc": {
"id": "PLC_101",
"name": "Auto Dealer Visitors",
"path": "/Auto Dealer Visitors",
"source": "PLACED"
}
},
{
"sub_request_status": "SUCCESS",
"plc": {
"id": "PLC_102",
"name": "Asian Vehicle Dealers",
"path": "/Auto Dealer Visitors/Asian Vehicle Dealers",
"parent_id": "PLC_101",
"source": "PLACED"
}
},
{
"sub_request_status": "SUCCESS",
"plc": {
"id": "PLC_103",
"name": "Big3 Vehicle Dealers",
"path": "/Auto Dealer Visitors/Big3 Vehicle Dealers",
"parent_id": "PLC_101",
"source": "PLACED"
}
},
<snip>
{
"sub_request_status": "SUCCESS",
"plc": {
"id": "PLC_618",
"name": "Marriott Chain Hotels",
"path": "/Travel Venue Visitors/Hotels/Marriott Chain Hotels",
"parent_id": "PLC_605",
"source": "PLACED"
}
}
]
}
This endpoint retrieves the list of Placed Visitation Segments for targeting.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/interests/plc
Location
Location targeting allows an advertiser to target users based on their location.
Location - Categories
Get Location Categories Targeting Options
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.location.catgeories()
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 |
Snap Audience Match
Snap Audience Match (SAM) allows 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 | |
| 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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
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 Snap Audience Match 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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
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 Snap Audience Match 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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
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 "https://adsapi.snapchat.com/v1/segments/{segment_id}"
-H "Authorization: Bearer meowmeowmeow"
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 or mobile identifier.
This endpoint will add users to the specified Snap Audience Match 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
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 |
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 country code, and exclude any non-numeric characters such as whitespace, parentheses, ‘+’, or ‘-’
Hashing Identifiers
Hash raw identifiers with lowercase hex SHA256 format.
Adding Users (Single-Key)
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
curl -X POST \
-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.
Removing Users
Users can also be removed from the segment at any time. The API supports matching via email or mobile identifier.
This endpoint will remove users from the specified Snap Audience Match 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
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 |
HTTP Request
DELETE https://adsapi.snapchat.com/v1/segments/{segment_id}/users
Parameters
| Parameter | Default | Description |
|---|---|---|
| segment_id | Segment ID |
Removing Users (Single-Key)
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
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 Snap Audience Match 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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
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 |
SAM - Lookalikes
A lookalike segment can be created from a first-party seed Snap Audience Match Segment. The segment can be used to target or exclude a specific group of users that “behave like” the seed audience segment.
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 |
|---|---|---|---|
| country | ISO-2 Country Code | R | |
| seed_segment_id | Seed Audience Segment ID | R | |
| type | The type of Lookalike to be created | O | BALANCE (default), SIMILARITY, REACH |
Create an Lookalike Segment
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
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 Snap Audience Match 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"
}, {
"country_code": "us",
"region_id": ["3", "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 SAM 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 SAM 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"
}
]
}
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get()
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/<ID>/audience_size_v2
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the ad account |
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/<ID>/audience_size_v2
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the ad squad |
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.
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 |
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
}
},
[[[ snip ]]]
{
"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 |
| 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, total |
| limit | The limit parameter specifies how many entities should be returned per page | O | integer, max 200 |
Response Parameters
| Attribute | Description |
|---|---|
| finalized_data_end_time | This defines the time up until when 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. |
| 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
The following metrics are available for specific Snap Ads with Attachments and/or at TOTAL granularity. Italicized metrics are available in the real-time stats pipeline. Non-italicized are available in real-time for the granularities DAY and HOUR, 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 |
| position_impressions | STORY | # the impression number for this story ad position |
| position_uniques | STORY | # the unique viewer numbers for this story ad position |
| position_frequency | STORY | # the frequency 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 |
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_start_checkout | Any | # of attributed “START_CHECKOUT” conversion events |
| conversion_add_cart | Any | # of attributed “ADD_CART” conversion events |
| conversion_view_content | Any | # of attributed “VIEW_CONTENT” conversion events |
| conversion_add_billing | Any | # of attributed “ADD_BILLING” conversion events |
| conversion_sign_ups | Any | # of attributed “SIGN_UP” conversion events |
| conversion_searches | Any | # of attributed “SEARCH” conversion events |
| conversion_level_completes | Any | # of attributed “LEVEL_COMPLETE” conversion events |
| conversion_app_opens | Any | # of attributed “APP_OPEN” conversion events |
| conversion_page_views | Any | # of attributed “PAGE_VIEW” conversion events |
| conversion_subscribe | Any | # of attributed “SUBSCRIBE” conversion events |
| conversion_ad_click | Any | # of attributed “AD_CLICK” conversion events |
| conversion_ad_view | Any | # of attributed “AD_VIEW” conversion events |
| conversion_complete_tutorial | Any | # of attributed “COMPLETE_TUTORIAL” conversion events |
| conversion_invite | Any | # of attributed “INVITE” conversion events |
| conversion_login | Any | # of attributed “LOGIN” conversion events |
| conversion_share | Any | # of attributed “SHARE” conversion events |
| conversion_reserve | Any | # of attributed “RESERVE” conversion events |
| conversion_achievement_unlocked | Any | # of attributed “ACHIEVEMENT_UNLOCKED” conversion events |
| conversion_add_to_wishlist | Any | # of attributed “ADD_TO_WISHLIST” conversion events |
| conversion_spend_credits | Any | # of attributed “SPENT_CREDITS” conversion events |
| conversion_rate | Any | # of attributed “RATE” conversion events |
| conversion_start_trial | Any | # of attributed “START_TRIAL” conversion events |
| conversion_list_view | Any | # of attributed “LIST_VIEW” conversion events |
| custom_event_1 | Any | # of attributed “CUSTOM_EVENT_1” conversion events |
| custom_event_2 | Any | # of attributed “CUSTOM_EVENT_2” conversion events |
| custom_event_3 | Any | # of attributed “CUSTOM_EVENT_3” conversion events |
| custom_event_4 | Any | # of attributed “CUSTOM_EVENT_4” conversion events |
| custom_event_5 | Any | # of attributed “CUSTOM_EVENT_5” conversion events |
Conversion breakout
The parameter conversion_source_types provides breakout of conversions based on where the conversions occurred.
| Parameter | Metric | Description |
|---|---|---|
| total | conversion_purchases | All purchase events |
| web | conversion_purchases_web | Purchases from a web browser |
| app | conversion_purchases_app | Purchases from an app |
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 | |||||
| conversion_purchases | |||||
| conversion_purchases_value | |||||
| conversion_save | |||||
| conversion_start_checkout | |||||
| conversion_add_cart | |||||
| conversion_view_content | |||||
| conversion_add_billing | |||||
| conversion_signups | |||||
| conversion_searches | |||||
| conversion_level_completes | |||||
| conversion_app_opens | |||||
| conversion_page_views | |||||
| conversion_subscribe | |||||
| conversion_ad_click | |||||
| conversion_ad_view | |||||
| conversion_complete_tutorial | |||||
| conversion_invite | |||||
| conversion_login | |||||
| conversion_share | |||||
| conversion_reserve | |||||
| conversion_achievement_unlocked | |||||
| conversion_add_to_wishlist | |||||
| conversion_spend_credits | |||||
| conversion_rate | |||||
| conversion_start_trial | |||||
| conversion_list_view | |||||
| custom_event_1 | |||||
| custom_event_2 | |||||
| custom_event_3 | |||||
| custom_event_4 | |||||
| custom_event_5 | |||||
| attachment_frequency | YES | YES | YES | Not supported. Use LIFETIME | |
| attachment_uniques | |||||
| frequency | |||||
| uniques |
Example for All Metrics
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get('123').stats()
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get('123').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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.adsquads.get('123').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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.ads.get('123').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 available from January 1st, 2020. DAILY, TOTAL, and LIFETIME are supported.
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.
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 |
|---|---|---|
| Geo | country | Metrics broken down by ISO country code |
| region | US-Only. Metrics broken down by two letter state abbreviation | |
| dma | US-Only. Metrics broken down by DMA numeric code | |
| Demographic | gender | Metrics broken down by gender; may be combined with age as gender,age |
| age | Metrics broken down by age buckets; may be combined with gender as age,gender | |
| User Interest | lifestyle_category | Snapchat User Lifestyle Interest |
| Device | os | Device Operating System |
| make | Device Make (e.g., Apple, Samsung) |
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.
| Metric | API field | Description |
|---|---|---|
| Paid Impressions | impressions | Impression Count |
| Swipe Ups | impressions | 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 |
| 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 |
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. The new parameter report_dimension is described in Reporting Insights and Dimensions.
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.ads.get('123').stats()
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.
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 and Creative. 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 |
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 APIs are rate limit to ensure infrastructure stability.
Every request to the API will return 3 headers in the response:
| Header | Type | Description |
|---|---|---|
| X-Rate-Limit-Limit | Integer | Total number of requests allowed for the given time period |
| X-Rate-Limit-Remaining | Integer | Number of requests remaining for the given time period |
| X-Rate-Limit-Reset | Unix Timestamp (UTC) | Timestamp when rate limit resets (milli-seconds) |
429 Error Code
If you reach the rate limit, you will start receiving an HTTP 429 Too Many Requests response.
Audience Filters
Audience Filters are a way for advertisers to bid on Filters targeting Snapchatters based on age, gender, interest groups and more.
Audience Filters:
- Allow advertisers to buy filters targeting an audience using all the same targeting capabilities as Snap Ads
- Are auction-based instead of being fixed price
- Available in all markets where Snap Ads are available
Audience Filter Implementation Details
- Advertiser will create a filter with a target audience and a cost-per-use bid (e.g. $0.20 per use).
- When a user opens the filter carousel, Snapchat will run a second price auction containing all the filters targeting that user.
- The filter that wins the auction will be inserted into the filter section of the carousel.
- If the filter is swiped on/over by the user, then the advertiser will be billed for the impression. An advertiser will only be billed once per filter carousel session: while a user can swipe back and forth over the filter during the session, the advertiser will only be billed for the first swipe in the session.
- If a user either posts the filter to their story or sends the filter 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": "Audience Filter 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": "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": "2016-08-11T22:00:00.000Z"
}
}
]
}
This will create a campaign within a specified ad account. Filter Ad Squads and Snap Ads Ad Squads can co-exist in the same campaign.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/campaigns
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_account_id | Ad Account ID |
Create an Audience Filter 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 or bid_micro must be set) | true/false |
| start_time | Start time | R | |
| end_time | End time | R | |
| optimization_goal | Optimization Goal | R | USES, 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 | FILTER |
| targeting | Targeting spec | R | Any valid targeting options |
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adsquads": [{"name": "Audience Filter Ad Squad", "status": "ACTIVE", "campaign_id": "a09f983a-06ac-4081-9659-7bc9e1cd6888", "type": "FILTER", "placement_v2": {"config": "CUSTOM","platforms": ["SNAPCHAT"],"snapchat_positions": ["CAMERA"]}, "billing_event": "IMPRESSION", "bid_micro": 10000000, "daily_budget_micro": 100000000,"start_time": "2017-08-15T12:00:00.000-07:00", "end_time": "2017-08-19T12:00:00.000-07:00", "optimization_goal": "USES", "targeting": {"demographics": [{"gender": "FEMALE","age_groups": ["18-20","21-24","25-34"]}],"interests": [{"category_id": ["SLC_7", "SLC_8"]}],"geos": [{"country_code": "us"}]}}]}' \
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": "58e3021b00ff01d8999153081c0001737e7465616d6b6f363139000161646d616e616765722d6170693a6f64672d637275642d74657374696e672d3300",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "aeeb055a-0f8a-4e8e-a9fb-381d5395471e",
"updated_at": "2017-08-15T20:48:39.373Z",
"created_at": "2017-08-15T20:48:39.373Z",
"created_by_app_id": "e4892f56-5303-4782-bfb2-14ebe02c6401",
"last_updated_by_app_id": "e4892f56-5303-4782-bfb2-14ebe02c6401",
"name": "Audience Filter Ad Squad",
"status": "ACTIVE",
"campaign_id": "dc210fba-e12a-43ad-901a-74ce190c13c8",
"type": "FILTER",
"targeting": {
"regulated_content": false,
"demographics": [
{
"age_groups": [
"18-20",
"21-24",
"25-34"
],
"gender": "FEMALE"
}
],
"interests": [
{
"category_id": [
"SLC_7",
"SLC_8"
]
}
],
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"CAMERA"
]
},
"billing_event": "IMPRESSION",
"bid_micro": 10000000,
"daily_budget_micro": 100000000,
"start_time": "2017-08-15T19:00:00.000Z",
"end_time": "2017-08-19T19:00:00.000Z",
"optimization_goal": "USES",
"delivery_constraint": "DAILY_BUDGET"
}
}
]
}
This creates an Ad Squad within a Campaign. For Audience Filter Ad Squads:
- placement_v2.config must be set to ‘CUSTOM’
- placement_v2.platforms must be set to ‘SNAPCHAT’
- placement_v2.snapchat_positions must be set to ‘CAMERA’
- billing_event must be set to ‘IMPRESSION’
- optimization_goal can only be set to ‘USES’
- Audience Filter ad squads contribute towards daily campaign budgets.
- All targeting options available for Snap Ads are also available for Audience Filter Ad Squads. SAM and Lookalike targeting are also allowed.
HTTP Request
POST https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads
Parameters
| Parameter | Default | Description |
|---|---|---|
| campaign_id | Campaign ID |
Create the Media
Media for an Audience Filter is a single image that contains the art that can be overlayed on snaps. This image:
- Should be at least 50% transparent.
- File type should be ‘png’.
- Dimensions should be 1080x1920 or 1080x2340.
- File size should be less than 300kb.
- Should not contain hashtags, urls, call to action and must not be a photo.
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 | IMAGE |
curl -X POST \
-d '{"media": [{"name":"Audience Filter Media", "type":"IMAGE","ad_account_id":"8adc3db7-8148-4fbf-999c-8d2266369888"}]}' \
-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": "Audience Filter Media",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369888",
"type": "IMAGE",
"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
curl -X POST -H 'content-type: multipart/form-data' -F 'file=@"/files/filter.png";filename="filter.png"' \
-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": "bc4e0b61-7e7b-4273-bca1-9fcba53f141d",
"updated_at": "2017-04-04T04:23:37.092Z",
"created_at": "2017-04-04T03:56:55.531Z",
"name": "Audience Filter Media",
"ad_account_id": "53ab6278-3b05-4e05-af83-ca5069b64e90",
"type": "IMAGE",
"media_status": "READY",
"file_name": "filter.png",
"download_link": "https://storage.googleapis.com/ad-manager-creatives/bc4e0b61-7e7b-4273-bca1-9fcba53f179d/75216cc9-909e-42e4-aacc-1024.png"
},
"request_status": "SUCCESS",
"request_id": "58e31fc400ff01067fee87652c0001737e7465616d6b6f363139000161646d616e616765722d6170693a6f64672d6372"
}
This endpoint receives the actual file 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 |
Create the Creative
Attributes
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| ad_account_id | Ad Account ID | R | |
| brand_name | Brand Name | R | 25 characters max |
| call_to_action | Call to Action | O | Must not be set for type=FILTER |
| headline | Headline | R (required but not displayed for audience filters) | 34 characters max |
| shareable | Allow Users to Share with Friends | O | Not relevant for type=FILTER |
| name | Creative name | R | |
| top_snap_media_id | Media ID that contains the filter art | R | |
| top_snap_crop_position | Top Snap Crop Position | O | Not relevant for type=FILTER |
| type | Creative Type | R | FILTER |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "f84d671c-dec8-4411-b812-050e76c36640", "name": "Audience Filter Creative", "headline": "Audience Filters Inc", "brand_name": "Audience Filters Inc", "top_snap_media_id": "1e8f430c-520d-40f1-b141-2e5ef0c30618", "type": "FILTER"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d88/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "58e3394300ff0608052c604bc90001737e7465616d6b6f363139000161646d616e616765722d6170693a6f64672d637275642d74657374696e672d33",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "225afc2b-0556-4050-9f85-cf3ce222fc88",
"updated_at": "2017-08-04T06:12:19.592Z",
"created_at": "2017-08-04T06:12:19.592Z",
"name": "Audience Filter Creative",
"brand_name": "Audience Filters Inc",
"headline": "Audience Filters Inc",
"ad_account_id": "f84d671c-dec8-4411-b812-050e76c36640",
"type": "FILTER",
"review_status": "PENDING_REVIEW",
"shareable": false,
"top_snap_media_id": "1e8f430c-520d-40f1-b141-2e5ef0c30618",
"top_snap_crop_position": "OPTIMIZED",
"ad_product": "FILTER"
}
}
]
}
For Audience Filter Creatives:
- call_to_action must not be set
- type must be set to FILTER
Create the Ad
Attributes
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| ad_squad_id | Ad Squad ID | R | |
| creative_id | Creative ID | R | |
| name | Ad name | R | |
| 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 |
| type | Ad type | R | FILTER |
curl -X POST \
-d '{"ads":[{"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe", "creative_id":"c1e6e929-acec-466f-b023-852b8cacc18f", "name": "Ad One", "type": "FILTER", "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": "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": "ACTIVE",
"type": "FILTER"
}
}
]
}
For Audience Filter Ads:
- type must be set to FILTER.
- Creative must be a creative of type=FILTER as well
HTTP Request
POST https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_squad_id | Ad Squad ID |
Reporting
Stats fields for Audience filters
| 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 |
Lenses
Lenses AR experiences are a powerful and memorable way to connect with consumers on a massive scale using augmented reality.
Lens Implementation Details
- 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 in question via Lens Studio.
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_LONGFORM_VIDEO, 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 | SIGN_UP, DOWNLOAD, ORDER_NOW, USE_APP, INSTALL_NOW, GET_NOW, PLAY, SHOP_NOW |
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 |
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 the Creative - 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 | SHOP_NOW, PLAY, OPEN_APP, MORE, TRY, USE_APP |
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 |
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"