Introduction
Welcome to the Snapchat Marketing API!
Code references are presented in the main column and examples in CURL can be viewed in the dark area to the right.
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 Squads has its advantages, we do not guarentee evenly distributed delivery. If you want to test audiences between countries, then we advise that you set up separate Ad Squads.
This will launch broadly in Ads Manager in late April, and you will start to see more Ad Squads with multiple geos
objects within their targeting_spec
as this rolls out. Each country needs to be placed in a geos
entry, a targeting spec that uses multi-country targeting needs to also include a demographics
entry that incorporates a single languages
entry.
If your app is updating the targeting_spec
of the AdSquad entity you should take multi-country targeting into consideration to allow multi-country.
March 2020
We are introducing breaking changes to our API. The deprecation date will be 90 days after the announcement date, with final end of life for legacy APIs and fields two weeks after the sunset date.
Deprecation of Insight parameters dimension
and pivots
Deprecation Schedule
Announcement Date: March 20th, 2020
Sunset Date: June 20th, 2020
- The parameters
dimension
andpivots
as described in the following section will be deprecated. - The new parameter
report_dimension
offers the same functionality with the added benefit of supporting DAY, TOTAL and LIFETIME granularity. - Delivery Insights via
report_dimension
are only available from January 1st, 2020. - After the deprecation you will still be able to use
dimension
andpivots
to retrieve data finalized prior to the 20th June 2020.
New bid_strategy
attribute replaces auto_bid
and target_bid
Deprecation Schedule
Announcement Date: March 20th, 2020
Sunset Date: June 20th, 2020
- The new
bid_strategy
attribute replaces the attributesauto_bid
andtarget_bid
bid_strategy
is an enumeration that holds the bid method for the Ad Squad- Apps should be adjusted to use only
bid_strategy
on Creation and Update requests, the attributesauto_bid
/target_bid
should not be sent in requests - During the 90 day transition period
bid_strategy
will co-exist withauto_bid
andtarget_bid
- See section on bid_strategy
Deprecation of placement
in favour of placement_v2
Deprecation Schedule
Announcement Date: March 20th, 2020
Sunset Date: June 20th, 2020
- All Ad Squads are required to use
placement_v2
- The attributes at
included_content_types
andexcluded_content_types
at AdSquad level will be deprecated in favour of the attributesinclusion
andexclusion
defined inplacement_v2
- During the 90 day transition period
placement
will co-exist withplacement_v2
- See section on placement_v2 for full information on how to implement
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 (USD, CAD, GBP, EUR, AUD) is equal to 1,000,000 micro-currency.
Examples
Currency Value | Micro-Currency Value |
---|---|
$1.00 | 1000000 |
$0.50 | 500000 |
$50,000 | 50000000000 |
$123.45 | 123450000 |
Authentication
To authorize, use this code:
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
meowmeowmeow
with 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. The Access Token is valid for 1800 seconds = 30 minutes.
# With shell, you can just pass the correct header with each request
curl -X POST \
-d "grant_type=authorization_code" \
-d "client_id={client_id}" \
-d "client_secret={client_secret}" \
-d "code={code}" \
-d "redirect_uri={redirect_uri}"
https://accounts.snapchat.com/login/oauth2/access_token
The above command returns JSON structured like this:
{
"expires_in": 1800,
"token_type": "Bearer",
"refresh_token": "32eb12f037712a6b60404d6d9c170ee9ae4d5b9936c73dd03c23fffff1213cb3",
"access_token": "0.MGQCxyz123"
}
HTTP Request
POST https://accounts.snapchat.com/login/oauth2/access_token
Parameters
Parameter | Default | Description |
---|---|---|
client_id | Client ID | |
client_secret | Client Secret | |
code | One-time Use Code from User Redirect or Refresh Token | |
grant_type | “authorization_code” | |
redirect_uri | URLEncoded Redirect URI. Required when grant_type=authorization_code. Must match redirect_uri from the previous /authorize call |
Refresh the Access Token
Access Tokens are short-lived. When you receive a 401 token expired error, you should use your Refresh Token to generate a new Access Token and retry the request. Many standard OAuth2 libraries can handle this expiration-retry pattern for you.
# With shell, you can just pass the correct header with each request
curl -X POST \
-d "refresh_token={refresh_token}" \
-d "client_id={client_id}" \
-d "client_secret={client_secret}" \
-d "grant_type=refresh_token" \
https://accounts.snapchat.com/login/oauth2/access_token
The above command returns JSON structured like this:
{
"access_token": "0.MGQCxyz123",
"token_type": "Bearer",
"expires_in": 1800,
"refresh_token": "32eb12f037712a6b60404d6d9c170ee9ae4d5b9936c73dd03c23fffff1213cb3",
"scope": "snapchat-marketing-api"
}
HTTP Request
POST https://accounts.snapchat.com/login/oauth2/access_token
Parameters
Parameter | Default | Description |
---|---|---|
client_id | Client ID | |
client_secret | Client Secret | |
grant_type | “refresh_token” | |
refresh_token | The refresh token you received when generating your first access token |
Full Web Flow Example
1. Open the authorize link in a browser:
https://accounts.snapchat.com/login/oauth2/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope=snapchat-marketing-api&state=wmKkg0TWgppW8PTBZ20sldUmF7hwvU
2. Login & Authorize via UI
3. Locate "code" query parameter in the redirect
4. Exchange code for access token + refresh token
curl -X POST \
-d "code={one_time_use_code}" \
-d "client_id={client_id}" \
-d "client_secret={client_secret}" \
-d "grant_type=authorization_code" \
-d "redirect_uri=redirect_uri"
https://accounts.snapchat.com/login/oauth2/access_token
5. When the access token expires, generate a new one using the refresh token
curl -X POST \
-d "refresh_token={refresh_token}" \
-d "client_id={client_id}" \
-d "client_secret={client_secret}" \
-d "grant_type=refresh_token" \
https://accounts.snapchat.com/login/oauth2/access_token
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 response, currently the expiry is 1800 seconds = 30 minutes.
When a request is attempted with an expired token, the response will be a 401 Not Authorized with additional headers.
< HTTP/1.1 401 Unauthorized
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Headers: Content-Type, Authorization
< WWW-Authenticate: Bearer error="invalid_token", error_description="The access token expired"
< X-Cloud-Trace-Context: e0fdbe35c49ad238e624635b6a45813d;o=1
< Date: Mon, 15 Aug 2016 21:10:01 GMT
< Content-Type: text/html
< Server: Google Frontend
< Content-Length: 0
User
Get Authenicated User
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
An Organization represents an brand, partner or ad agency, creation happens via Snap Business Manager.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
name | Organization name | R |
Create an Organization
The only way to set up an Organization is to sign up for a Business account with Snap Business Manager.
Get All Organizations
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",
"accepted_term_version": "8",
"is_agency": true,
"configuration_settings": {
"notifications_enabled": true
},
"type": "ENTERPRISE",
"state": "ACTIVE",
"roles": [
"member"
],
"ad_accounts": [
{
"id": "8b8e40af-fc64-455d-925b-ca80f7af6914",
"updated_at": "2018-03-07T23:39:20.469Z",
"created_at": "2018-03-27T23:42:43.513Z",
"name": "Hooli Originals",
"type": "PARTNER",
"status": "ACTIVE",
"currency": "USD",
"timezone": "America/Los_Angeles",
"roles": [
"reports"
]
},
{
"id": "497979f0-ea17-4971-8288-054883f1caca",
"updated_at": "2017-01-04T22:58:38.179Z",
"created_at": "2018-09-07T14:41:36.002Z",
"name": "Pied piper Test Account",
"type": "PARTNER",
"status": "ACTIVE",
"currency": "USD",
"timezone": "America/Los_Angeles",
"roles": [
"admin"
]
},
{
"id": "22ada972-f2aa-4d06-a45a-a7a80f53ae34",
"updated_at": "2017-07-28T02:32:03.914Z",
"created_at": "2017-12-08T21:56:57.305Z",
"name": "Initech Corp",
"type": "PARTNER",
"status": "ACTIVE",
"currency": "USD",
"timezone": "America/Los_Angeles",
"roles": [
"creative"
]
}
],
"my_display_name": "Honey Badger",
"my_invited_email": "honey.badget@hooli.com",
"my_member_id": "8454ada6-cec8-4e97-a0a7-c0b262c4137b"
}
}
]
}
This endpoint retrieves all organizations the user has access to and the ad accounts beneath each of those organizations. The roles attribute holds shows the role that the user holds within the Ad Account in question, Ad Account roles are explain in the Roles section.
HTTP Request
GET https://adsapi.snapchat.com/v1/me/organizations?with_ad_accounts=true
Get a Specific Organization
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. Funding sources are assigned to an Ad Account in order to pay for the activity within that Ad Account.
Attributes
Attribute | Description | Possible Values | Supported for type |
---|---|---|---|
id | ID of the funding source | ALL | |
created_at | Date of creation | ALL | |
updated_at | Date of last update | ALL | |
type | Funding Source type | LINE_OF_CREDIT, CREDIT_CARD, COUPON, PAYPAL | ALL |
status | Status of the funding source | ACTIVE, REDEEMED, SPENT, EXPIRED, DELETED | ALL |
budget_spent_micro | Budget Spent (micro-currency) | LINE_OF_CREDIT | |
currency | Account currency | USD, CAD, GBP, AUD, EUR | LINE_OF_CREDIT, COUPON |
total_budget_micro | Total Budget (micro-currency) | LINE_OF_CREDIT, CREDIT_CARD | |
budget_spent_micro | Budget spent (micro-currency) | LINE_OF_CREDIT, CREDIT_CARD | |
available_credit_micro | Total available credit | LINE_OF_CREDIT, COUPON | |
card_type | Credit Card Type | AMEX, DINERS_CLUB, DISCOVER, JCB, MAESTRO, MASTERCARD, VISA, UNKNOWN | CREDIT_CARD |
name | Name of the Credit Card | ALL | |
last_4 | Last 4 digits of the Credit Card | CREDIT_CARD | |
expiration_year | Expiration year of the Credit Card | CREDIT_CARD | |
expiration_month | Expiration month of the Credit Card | CREDIT_CARD | |
daily_spend_limit_micro | Daily spend limit for Credit Card (micro-currency) | CREDIT_CARD | |
daily_spend_limit_currency | Currency for the daily_spend_limit_micro | USD, CAD, GBP, AUD, EUR | CREDIT_CARD |
value_micro | Value of the COUPON (micro-currency) | COUPON | |
start_date | Start date of the COUPON | COUPON | |
end_date | End date of the COUPON | COUPON | |
Email associated with Paypal | PAYPAL |
Create a Funding Source
Funding sources using credit cards and PayPal can be set up using Business Manager
The Partner Manager team creates all other types of Funding Sources on behalf of partners and advertisers. Please reach out to your partner manager for assistance.
Get All Funding Sources
curl "https://adsapi.snapchat.com/v1/organizations/{organization_id}/fundingsources" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "59236a2500ff05763ff95f2fcc0001737e7465616d6b6f363139000161646d616e616765722d6170693a6b6162726168616d0001011d",
"fundingsources": [
{
"sub_request_status": "SUCCESS",
"fundingsource": {
"id": "1e224e75-3883-42cf-a5d9-ce505945d2d3",
"updated_at": "2017-05-22T22:46:30.917Z",
"created_at": "2017-05-22T22:46:30.917Z",
"type": "CREDIT_CARD",
"card_type": "DISCOVER",
"name" : "My DISCOVER card",
"last_4": "1100",
"expiration_month": "12",
"expiration_year": "2020",
"daily_spend_limit_micro": 25000000,
"daily_spend_currency": "USD"
}
},
{
"sub_request_status": "SUCCESS",
"fundingsource": {
"id": "9d111fbf-da5f-4526-9e7b-226f847b3d7e",
"updated_at": "2017-05-22T22:46:30.920Z",
"created_at": "2017-05-22T22:46:30.920Z",
"type": "LINE_OF_CREDIT",
"available_credit_micro": 2000000000,
"currency": "USD",
"total_budget_micro": 10000000000,
"status": "ACTIVE",
"credit_account_type": "MANAGED",
"budget_spent_micro": 8000000000
}
},
{
"sub_request_status": "SUCCESS",
"fundingsource": {
"id": "d24b4011-3560-47ea-86fa-0ed14c6b90d4",
"updated_at": "2017-05-22T22:46:30.920Z",
"created_at": "2017-05-22T22:46:30.920Z",
"type": "COUPON",
"available_credit_micro": 10000000000,
"currency": "EUR",
"value_micro": 10000000000,
"status": "REDEEMED",
"start_date": "2017-05-22T22:46:30.923Z",
"end_date": "2017-05-22T22:46:30.923Z"
}
}
]
}
This endpoint retrieves all funding sources for the specified Organization.
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/fundingsources
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Get a Specific Funding Source
curl "https://adsapi.snapchat.com/v1/fundingsources/e703eb9f-8eac-4eda-a9c7-deec3935222d" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b000ffd800ff05551a197221f10001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010c",
"fundingsources": [
{
"sub_request_status": "success",
"fundingsource": {
"id": "e703eb9f-8eac-4eda-a9c7-deec3935222d",
"updated_at": "2016-08-11T22:03:54.337Z",
"created_at": "2016-08-11T22:03:54.337Z",
"name": "Hooli Test Ad Account Funding Source",
"type": "LINE_OF_CREDIT",
"organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"currency": "USD"
}
}
]
}
This endpoint retrieves a specific funding source.
HTTP Request
GET https://adsapi.snapchat.com/v1/fundingsources/{funding_source_id}
URL Parameters
Parameter | Description |
---|---|
funding_source_id | The ID of the funding source to retrieve |
Billing Centers
Billing Centers allow Businesses to have multiple invoicing locations to choose from. A Billing Center is the contact that will be receiving invoices.
Billing Centers can only be created via Snap Business Manager.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
organization_id | Organization ID | R | |
name | Name of the Billing Center | R | |
email_address | Email address | R | |
address_line_1 | Address line 1 | R | |
locality | Locality | R | |
administrative_district_level_1 | District | R | |
country | Country | R | |
postal_code | Post code | R | |
alternative_email_addresses | Array of email addresses | O |
Get all Billing Centers
curl "https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/billingcenters" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eaa971a00ff05c3d6fabff7fb0001737e616473617069736300016275696c642d63386238336332372d312d3334372d310001011a",
"paging": {},
"billingcenters": [
{
"sub_request_status": "SUCCESS",
"billingcenter": {
"id": "8b8db2a8-2b48-42f0-858a-88901a782b27",
"updated_at": "2017-10-17T12:25:50.866Z",
"created_at": "2017-10-17T12:25:50.866Z",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"name": "Duck Billing Center",
"email_address": "mr_duck@example.com",
"address_line_1": "11 Duck Pond Avenue",
"locality": "London",
"administrative_district_level_1": "GB-LND",
"country": "GB",
"postal_code": "NW1 4RY"
}
},
{
"sub_request_status": "SUCCESS",
"billingcenter": {
"id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd",
"updated_at": "2020-02-30T09:49:52.118Z",
"created_at": "2020-02-30T09:49:52.118Z",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"name": "Kianjous Billing Center",
"email_address": "honeybear_ltd@example.com",
"address_line_1": "10 Honey Bear Road",
"locality": "London",
"administrative_district_level_1": "GB-LND",
"country": "GB",
"postal_code": "NW1 4RY",
"alternative_email_addresses": [
"honeybear_burrow@example.com"
]
}
}
]
}
The following API request retrieves all Billing Centers for an Organization.
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/billingcenters
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Get a specific Billing Center
curl "https://adsapi.snapchat.com/v1/billingcenters/6e0f4532-3702-4f0b-9889-9fe5d0614afd" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eaa9e6000ff0570e6188bd1110001737e616473617069736300016275696c642d63386238336332372d312d3334372d3100010138",
"billingcenters": [
{
"sub_request_status": "SUCCESS",
"billingcenter": {
"id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd",
"updated_at": "2020-02-30T09:49:52.118Z",
"created_at": "2020-02-30T09:49:52.118Z",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"name": "Kianjous Billing Center",
"email_address": "honeybear_ltd@example.com",
"address_line_1": "10 Honey Bear Road",
"locality": "London",
"administrative_district_level_1": "GB-LND",
"country": "GB",
"postal_code": "NW1 4RY",
"alternative_email_addresses": [
"honeybear_burrow@example.com"
]
}
}
]
}
The following API request retrieves a specific Billing Center.
HTTP Request
GET https://adsapi.snapchat.com/v1/billingcenters/{billing_center_id}
Parameters
Parameter | Default | Description |
---|---|---|
billing_center_id | Billing Center ID |
Create a Billing Center
curl -X POST \
-d '{"billingcenters":[{"organization_id":"8fdeefec-f502-4ca8-9a84-6411e0a51053","name":"Kianjous Billing Center","email_address":"honeybear_ltd@example.com","address_line_1":"10 Honey Bear Road","locality":"London","administrative_district_level_1":"GB-LND","country":"GB","postal_code":"NW1 4RY","alternative_email_addresses":["honeybear_burrow@example.com"]}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/billingcenters
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eaa9f3f00ff0e03450355dbc60001737e616473617069736300016275696c642d63386238336332372d312d3334372d310001010b",
"billingcenters": [
{
"sub_request_status": "SUCCESS",
"billingcenter": {
"id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd",
"updated_at": "2020-02-30T09:49:52.118Z",
"created_at": "2020-02-30T09:49:52.118Z",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"name": "Kianjous Billing Center",
"email_address": "honeybear_ltd@example.com",
"address_line_1": "10 Honey Bear Road",
"locality": "London",
"administrative_district_level_1": "GB-LND",
"country": "GB",
"postal_code": "NW1 4RY",
"alternative_email_addresses": [
"honeybear_burrow@example.com"
]
}
}
]
}
The following API request creates a new Billing Center.
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/billingcenters
Parameters
Parameter | Default | Description |
---|---|---|
billing_center_id | Billing Center ID |
Update a Billing Center
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"billingcenters":[{"id":"6e0f4532-3702-4f0b-9889-9fe5d0614afd","organization_id":"1fdeefec-f502-4ca8-9a84-6411e0a51053","name":"Kianjous Billing Center","email_address":"honeybear_ltd@example.com","address_line_1":"10 Honey Bear Road","locality":"London","administrative_district_level_1":"GB-LND","country":"GB","postal_code":"NW1 4RY","alternative_email_addresses":["honeybear_burrow@example.com","mr_duck@example.com"]}]}'
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/billingcenters
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eac190700ff04ae16ca53679d0001737e616473617069736300016275696c642d38653566343030352d312d3334382d3000010107",
"billingcenters": [
{
"sub_request_status": "SUCCESS",
"billingcenter": {
"id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd",
"updated_at": "2020-05-01T12:41:43.470Z",
"created_at": "2020-04-30T09:49:52.118Z",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"name": "Kianjous Billing Center",
"email_address": "honeybear_ltd@example.com",
"address_line_1": "10 Honey Bear Road",
"locality": "London",
"administrative_district_level_1": "GB-LND",
"country": "GB",
"postal_code": "NW1 4RY",
"alternative_email_addresses": [
"honeybear_burrow@example.com",
"mr_duck@example.com"
]
}
}
]
}
The following API request updates a Billing Center with new details.
Attributes that can be updated
Attribute | Required |
---|---|
name | R |
email_address | R |
address_line_1 | R |
locality | R |
administrative_district_level_1 | R |
country | R |
postal_code | R |
alternative_email_addresses | O |
HTTP Request
PUT https://adsapi.snapchat.com/v1/organizations/{organization_id}/billingcenters
Parameters
Parameter | Default | Description |
---|---|---|
billing_center_id | Billing Center ID |
Invoices
Invoices can only be created by Snap, Invoices are allocated on an Ad Account basis and can be fetched by an member with one of the following roles, Organization Admin, Ad Account Admin, or Campaign Manager.
Attributes
Attribute | Description | Possible Values |
---|---|---|
org_id | Organization ID | |
invoice_id | Invoice ID | |
netsuite_file_id | Snap Internal ID | |
ad_account_id | Ad Account ID | |
customer.name | Customer name | |
customer.netsuite_id | Snap Internal ID | |
document_number | Document number | |
line_last_modified | Date | |
last_modified | Date | |
amount_cent | Invoice amount in cents | |
currency | Currency of the invoice | AUD, CAD, EUR, GBP, USD, SEK, DKK, NOK |
billing_period | Specifies the billing period | |
due_date | Due date of the invoice | |
created_at | Creation date of the invoice | |
invoice_status | Indicates whether the invoice has been collected | COLLECTED, SENT_FOR_COLLECTION |
invoice_content | Bytestream (Base64), this Bytestream can turned into a PDF |
List invoices by Ad Account
curl "https://adsapi.snapchat.com/v1/adaccounts/88cdd2d0-b604-455a-925b-b8eb68823e48/invoices" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f0f19d700ff0306e63ea5ff00980001737e616473617069736300016275696c642d61646161313865312d312d3336372d3000010102",
"invoices": [
{
"sub_request_status": "SUCCESS",
"invoice": {
"org_id": "8ba72a1b-0901-4b9e-951a-e39b9ad27aa3",
"invoice_id": "861b7c55-7e35-4348-918f-3758db350b80",
"netsuite_file_id": "5910692",
"ad_account_id": "88cdd2d0-b604-455a-925b-b8eb68823e48",
"customer": {
"name": "Badger Tunneling Inc.",
"netsuite_id": "8828020"
},
"document_number": "146810",
"line_last_modified": "2020-05-14T08:20:00.000Z",
"last_modified": "2020-05-14T08:20:00.000Z",
"amount_cent": 1171496,
"currency": "USD",
"billing_period": "April 2020",
"due_date": "2020-06-05T00:00:00.000Z",
"created_at": "2020-05-02T06:45:00.000Z",
"invoice_status": "COLLECTED"
}
},
{
"sub_request_status": "SUCCESS",
"invoice": {
"org_id": "8ba72a1b-0901-4b9e-951a-e39b9ad27aa3",
"invoice_id": "8848a897-e1b7-4433-a9a1-78fbafb5d52b",
"netsuite_file_id": "8036582",
"ad_account_id": "88cdd2d0-b604-455a-925b-b8eb68823e48",
"customer": {
"name": "Badger Tunneling Inc.",
"netsuite_id": "8828020"
},
"document_number": "151141",
"line_last_modified": "2020-06-09T08:34:00.000Z",
"last_modified": "2020-06-09T08:34:00.000Z",
"amount_cent": 375222,
"currency": "USD",
"billing_period": "May 2020",
"due_date": "2020-07-05T00:00:00.000Z",
"created_at": "2020-06-02T07:05:00.000Z",
"invoice_status": "COLLECTED"
}
},
{
"sub_request_status": "SUCCESS",
"invoice": {
"org_id": "8ba72a1b-0901-4b9e-951a-e39b9ad27aa3",
"invoice_id": "8be7c07f-b1dc-4aca-9729-348bf05b67a6",
"netsuite_file_id": "8170796",
"ad_account_id": "88cdd2d0-b604-455a-925b-b8eb68823e48",
"customer": {
"name": "Badger Tunneling Inc.",
"netsuite_id": "8828020"
},
"document_number": "154209",
"line_last_modified": "2020-07-07T16:15:00.000Z",
"last_modified": "2020-07-07T16:15:00.000Z",
"amount_cent": 1329360,
"currency": "USD",
"billing_period": "June 2020",
"due_date": "2020-08-06T00:00:00.000Z",
"created_at": "2020-07-02T04:53:00.000Z",
"invoice_status": "SENT_FOR_COLLECTION"
}
}
]
}
This endpoint will list all invoices for a given Ad Account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/invoices
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Get individual Invoice
curl "https://adsapi.snapchat.com/v1/adaccounts/04cdd2d0-b604-455a-925b-b8eb68823e48/invoices/2be7c07f-b1dc-4aca-9729-348bf05b67a6" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f107ce000ff0da20b969610630001737e616473617069736300016275696c642d61646161313865312d312d3336372d3000010131",
"invoices": [
{
"sub_request_status": "SUCCESS",
"invoice": {
"org_id": "eba72a1b-0901-4b9e-951a-e39b9ad27aa3",
"invoice_id": "2be7c07f-b1dc-4aca-9729-348bf05b67a6",
"netsuite_file_id": "6216757",
"ad_account_id": "04cdd2d0-b604-455a-925b-b8eb68823e48",
"customer": {
"name": "Flo Health, Inc.",
"netsuite_id": "7828020"
},
"document_number": "154209",
"line_last_modified": "2020-07-15T09:03:00.000Z",
"last_modified": "2020-07-15T09:03:00.000Z",
"amount_cent": 1329360,
"currency": "USD",
"billing_period": "June 2020",
"due_date": "2020-08-06T00:00:00.000Z",
"created_at": "2020-07-02T04:53:00.000Z",
"invoice_status": "COLLECTED"
}
}
]
}
This endpoint retrieve an individual invoice for a given Ad Account
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/invoices/{invoice_id}
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID | |
invoice_id | Invoice ID | |
include_pdf | false | optional parameter for retrieving the invoice_content attribute |
Example 1 - Invoice
Retrieving an invoice
curl "https://adsapi.snapchat.com/v1/adaccounts/9d874f18-8a86-422b-a4c0-67525472f339/invoices/93106732-4504-4220-83f6-035c30bf38a9" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f15b33d00ff04a2f415f889b70001737e616473617069736300016275696c642d65626530306366642d312d3336382d300001014c",
"invoices": [
{
"sub_request_status": "SUCCESS",
"invoice": {
"org_id": "96412453-e008-4353-a8da-881ed5170e9c",
"invoice_id": "93106732-4504-4220-83f6-035c30bf38a9",
"netsuite_file_id": "9214559",
"ad_account_id": "9d874f18-8a86-422b-a4c0-67525472f339",
"customer": {
"name": "Hedgehogs interactive Ltd",
"netsuite_id": "90053849"
},
"document_number": "150239",
"line_last_modified": "2020-07-14T23:43:00.000Z",
"last_modified": "2020-07-14T23:43:00.000Z",
"amount_cent": 132095,
"currency": "USD",
"billing_period": "May 2020",
"due_date": "2020-07-05T00:00:00.000Z",
"created_at": "2020-06-02T02:54:00.000Z",
"invoice_status": "COLLECTED"
}
}
]
}
This example retrieves an individual invoice.
Example 2 - Invoice - invoice_content
Retrieving an invoice with invoice_content
curl "https://adsapi.snapchat.com/v1/adaccounts/9e08d5dd-023b-429e-904c-0924291dc478/invoices/9db4ab51-6402-4b20-b47b-a893267dfb3f?include_pdf=true" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f15b5cd00ff0781f49f7748b80001737e616473617069736300016275696c642d65626530306366642d312d3336382d3000010150",
"invoices": [
{
"sub_request_status": "SUCCESS",
"invoice": {
"org_id": "97433ff4-1fb6-416f-b726-069624ac1de2",
"invoice_id": "9db4ab51-6402-4b20-b47b-a893267dfb3f",
"netsuite_file_id": "5489672",
"ad_account_id": "9e08d5dd-023b-429e-904c-0924291dc478",
"customer": {
"name": "Le Chipmunks Inc",
"netsuite_id": "1277123"
},
"document_number": "124357",
"line_last_modified": "2020-02-21T02:11:00.000Z",
"last_modified": "2020-02-21T02:11:00.000Z",
"amount_cent": 953057,
"currency": "EUR",
"billing_period": "November 2019",
"due_date": "2020-02-03T00:00:00.000Z",
"created_at": "2019-12-02T15:41:00.000Z",
"invoice_content": "JVBERi0xLjMKJd/++LIKMSAwIG9iago8PC ... emUgMzI+PgpzdGFydHhyZWYKMjY1ODQKJSVFT0YK",
"invoice_status": "COLLECTED"
}
}
]
}
This example retrieves an individual invoice for with the parameter include_pdf which adds the attribute invoice_content
on the invoice entity that is returned.
Ad Accounts
An Ad Account is owned by an Organization and contains Ad Campaigns. Ad Accounts have one or more Funding Sources (Credit card, Paypal, Lines of Credit etc).
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
advertiser | Name of the Advertiser | R | User input |
currency | Account currency | R | AUD, CAD, EUR, GBP, USD |
funding_source_ids | Array of Funding Source IDs | R | |
billing_type | Type of billing | R | IO, REVOLVING |
name | Account name | R | User input |
organization_id | Organization ID | R | |
test | Indicates Ad Account is a test ad account, test ad accounts can never serve live ads | O | true |
timezone | Account timezone, remember to take the time differences into account when you set up your application. All our timings are stored in UTC which means you are required to add/remove hours to make up a full 24 hours when using the DAY granularity in the API | R | Africa/Cairo, Africa/Johannesburg, America/Anchorage, America/Cancun, America/Chicago, America/Dawson, America/Dawson_Creek, America/Denver, America/Edmonton, America/Halifax, America/Hermosillo, America/Los_Angeles, America/Mazatlan, America/Mexico_City, America/Montevideo, America/New_York, America/Phoenix, America/Rainy_River, America/Regina, America/Tijuana, America/Toronto, America/Vancouver, Asia/Amman, Asia/Beirut, Asia/Dubai, Asia/Hong_Kong, Asia/Irkutsk, Asia/Jerusalem, Asia/Kamchatka, Asia/Krasnoyarsk, Asia/Magadan, Asia/Nicosia, Asia/Omsk, Asia/Qatar, Asia/Riyadh, Asia/Shanghai, Asia/Singapore, Asia/Vladivostok, Asia/Yakutsk, Asia/Yekaterinburg, Atlantic/Canary, Australia/Perth, Australia/Sydney, Europe/Amsterdam, Europe/Berlin, Europe/Brussels, Europe/Dublin, Europe/Helsinki, Europe/Istanbul, Europe/Kaliningrad, Europe/London, Europe/Luxembourg, Europe/Madrid, Europe/Malta, Europe/Moscow, Europe/Oslo, Europe/Paris, Europe/Rome, Europe/Samara, Europe/Stockholm, Europe/Vienna, Europe/Vilnius, Europe/Warsaw, Europe/Zurich, Pacific/Auckland, Pacific/Honolulu, UTC |
type | Account type | R | DIRECT, PARTNER |
lifetime_spend_cap_micro | Required if billing_type is set to IO, the lifetime spend cap of the account in micro currency | O | |
advertiser_organization_id | Organization ID of the Advertiser selected | read-only | |
paying_advertiser_name | Name of the paying advertiser/political entity, required if the Ad Account will contain political/advocacy ads | O | max 32 characters |
regulations | Required if the Ad Account will contain ads for Credit, Housing or Employment, this attribute is immutable once set to true | O | { “restricted_delivery_signals”: true } |
agency_representing_client | Account name | R | true/false |
client_based_in_country | Required if agency_representing_client is true and if Advertiser is based in France or targeting Ads to audiences in France |
O | FR |
client_paying_invoices | Required if agency_representing_client is true and if Advertiser is based in France or targeting Ads to audiences in France |
O | true/false |
agency_client_metadata | Client metadata is required if agency_representing_client is true and if the Advertiser is based in France or is targeting Ads to audiences in France |
O | JSON object containing the attributes; name, email, address_line_1, city,administrative_district_level_1, country, zipcode, tax_id |
delivery_status | Delivery status | Read-only | See Delivery status |
Create an Ad Account
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adaccounts": [{"name": "Example Ad Account","type": "PARTNER","status": "ACTIVE","organization_id": "7fdeefec-f502-4ca8-9a84-6411e0a51058","funding_source_ids": ["6ca1687a-f2b4-437d-8554-a85403a714c5"],"currency": "USD","billing_type": "IO","billing_center_id": "9b8db2a8-2b48-42f0-858a-88901a782b27","lifetime_spend_cap_micro": "200000000000","timezone": "America\/Los_Angeles","advertiser": "Example Advertiser Inc"}]}' \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/adaccounts
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e7b42c900ff0e76f111031c2c0001737e616473617069736300016275696c642d62313763613636652d312d3333372d3200010122",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "7c6d2e91-3a7c-4230-b048-f724bf217a82",
"updated_at": "2020-03-25T11:38:50.273Z",
"created_at": "2020-03-25T11:38:50.273Z",
"name": "Example Ad Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"funding_source_ids": [
"6ca1687a-f2b4-437d-8554-a85403a714c5"
],
"currency": "USD",
"timezone": "America/Los_Angeles",
"advertiser": "Example Advertiser Inc",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"billing_center_id": "9b8db2a8-2b48-42f0-858a-88901a782b27",
"billing_type": "IO",
"lifetime_spend_cap_micro": 200000000000,
"agency_representing_client": false,
"client_paying_invoices": false
}
}
]
}
This endpoint creates an Ad Account within the specified Organization. When setting up new Ad Accounts it’s important to take the below factors into account, not following these points may cause the Ad Account to be suspended.
If the ad account will be used for housing, credit or employment advertising it needs to have the attribute
regulations.restricted_delivery_signals
set totrue
If the ad account will be used for political advertising the attribute
paying_advertiser_name
needs to be filled out with the political organization or advocacy group who is paying for the ad (32 character limit)If the Ad Account is owned by an agency buying ads on behalf of an advertiser the attribute
agency_representing_client
needs to be set totrue
If the Ad Account is owned by an agency buying ads on behalf of an advertiser, and the Advertiser is based in France, or will target ads to an audience in France, the following settings will apply:
- The attribute
agency_representing_client
needs to be set totrue
- The attribute
client_paying_invoices
needs to be set totrue
if the agency is paying the invoices, orfalse
if the advertiser they represent is paying the invoices - The attribute
client_based_in_country
needs to be set tofr
- The attribute
agency_client_metadata
needs to be set using the attributesname
,email
,address_line_1
,city
,administrative_district_level_1
,country
,zipcode
andtax_id
- The attribute
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/adaccounts
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Get All Ad Accounts
curl "https://adsapi.snapchat.com/v1/organizations/{organization_id}/adaccounts" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0015e00ff07d5c0c38928ad0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010107",
"adaccounts": [
{
"sub_request_status": "success",
"adaccount": {
"id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"updated_at": "2016-08-11T22:03:58.869Z",
"created_at": "2016-08-11T22:03:58.869Z",
"name": "Hooli Test Ad Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"funding_source_ids": [
"e703eb9f-8eac-4eda-a9c7-deec3935222d"
],
"currency": "USD",
"timezone": "America/Los_Angeles",
"advertiser": "Hooli"
}
},
{
"sub_request_status": "success",
"adaccount": {
"id": "81cf9302-764c-429a-8561-e3bc329cf987",
"updated_at": "2016-08-11T22:03:58.869Z",
"created_at": "2016-08-11T22:03:58.869Z",
"name": "Awesome Ad Account",
"type": "DIRECT",
"status": "ACTIVE",
"organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"funding_source_ids": [
"7abfb9c6-0258-4eee-9898-03a8c099695d"
],
"currency": "USD",
"timezone": "America/Los_Angeles",
"advertiser": "Hooli"
}
}
]
}
This endpoint retrieves all ad accounts for the specified Organization.
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/{organization-id}/adaccounts
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Get a Specific Ad Account
curl "https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0021900ff06bbfeb44f77240001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010e",
"adaccounts": [
{
"sub_request_status": "success",
"adaccount": {
"id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"updated_at": "2016-08-11T22:03:58.869Z",
"created_at": "2016-08-11T22:03:58.869Z",
"name": "Hooli Test Ad Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"funding_source_ids": [
"e703eb9f-8eac-4eda-a9c7-deec3935222d"
],
"currency": "USD",
"timezone": "America/Los_Angeles",
"advertiser": "Hooli"
}
}
]
}
This endpoint retrieves a specific Ad Account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}
URL Parameters
Parameter | Description |
---|---|
ad_account_id | Ad Account ID of the ad account to retrieve |
Update Ad Account
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adaccounts": [{"type": "PARTNER","advertiser": "Example Advertiser Inc","advertiser_organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053","billing_center_id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd","billing_type": "IO","currency": "USD","id": "7c6d2e91-3a7c-4230-b048-f724bf217a82","lifetime_spend_cap_micro": 200000000000,"name": "Example Ad Account","organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053","funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],"status": "ACTIVE","timezone": "America/Los_Angeles","agency_representing_client": false,"client_paying_invoices": false}]}'
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/adaccounts
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eac3e0c00ff07836d9acd3b2a0001737e616473617069736300016275696c642d38653566343030352d312d3334382d3000010137",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "7c6d2e91-3a7c-4230-b048-f724bf217a82",
"updated_at": "2020-05-01T15:19:41.536Z",
"created_at": "2020-03-25T11:38:50.273Z",
"name": "Example Ad Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"funding_source_ids": [
"5ca1687a-f2b4-437d-8554-a85403a714c5"
],
"currency": "USD",
"timezone": "America/Los_Angeles",
"advertiser": "Example Advertiser Inc",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"billing_center_id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd",
"billing_type": "IO",
"lifetime_spend_cap_micro": 200000000000,
"agency_representing_client": false,
"client_paying_invoices": false
}
}
]
}
This endpoint updates a specific Ad Account.
Attributes that can be updated
Attribute | Required |
---|---|
name | R |
advertiser | R |
billing_center_id | R |
lifetime_spend_cap_micro | R |
regulations.restricted_delivery_signals | R |
agency_representing_client | R |
paying_advertiser_name | O |
client_paying_invoices | O |
client_based_in_country | O |
agency_client_metadata | O |
HTTP Request
PUT https://adsapi.snapchat.com/v1/organizations/{organization_id}/adaccounts
URL Parameters
Parameter | Description |
---|---|
organization_id | Organization ID of the Organization to which the Ad Account belongs |
Update an Ad Account’s Lifetime Spend Cap
curl -X PUT \
-H 'Authorization: Bearer meowmeowmeow' \
-H 'Content-Type: application/json' \
-d '{"adaccounts": [{"id":"123b9ca6-92f2-49c3-a3ed-0ea58afb467e","name":"Hooli Ad Account","type":"PARTNER","status":"ACTIVE","organization_id":"40c6719b-da09-410b-9185-0cc9c0dfed1d","funding_source_ids":["cdc67eba-a774-4954-9b94-9502bbdac1bc"],"currency":"USD","timezone":"America/Los_Angeles","brand_name":"Hooli","lifetime_spend_cap_micro":1500000000
}]}' \
https://adsapi.snapchat.com/v1/organizations/40c6719b-da09-410b-9185-0cc9c0dfed1d/adaccounts
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0021900ff06bbfeb44f77240001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010e",
"adaccounts": [
{
"sub_request_status": "success",
"adaccount": {
"id": "123b9ca6-92f2-49c3-a3ed-0ea58afb467e",
"updated_at": "2016-08-11T22:03:58.869Z",
"created_at": "2016-08-11T22:03:58.869Z",
"name": "Hooli Ad Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "40c6719b-da09-410b-9185-0cc9c0dfed1d",
"funding_source_ids": [
"e703eb9f-8eac-4eda-a9c7-deec3935222d"
],
"currency": "USD",
"timezone": "America/Los_Angeles",
"brand_name":"Hooli",
"lifetime_spend_cap_micro":1500000000
}
}
]
}
This endpoint updates the Lifetime Spend Limit of a specific ad account, this can only be updated for Ad Accounts where the billing_type
is set to IO
. Please note that once the Lifetime Spend Limit is set for a specific ad account, it can only be increased or decreased but not removed.
Assign Funding Source
Assigning funding sources to ad accounts can be done in Business Manager. Please reach out to your partner manager for further assistance.
Ad Account creation - Example 1
Ad Account - Used for Political advertising
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adaccounts": [{"name": "Votes for Dogs Account","type": "PARTNER","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],"currency": "GBP","timezone": "Europe/London","advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27","billing_type": "REVOLVING","agency_representing_client": false,"client_paying_invoices": false,"paying_advertiser_name": "The Pugs & Poodle Alliance","regulations": {"restricted_delivery_signals": false}}]}' \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/adaccounts
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eac0cdb00ff06d4845e8997c40001737e616473617069736300016275696c642d38653566343030352d312d3334382d300001015f",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "2b0efb26-973b-4085-aef1-bd0bef429b91",
"updated_at": "2020-05-01T11:49:48.045Z",
"created_at": "2020-05-01T11:49:48.045Z",
"name": "Votes for Dogs Account",
"type": "PARTNER",
"status": "PENDING",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"funding_source_ids": [
"5ca1687a-f2b4-437d-8554-a85403a714c5"
],
"currency": "GBP",
"timezone": "Europe/London",
"paying_advertiser_name": "The Pugs & Poodle Alliance",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27",
"billing_type": "REVOLVING",
"agency_representing_client": false,
"client_paying_invoices": false,
"regulations": {
"restricted_delivery_signals": false
}
}
}
]
}
This request creates an Ad account that will be used for Political or Advocacy Ads, it contains the attribute paying_advertiser_name
.
Ad Account creation - Example 2
Ad Account - Used for Credit, Housing, Employment Ads
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adaccounts": [{"name": "Account for Credit Housing Employment Ads","type": "PARTNER","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],"currency": "EUR","timezone": "Europe/Paris","advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27","billing_type": "REVOLVING","agency_representing_client": false,"client_paying_invoices": false,"regulations": {"restricted_delivery_signals": true}}]}' \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/adaccounts
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eac0e1600ff0abfa792ff005a320001737e616473617069736300016275696c642d38653566343030352d312d3334382d3000010153",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "f249cfe1-973f-4a04-899a-c1f65b9070a0",
"updated_at": "2020-05-01T11:55:03.343Z",
"created_at": "2020-05-01T11:55:03.343Z",
"name": "Account for Credit Housing Employment Ads",
"type": "PARTNER",
"status": "PENDING",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"funding_source_ids": [
"5ca1687a-f2b4-437d-8554-a85403a714c5"
],
"currency": "EUR",
"timezone": "Europe/Paris",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27",
"billing_type": "REVOLVING",
"agency_representing_client": false,
"client_paying_invoices": false,
"regulations": {
"restricted_delivery_signals": true
}
}
}
]
}
This request creates an Ad account that can be used for housing, credit and employment ads, the restricted_delivery_signals
within the regulations
attribute has been set to true
.
Ad Account creation - Example 3
Ad Account - Agency representing client, client based in France or targeting France
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{ "adaccounts": [{"name": "délicieux aliments pour chiens","type": "PARTNER","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],"currency": "EUR","timezone": "Europe/Paris","advertiser_organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053","billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27","billing_type": "REVOLVING","agency_representing_client": true,"client_based_in_country": "FR","client_paying_invoices": false,"agency_client_metadata": {"name": "Madamemoiselle Poodle","email": "poodle_client@example.com","address_line_1": "101 Boulevard la Fayette","city": "Paris","administrative_district_level_1": "FR-O","country": "FR","zipcode": "62100","tax_id": "FR12345678900"},"regulations": {"restricted_delivery_signals": false}}]}' \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/adaccounts
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eab157200ff07dcbf0737d8790001737e616473617069736300016275696c642d63386238336332372d312d3334372d3100010128",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "cdfc6dbd-9ac6-416a-b386-d473dd6e6d64",
"updated_at": "2020-04-30T18:14:11.150Z",
"created_at": "2020-04-30T18:14:11.150Z",
"name": "Délicieux aliments pour chiens",
"type": "PARTNER",
"status": "PENDING",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"funding_source_ids": [
"5ca1687a-f2b4-437d-8554-a85403a714c5"
],
"currency": "EUR",
"timezone": "Europe/Paris",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27",
"billing_type": "REVOLVING",
"agency_representing_client": true,
"client_based_in_country": "FR",
"client_paying_invoices": false,
"agency_client_metadata": {
"name": "Madamemoiselle Poodle",
"email": "poodle_client@example.com",
"address_line_1": "101 Boulevard la Fayette",
"city": "Paris",
"administrative_district_level_1": "FR-O",
"country": "FR",
"zipcode": "62100",
"tax_id": "FR12345678900"
},
"regulations": {
"restricted_delivery_signals": false
}
}
}
]
}
This request creates an Ad Account that is owned by an Agency representing a client, where the Advertiser is paying the invoices and where the Advertiser is based in France, or where the Ad Account will target ads to audience in France.
agency_representing_client
has been set totrue
client_based_in_country
has been set toFR
client_paying_invoices
has been set tofalse
as the Advertiser is paying the invoices (note that this should be set totrue
if the Agency pays the invoices)agency_client_metadata
has been filled out with the address of the Advertiser and their French Tax ID
Ad Account creation - Example 4
Ad Account - Setting up a test Ad Account
curl -X POST -H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
-d '{"adaccounts": [{"name":"The Dalmatian Test Account","type":"PARTNER","status":"ACTIVE","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058","currency": "EUR","timezone": "Europe\/London","advertiser":"Dalmatian Retail", "billing_type":"REVOLVING","billing_center_id":"7b8db2a8-2b48-42f0-858a-88901a782b27","agency_representing_client":false, "client_paying_invoices": false,"test":true}]}' \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/adaccounts
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f68d35200ff0864c8d10ae0dd0001737e616473617069736300016275696c642d35373264613164312d312d3338362d300001013d",
"adaccounts": [
{
"sub_request_status": "SUCCESS",
"adaccount": {
"id": "a54ccc44-12fa-4952-b813-95f5dcfc27e7",
"updated_at": "2020-09-21T16:22:43.094Z",
"created_at": "2020-09-21T16:22:43.094Z",
"name": "The Dalmatian Test Account",
"type": "PARTNER",
"status": "ACTIVE",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"currency": "EUR",
"timezone": "Europe/London",
"advertiser": "Dalmatian Retail",
"advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
"billing_center_id": "7b8db2a8-2b48-42f0-858a-88901a782b27",
"test": true,
"billing_type": "REVOLVING",
"agency_representing_client": false,
"client_paying_invoices": false
}
}
]
}
This request creates an Ad Account with the test parameter set to true, the resulting Ad Account never will be able to serve ads. The intention of setting up such an Ad Account is to be able to execute write requests without risking that ads will go live.
Members
A Member represents a Snapchat account user who is a member of an Organization, a Member needs to be assigned a Role within both the Organization and individual Ad Accounts in order to access entities.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
display_name | Name of the user | R | |
organization_id | Organization ID | R | |
member_status | Name of the Advertiser | R | INVITED, MEMBER |
email address of the user | R |
Get all Members of an Organization
curl "https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/members" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea05c4800ff08ac5ff42a0f740001737e616473617069736300016275696c642d64313063316333662d312d3334352d3000010102",
"members": [
{
"sub_request_status": "SUCCESS",
"member": {
"id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
"updated_at": "2017-10-17T12:25:50.815Z",
"created_at": "2017-10-17T12:25:50.815Z",
"email": "honeybear@example.com",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"display_name": "Honey Bear",
"member_status": "MEMBER"
}
},
{
"sub_request_status": "SUCCESS",
"member": {
"id": "b124e762-9720-4f89-bdd2-7fe06e71d7cc",
"updated_at": "2020-03-05T11:29:31.562Z",
"created_at": "2018-09-28T19:05:09.787Z",
"email": "jack_the_bear@example.com",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"display_name": "Jack Polarbear",
"member_status": "MEMBER"
}
},
{
"sub_request_status": "SUCCESS",
"member": {
"id": "d051973d-32b2-496b-b44a-345986bce17d",
"updated_at": "2020-04-22T14:56:33.164Z",
"created_at": "2020-04-22T14:45:04.452Z",
"email": "guinea_pig@example.com",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"display_name": "Esmeralda the Guinea Pig",
"member_status": "MEMBER"
}
}
]
}
The following API request returns the information of all Members of an Organization, this includes their display name, email address and member status. Members who have not yet accepted their invite will have the status INVITED, members that have accepted the invite will have the status MEMBER.
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/members
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Get a specific Member
curl "https://adsapi.snapchat.com/v1/members/d051973d-32b2-496b-b44a-345986bce17d" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea05dcf00ff05a0584dcd2c0f0001737e616473617069736300016275696c642d64313063316333662d312d3334352d300001015b",
"members": [
{
"sub_request_status": "SUCCESS",
"member": {
"id": "d051973d-32b2-496b-b44a-345986bce17d",
"updated_at": "2020-04-22T14:56:33.164Z",
"created_at": "2020-02-22T14:45:04.452Z",
"email": "honeybear@example.com",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"display_name": "Honey Bear",
"member_status": "MEMBER"
}
}
]
}
The following API request returns the information of a specific Member.
HTTP Request
GET https://adsapi.snapchat.com/v1/members/{member_id}
Parameters
Parameter | Default | Description |
---|---|---|
member_id | Member ID |
Create Member
curl -X POST \
-d '{"members": [{"email": "honeybear@example.com","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","display_name": "Honey Bear"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/members
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea0587000ff0360f26d1e8c1d0001737e616473617069736300016275696c642d64313063316333662d312d3334352d3000010157",
"members": [
{
"sub_request_status": "SUCCESS",
"member": {
"id": "d051973d-32b2-496b-b44a-345986bce17d",
"updated_at": "2020-04-22T14:45:04.452Z",
"created_at": "2020-04-22T14:45:04.452Z",
"email": "honeybear@example.com",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"display_name": "Honey Bear",
"member_status": "INVITED"
}
}
]
}
The following API request creates a member within the chosen Organization, this will trigger an email invite to the user in question.
When the user accepts the invite the member_status
attribute will update from INVITED to MEMBER. Member creation should always be coupled with a Role creation within the Organization.
HTTP Request
POST https://adsapi.snapchat.com/v1/organizations/{organization_id}/members
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Delete Member
curl -X DELETE "https://adsapi.snapchat.com/v1/members/d051973d-32b2-496b-b44a-345986bce17d" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status":"SUCCESS",
"request_id":"5ea6f3f900ff01fa13ebea326c0001737e616473617069736300016275696c642d39326335343566322d312d3334362d3000010107",
"members":[]
}
The following API request deletes a member from the Organization.
HTTP Request
DELETE https://adsapi.snapchat.com/v1/{{member_id}}
Parameters
Parameter | Default | Description |
---|---|---|
member_id | Member ID |
Roles
Roles exist at two levels, Organization level and Ad Account level.
Organization Roles
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
member_id | Member ID | R | |
organization_id | Organization ID | R | |
type | Organization role type | R | member, admin |
A Member
must be assigned one of the two Organization role types, member
or admin
.
Name | Description |
---|---|
admin | Admin access to everything in the Organization including creating, updating, deleting entities, adding new Members, assigning Roles |
member | Required for all Members who do not have the admin role, also a prerequisite for Ad Account Roles |
Ad Account Roles
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
member_id | Member ID | R | |
ad_account_id | Member ID | R | |
type | Ad Account role type | R | admin, creative, general, reports, audience |
In order to be assigned an Ad Account role the Member in question first needs the Organization role type member
.
Name | Description |
---|---|
admin | Admin access to everything in the Ad Account |
creative | Has full control of Creative and Media entities, and read access to all other entities. |
general | Has full control of sub-Ad Account level entities (Campaigns, Ad Squads, Ads) |
reports | Has read-only access to the Ad Account for reporting purposes. |
audience | Has full control of Audience entities |
Get Roles for Member
curl "https://adsapi.snapchat.com/v1/members/d051973d-32b2-496b-b44a-345986bce17d/roles?limit=100" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea9654400ff07724b540651010001737e616473617069736300016275696c642d36373239363666352d312d3334372d3000010115",
"paging": {},
"roles": [
{
"sub_request_status": "SUCCESS",
"role": {
"id": "53155cfb-fc21-4d5f-a3dc-2ab7d8c7db03",
"updated_at": "2020-02-04T12:32:22.365Z",
"created_at": "2020-02-04T12:32:22.281Z",
"container_kind": "AdAccounts",
"container_id": "8fb3b893-7978-43d5-81fe-fe0613972092",
"member_id": "d051973d-32b2-496b-b44a-345986bce17d",
"ad_account_id": "8fb3b893-7978-43d5-81fe-fe0613972092",
"type": "reports"
}
},
{
"sub_request_status": "SUCCESS",
"role": {
"id": "9e19db05-340d-4cdf-8de9-09022a2842cf",
"updated_at": "2019-02-06T23:26:11.401Z",
"created_at": "2018-10-17T11:48:58.601Z",
"container_kind": "AdAccounts",
"container_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"member_id": "d051973d-32b2-496b-b44a-345986bce17d",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"type": "admin"
}
},
{
"sub_request_status": "SUCCESS",
"role": {
"id": "ab0e7b9b-e0c0-441e-b26b-90ebd13c564a",
"updated_at": "2019-02-07T00:52:25.576Z",
"created_at": "2018-10-17T11:48:24.559Z",
"container_kind": "Organizations",
"container_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"member_id": "d051973d-32b2-496b-b44a-345986bce17d",
"organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053",
"type": "member"
}
}
]
}
The following API request returns all Roles assigned to a Member, this includes Roles within both Organizations and Ad Accounts.
HTTP Request
GET https://adsapi.snapchat.com/v1/members/{member_id}/roles
Parameters
Parameter | Default | Description |
---|---|---|
something_id | Organization ID | |
limit | integer, min 50, max 1000 |
Get all Roles in Organization
curl "https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/roles?limit=100" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea9636000ff0d8046762797040001737e616473617069736300016275696c642d36373239363666352d312d3334372d300001010c",
"paging": {},
"roles": [
{
"sub_request_status": "SUCCESS",
"role": {
"id": "1001050f-325e-486f-902f-e7eea192755f",
"updated_at": "2019-12-05T14:30:20.480Z",
"created_at": "2019-12-05T14:30:20.480Z",
"container_kind": "Organizations",
"container_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053",
"member_id": "63ef6f6d-09f4-4eb7-aa52-c83bcc35608c",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"type": "admin"
}
},
{
"sub_request_status": "SUCCESS",
"role": {
"id": "10d8b407-40f3-406d-8d04-2d5c59ff55fd",
"updated_at": "2020-03-05T11:29:31.964Z",
"created_at": "2020-03-05T11:29:31.964Z",
"container_kind": "Organizations",
"container_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053",
"member_id": "b124e762-9720-4f89-bdd2-7fe06e71d7cc",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"type": "member"
}
},
{
"sub_request_status": "SUCCESS",
"role": {
"id": "20feac40-828c-46e2-a57b-60b5e0274ce4",
"updated_at": "2020-03-25T17:54:39.170Z",
"created_at": "2020-03-25T17:54:39.170Z",
"container_kind": "Organizations",
"container_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053",
"member_id": "9db3e9a8-b7d4-4bb9-922f-72ea22d10aa6",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"type": "member"
}
},
{
"sub_request_status": "SUCCESS",
"role": {
"id": "57fa3d11-7330-461e-aca0-0d010d5b4932",
"updated_at": "2019-02-06T07:42:30.365Z",
"created_at": "2017-10-17T12:25:50.821Z",
"container_kind": "Organizations",
"container_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053",
"member_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"type": "admin"
}
}
]
}
The following API request returns all Roles assigned within an Organization.
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/roles
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID | |
limit | integer, min 50, max 1000 |
Create Organization Role
curl -X POST \
-d '{"roles": [{"member_id": "d051973d-32b2-496b-b44a-345986bce17d","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","type": "member"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/organizations/1fdeefec-f502-4ca8-9a84-6411e0a51053/roles
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea8334500ff06d6157db3e3d40001737e616473617069736300016275696c642d36373239363666352d312d3334372d3000010137",
"roles": [
{
"sub_request_status": "SUCCESS",
"role": {
"id": "9a121178-73f0-4089-8f80-a60e5445e8ea",
"updated_at": "2020-04-28T13:44:37.586Z",
"created_at": "2020-04-28T13:44:37.586Z",
"container_kind": "Organizations",
"container_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"member_id": "d051973d-32b2-496b-b44a-345986bce17d",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"type": "member"
}
}
]
}
The following API request creates an Organization Role for a Member, this should follow any Member invitation to the Organization.
HTTP Request
POST https://adsapi.snapchat.com/v1/organizations/{organization_id}/roles
Parameters
Parameter | Default | Description |
---|---|---|
organization_id | Organization ID |
Get all Roles in Ad Account
curl "https://adsapi.snapchat.com/v1/82225ba6-7559-4000-9663-bace8adff5f2/roles?limit=1000" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea85f5100ff0e03a2de2a46760001737e616473617069736300016275696c642d36373239363666352d312d3334372d3000010106",
"paging": {},
"roles": [
{
"sub_request_status": "SUCCESS",
"role": {
"id": "4c73255a-903a-423c-a98d-862bba405ec0",
"updated_at": "2019-05-22T13:04:14.694Z",
"created_at": "2019-05-22T13:04:14.694Z",
"container_kind": "AdAccounts",
"container_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"member_id": "9227efda-b0d4-497e-82b9-0125780892ec",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"type": "creative"
}
},
{
"sub_request_status": "SUCCESS",
"role": {
"id": "e293289e-14d8-432a-9edb-2943b75da2ec",
"updated_at": "2019-02-07T18:08:18.706Z",
"created_at": "2018-10-18T19:41:56.727Z",
"container_kind": "AdAccounts",
"container_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"member_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"type": "admin"
}
},
{
"sub_request_status": "SUCCESS",
"role": {
"id": "f7cd2f3c-de7e-4b4f-b8f4-44f2b428bca9",
"updated_at": "2020-03-25T17:55:01.620Z",
"created_at": "2020-03-25T17:55:01.344Z",
"container_kind": "AdAccounts",
"container_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"member_id": "9db3e9a8-b7d4-4bb9-922f-72ea22d10aa6",
"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
"type": "general"
}
}
]
}
The following API gets a list of all Roles that have been created within an Ad Account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/roles
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID | |
limit | integer, min 50, max 1000 |
Create Ad Account Role
curl -X POST \
-d '{"roles": [{"member_id": "d051973d-32b2-496b-b44a-345986bce17d","ad_account_id": "8c545687-a599-4faa-a704-4b097c6da5fe","type": "creative"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8c545687-a599-4faa-a704-4b097c6da5fe/roles
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea8335700ff09599711db33160001737e616473617069736300016275696c642d36373239363666352d312d3334372d3000010135",
"roles": [
{
"sub_request_status": "SUCCESS",
"role": {
"id": "5191aec7-b771-4c56-9963-126b14dbe2e3",
"updated_at": "2020-02-28T13:44:55.746Z",
"created_at": "2020-02-28T13:44:55.746Z",
"container_kind": "AdAccounts",
"container_id": "8c545687-a599-4faa-a704-4b097c6da5fe",
"member_id": "d051973d-32b2-496b-b44a-345986bce17d",
"ad_account_id": "8c545687-a599-4faa-a704-4b097c6da5fe",
"type": "creative"
}
}
]
}
The following API request creates an Ad Account role for the Member. Note that a prerequisite for an Ad Account role is for the Member to already have a member
role in the Organization under which the Ad Account exists.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/roles
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Delete Role
curl -X DELETE "https://adsapi.snapchat.com/v1/roles/5191aec7-b771-4c56-9963-126b14dbe2e3" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ea8338a00ff0ded779b7f217a0001737e616473617069736300016275696c642d36373239363666352d312d3334372d3000010130",
"roles": []
}
The following API request removes a Role from an Organisation or Ad Account. If you are deleting the Member’s Organization Role, leaving the Member without any roles, you should also delete the Member from the Organization.
HTTP Request
DELETE https://adsapi.snapchat.com/v1/roles/{role_id}
Parameters
Parameter | Default | Description |
---|---|---|
role_id | Role ID |
Campaigns
A campaign has a business objective and organizes Ad Squads. You can define a goal and view stats for this campaign to see whether your goal has been reached. The reports and stats combines all the ad squads within this campaign.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
daily_budget_micro | Daily Spend Cap (micro-currency) | O | |
end_time | End time | O | |
name | Campaign name | R | |
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” } |
delivery_status | Delivery status | Read-only | See Delivery status |
** Coming soon. See Reach And Frequency
++ The regulations attribute alongside restricted_delivery_signals is required for Campaigns running Ads promoting Credit, Housing, Employment (CHE), this attribute has to be activated at Ad Account level first or it cannot be used at Campaign level; https://businesshelp.snapchat.com/en-US/a/create-ad-account
+- The regulations attribute alongside the candidate_ballot_information field is optional, but may be required in certain states The paying_advertiser attribute has to be activated at Ad Account level first or the candidate/ballot field cannot be used at Campaign level; https://businesshelp.snapchat.com/en-US/a/create-ad-account
To enable app install and post-install attribution on ads, the ‘measurement_spec’ field must be populated with the corresponding iOS and Android app IDs on campaign creation.
lifetime_spend_cap_micro
can be increased and removed. Reducing the limit is allowed as long as the new limit is 1.1 times the amount already spent. daily_budget_micro
set at the campaign level & the new lifetime_spend_cap_micro
are evaluated independently. Delivery stops when either the Ad Account spend cap or the Campaign Lifetime spend cap is reached.
Create a Campaign
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"campaigns": [{"name": "Cool Campaign", "ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1d0d", "status": "PAUSED", "start_time": "2016-08-11T22:03:58.869Z"}]}' \
"https://adsapi.snapchat.com/v1/adaccounts/{ad_acount_id}/campaigns"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b002ad00ff07e1f50fd2267f0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"campaigns": [
{
"sub_request_status": "success",
"campaign": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"updated_at": "2016-08-14T05:33:33.876Z",
"created_at": "2016-08-14T05:33:33.876Z",
"name": "Cool Campaign",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"status": "PAUSED",
"start_time": "2016-08-11T22:03:58.869Z"
}
}
]
}
This endpoint will create a campaign within a specified ad account.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/campaigns
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Update a Campaign
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"campaigns": [{"name": "Cool Campaign", "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "status": "PAUSED", "start_time": "2016-08-11T22:03:58.869Z", "end_time": "2016-08-21T22:03:58.869-0700", "id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39"}]}'
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/campaigns
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0032700ff07e0cfdaa5e1a40001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010105",
"campaigns": [
{
"sub_request_status": "success",
"campaign": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"updated_at": "2016-08-14T05:35:35.943Z",
"created_at": "2016-08-14T05:33:33.876Z",
"name": "Cool Campaign",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"status": "PAUSED",
"start_time": "2016-08-11T22:03:58.869Z",
"end_time": "2016-08-22T05:03:58.869Z"
}
}
]
}
This endpoint will update a specified campaign.
Attributes that can be updated
Attribute | Description | Required | Possible Values |
---|---|---|---|
end_time | End time | O | |
name | Campaign name | R | |
daily_budget_micro | Daily Spend Cap (micro-currency) | O | |
lifetime_spend_cap_micro | Lifetime spend cap for the campaign (micro-currency) | O | |
start_time | Start time | O | |
status | Campaign status | R | ACTIVE, PAUSED |
HTTP Request
PUT https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/campaigns
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Get All Campaigns
curl "https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/campaigns" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b003c700ff0f2e66c37f96c20001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010103",
"campaigns": [
{
"sub_request_status": "success",
"campaign": {
"id": "06302efa-4c0f-4e36-b880-a395a36cef64",
"updated_at": "2016-08-12T20:28:58.738Z",
"created_at": "2016-08-12T20:28:58.738Z",
"name": "Campaign One",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"daily_budget_micro": 200000000,
"status": "ACTIVE",
"start_time": "2016-08-10T17:12:49.707Z",
"end_time": "2016-08-13T17:12:49.707Z"
}
},
{
"sub_request_status": "success",
"campaign": {
"id": "0fc8e179-6f3b-46e7-be8e-ca53fd404ece",
"updated_at": "2016-08-12T21:06:18.343Z",
"created_at": "2016-08-12T21:06:18.343Z",
"name": "Campaign Deux",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"daily_budget_micro": 500000000,
"status": "ACTIVE",
"start_time": "2016-08-10T17:12:49.707Z",
"end_time": "2016-08-13T17:12:49.707Z"
}
},
[[[ snip ]]]
{
"sub_request_status": "success",
"campaign": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"updated_at": "2016-08-14T05:36:46.441Z",
"created_at": "2016-08-14T05:33:33.876Z",
"name": "Cool Campaign",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"status": "PAUSED",
"start_time": "2016-08-11T22:03:58.869Z",
"end_time": "2016-08-22T05:03:58.869Z"
}
},
{
"sub_request_status": "success",
"campaign": {
"id": "fedf8e04-0176-4ce3-a1ca-148204aee62c",
"updated_at": "2016-08-12T02:18:33.412Z",
"created_at": "2016-08-12T02:18:33.412Z",
"name": "Crazy Campaign",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"start_time": "2016-08-11T22:03:58.869Z",
"status": "PAUSED"
}
}
]
}
This endpoint retrieves all campaigns within a specified ad account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/campaigns
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Get a Specific Campaign
curl "https://adsapi.snapchat.com/v1/campaigns/92e1c28a-a331-45b4-8c26-fd3e0eea8c39" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0049c00ff0e8cb21af5199c0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010107",
"campaigns": [
{
"sub_request_status": "success",
"campaign": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"updated_at": "2016-08-14T05:36:46.441Z",
"created_at": "2016-08-14T05:33:33.876Z",
"name": "Cool Campaign",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"status": "PAUSED",
"start_time": "2016-08-11T22:03:58.869Z",
"end_time": "2016-08-22T05:03:58.869Z"
}
}
]
}
This endpoint retrieves a specific campaign.
HTTP Request
GET https://adsapi.snapchat.com/v1/campaigns/<ID>
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the campaign to retrieve |
Delete a Specific Campaign
curl -X DELETE "https://adsapi.snapchat.com/v1/campaigns/92e1c28a-a331-45b4-8c26-fd3e0eea8c39" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b004dc00ff0e29c26b5d51840001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010106",
"campaigns": []
}
This endpoint deletes a specific campaign.
HTTP Request
DELETE https://adsapi.snapchat.com/v1/campaigns/<ID>
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the campaign to delete |
Ad Squads
An Ad Squad is owned by a Campaign and contains one or more Ads.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
campaign_id | Campaign ID | R | |
bid_micro | Max Bid (micro-currency) | R | Minimum value 10000 , Maximum value 1000000000 |
billing_event | Billing Event | R | IMPRESSION |
daily_budget_micro | Daily Budget (micro-currency) | one of daily_budget_micro or lifetime_budget_micro must be set | Minimum value 5000000 across all supported currencies |
lifetime_budget_micro | Lifetime budget (micro-currency) | one of lifetime_budget_micro or daily_budget_micro must be set | |
end_time | End time | O | |
name | Ad Squad name | R | |
optimization_goal | Optimization Goal | R | IMPRESSIONS, SWIPES, APP_INSTALLS, VIDEO_VIEWS, VIDEO_VIEWS_15_SEC, USES, STORY_OPENS, PIXEL_PAGE_VIEW, PIXEL_ADD_TO_CART, PIXEL_PURCHASE, PIXEL_SIGNUP, APP_ADD_TO_CART, APP_PURCHASE, APP_SIGNUP, see Squad Optimization Goals |
conversion_window | Conversion window optimization, requires optimization_goal is one of APP_INSTALLS, APP_PURCHASE, APP_SIGNUP, APP_ADD_TO_CART, APP_REENGAGE_OPEN, see Squad Optimization window | O | SWIPE_28DAY_VIEW_1DAY, SWIPE_7D |
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 attribute will be deprecated please use inclusion | 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 attribute will be deprecated please use exclusion | 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 desired ROAS used with the MIN_ROAS BidStrategy | R if BidStrategy = MIN_ROAS | Minimum value 10000 , Maximum value 100000000 |
pixel_id | Pixel to be associated with the Ad Squad | O | |
measurement_provider_names | approved measurement provider | O | MOAT_SS, DOUBLEVERIFY |
reach_and_frequency_status** | Status of the reach and frequency booking | R | Must be set to PENDING which automatically updates to ACTIVE or FAILED after booking |
delivery_constraint | Type of delivery | R | DAILY_BUDGET (when using daily_budget_micro), LIFETIME_BUDGET (when using lifetime_budget_micro), REACH_AND_FREQUENCY** |
reach_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 |
delivery_status | Delivery status | Read-only | See Delivery status |
event_sources | Snap App Id to be associated with the Ad Squad | O | Availble for Optimization Goals APP_REENGAGE_OPEN / APP_REENGAGE_PURCHASE and Dynamic Product Ads when using APP_INSTALL / DEEP_LINK |
** See Reach And Frequency
Event sources
Example request setting the
event_sources
to Snap App ID
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adsquads": [{"id": "7e52b0f4-a3fc-46f2-9a33-f03d71c55047","name": "Badger Supplies Ad Squad","status": "ACTIVE","campaign_id": "7b15f643-3052-4eb3-b5e1-09fa1ce0116a","type": "SNAP_ADS","targeting": {"regulated_content": false,"geos": [{"country_code": "uk"}],"devices": [{"os_type": "iOS"}],"enable_targeting_expansion": false},"placement_v2": {"config": "AUTOMATIC"},"billing_event": "IMPRESSION","bid_strategy": "AUTO_BID","daily_budget_micro": 50000000,"start_time": "2021-11-01T17:12:49.707Z","end_time": "2021-12-01T17:12:49.707Z","optimization_goal": "SWIPES","event_sources": {"MOBILE_APP": ["8b5b83ec-c593-4a64-9c6d-a0eb9da0edb8"]}}]}'
https://adsapi.snapchat.com/v1/campaigns/88539b6b-93f2-4b3a-8181-ca869cb45088/adsquads
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "6011886c00ff09fe1978d146130001737e616473617069736300016275696c642d65386534326330362d312d3431372d3000010113",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "7e52b0f4-a3fc-46f2-9a33-f03d71c55047",
"updated_at": "2021-01-27T15:36:13.676Z",
"created_at": "2020-11-11T10:24:46.334Z",
"name": "Badger Supplies Ad Squad",
"status": "ACTIVE",
"campaign_id": "7b15f643-3052-4eb3-b5e1-09fa1ce0116a",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"geos": [
{
"country_code": "uk"
}
],
"devices": [
{
"os_type": "iOS"
}
],
"enable_targeting_expansion": false
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 50000000,
"start_time": "2021-11-01T17:12:49.707Z",
"end_time": "2021-12-01T17:12:49.707Z",
"optimization_goal": "SWIPES",
"event_sources": {
"MOBILE_APP": [
"8b5b83ec-c593-4a64-9c6d-a0eb9da0edb8"
]
},
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED"
}
}
]
}
The event_sources
attribute defines a Snap App ID which is associated with the Ad Squad, events triggered by the App will be eligible for conversions and can also used to set up Mobile custom audiences. It is recommended that you add event_sources
to any Ad Squad using the optimization goals APP_INSTALLS or DEEP_LINK.
The event_sources
attribute is a prerequisite for App Install state targeting.
Bid Strategy
Example request setting
bid_strategy
andbid_micro
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adsquads":[{"id": "9077bb86-fb9a-4ded-9da9-67bc2e1dd6c5","name": "Badger Supplies Ad Squad - event sources","status": "ACTIVE","campaign_id": "4813d068-370b-45f6-a8d6-e01de878f1b5","type": "SNAP_ADS","targeting": {"regulated_content": false,"geos": [{"country_code": "uk"}],"devices": [{"os_type": "ANDROID"}],"enable_targeting_expansion": true},"placement_v2": {"config": "AUTOMATIC"},"bid_micro": 1000000,"bid_strategy": "TARGET_COST","daily_budget_micro": 50000000,"start_time": "2021-01-30T23:43:45.000Z","end_time": "2021-02-08T07:59:59.000Z","optimization_goal": "APP_INSTALLS","event_sources": {"MOBILE_APP": ["9b5b83ec-c593-4a64-9c6d-a0eb9da0edb9"]}}]}'
https://adsapi.snapchat.com/v1/campaigns/4813d068-370b-45f6-a8d6-e01de878f1b5/adsquads
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "60118f4f00ff026a940c321500ff0001737e616473617069736300016275696c642d65386534326330362d312d3431372d3000010143",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "9077bb86-fb9a-4ded-9da9-67bc2e1dd6c5",
"updated_at": "2021-01-27T16:05:35.770Z",
"created_at": "2021-01-27T16:03:14.293Z",
"name": "Badger Supplies Ad Squad - event sources",
"status": "ACTIVE",
"campaign_id": "4813d068-370b-45f6-a8d6-e01de878f1b5",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"geos": [
{
"country_code": "uk"
}
],
"devices": [
{
"os_type": "ANDROID"
}
],
"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": "2021-01-30T23:43:45.000Z",
"end_time": "2021-02-08T07:59:59.000Z",
"optimization_goal": "APP_INSTALLS",
"event_sources": {
"MOBILE_APP": [
"9b5b83ec-c593-4a64-9c6d-a0eb9da0edb9"
]
},
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD",
"creation_state": "PUBLISHED"
}
}
]
}
On the 20th of March 2020 we announced the deprecation of the attributes auto_bid
and target_bid
, please ensure that you have switched to using only bid_strategy
by the 20th of June 2020. Creation of AdSquads and updating of AdSquads should only use the bid_strategy
attribute.
The API will return the attributes auto_bid
/target_bid
when requesting the AdSquad entity but these attributes should be stripped out for any update AdSquad requests you make or the API will reject your requests come the 20th June 2020.
The below table outlines the relationship between the old bid settings and bid_strategy
.
auto_bid | target_bid | bid_micro | bid_strategy |
---|---|---|---|
true | false | —– | AUTO_BID |
false | false | used for bid | LOWEST_COST_WITH_MAX_BID |
false | true | used for bid | TARGET_COST |
The bid_strategy
attribute defines the bid strategy used for the Ad Squad, bid_strategy
is an enumeration field which should be set to the bidding strategy of your choice, given the below options.
bid_strategy | Description | Additional Settings |
---|---|---|
AUTO_BID | Drive the most efficient cost per action while spending your budget | —– |
LOWEST_COST_WITH_MAX_BID | Bids conservatively at or below your desired bid | use bid_micro to set bid |
MIN_ROAS** | Achieves the most purchase value while maintaining a minimum return on your ad spend, this strategy requires that that APP_PURCHASE event along with the price parameter has been implemented |
use roas_value_micro to set minimum ROAS in micro currency, one full unit of a currency in roas_value_micro represents a ROAS of 1, roas_value_micro value can be set between 10000 and a maximum of 100000000. |
TARGET_COST | Achieves the most volume while aiming to keep your average cost per action below your target cost | use bid_micro to set bid |
** The MIN_ROAS bid strategy requires 50 PURCHASE conversions within 7 days, the price
parameter needs to be passed with the PURCHASE event and there needs to be at least 3 unique price
values.
Optimization Goals allowed per Bid Strategy.
bid_strategy | Optimization goals |
---|---|
AUTO_BID | APP_INSTALLS, APP_PURCHASE, IMPRESSIONS, PIXEL_PURCHASE, STORY_OPENS, SWIPES, USES, VIDEO_VIEWS, VIDEO_VIEWS_15_SEC |
LOWEST_COST_WITH_MAX_BID | No restrictions |
MIN_ROAS | APP_PURCHASE |
TARGET_COST | APP_INSTALLS, 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 |
MIN_ROAS examples
The Minimum ROAS (MIN_ROAS) bid strategy allows advertisers to define their desired ROAS in relation to the currency
they are using within that Ad Account entity.
MIN_ROAS assumes the advertiser has implemented the in-app event APP_PURCHASE
with the price
parameter via their MMP.
The roas_value_micro
is used to define the expected ROAS and is defined in micro currency
Examples using “bid_strategy”:“MIN_ROAS”;
- A
roas_value_micro
1000000 in an Ad Account using the currency USD, optimizes to deliver $1 for every $1 in spend. - A
roas_value_micro
500000 in an Ad Account using the currency GBP, optimizes to deliver £0.50 for every £1 in spend. - A
roas_value_micro
1500000 in an Ad Account using the currency EUR, optimizes to deliver €1.50 for every €1 in spend.
Placement V2
On the 20th of March 2020 we announced the deprecation of the placement
attribute in favour of placement_v2
, please ensure that you have switched to using placement_v2
by the 20th of June 2020. This also means that content targeting via included_content_types
and excluded_content_types
moves from the Ad Squad level attributes to the attributes inclusion
and exclusion
which are defined within placement_v2
.
Your App will not be able to set or amend the placement
attribute via Creation or Update requests for any Ad Squads past the 20th June 2020. Any AdSquads that have only the placement
attribute set will continue to serve based on that setting post 20th June 2020
The below table outlines the relationship between placement
and placement_v2
.
placement | placement_v2 - snapchat_positions |
---|---|
SNAP_ADS | INTERSTITIAL_USER, INTERSTITIAL_CONTENT, INSTREAM |
USER_STORIES | INTERSTITIAL_USER |
CONTENT | INSTREAM |
DISCOVER_FEED | FEED |
CAMERA | CAMERA |
- | GAMES |
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, GAMING, GENERAL_LIFESTYLE, FOOD, SPORTS, YOUNG_BOLD |
exclusion | Details about the content types to be included | O | {“content_types”: [List of possible content types]}. Ad Squad must be of type SNAP_ADS. snapchat_positions must include INSTREAM. Inclusion and exclusion content types must be mutually exclusive NEWS, ENTERTAINMENT, SCIENCE_TECHNOLOGY, BEAUTY_FASHION, MENS_LIFESTYLE, WOMENS_LIFESTYLE, GAMING, GENERAL_LIFESTYLE, FOOD, SPORTS, YOUNG_BOLD |
Placement v2 gives advertisers more options and control over the location and context of where ads are placed, and includes all the advanced placement options that Snapchat has to offer. The inclusion
and exclusion
attributes within placement_v2
replaces the previously used included_content_types
and included_content_types
attributes which were defined at Ad Squad level.
config
Value | Description |
---|---|
AUTOMATIC | Snapchat will choose the optimal placement for your ad across all of Snapchat and the Audience Extension. 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 |
GAMES | Ads run as Commercials within Snap Games. Ad Squad type must be SNAP_ADS |
AUDIENCE_EXTENSION | Ads run in the Snapchat Audience Network, this feature is currently in closed Beta |
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_strategy
must be set to ‘LOWEST_COST_WITH_MAX_BID’bid_micro
must be setoptimization_goal
must be one of IMPRESSIONS, USES, SWIPES, VIDEO_VIEWS, VIDEO_VIEWS_15_SEC or STORY_OPENS
pacing_type
is immutable and can be changed given the correct validations are in place.
Squad Optimization Goals
Goal-Based Bidding (GBB) allows a squad to be optimized toward a specific outcome.
Optimization Goal changes how the squad’s bid_micro is interpreted.
Note: No matter what Optimization Goal is selected, the Billing Event will still be IMPRESSION. This may change in the future.
Optimization Goal | Bid Interpretation | Details |
---|---|---|
IMPRESSIONS | Cost Per 1000 Impressions (CPM) | bid_micro will not be exceeded |
SWIPES | Target Cost Per Swipe | bid_micro is treated as a goal, not a maximum, and can be exceeded |
APP_INSTALLS | Target Cost Per Install | bid_micro is treated as a goal, not a maximum, and can be exceeded |
VIDEO_VIEWS | Target Cost per 2 second Video View | bid_micro is treated as a goal, not a maximum, and can be exceeded |
VIDEO_VIEWS_15_SEC | Target Cost per 15 second Video View | bid_micro is treated as a goal, not a maximum, and can be exceeded |
USES | Cost Per Use (of filter) | bid_micro is treated as a goal, not a maximum, and can be exceeded |
STORY_OPENS | Target Cost Per Story Open for Story Ads | bid_micro is treated as a goal, not a maximum, and can be exceeded |
PIXEL_PAGE_VIEW | Target Cost Per PAGE_VIEW on web | bid_micro is treated as a goal, not a maximum, and can be exceeded |
PIXEL_ADD_TO_CART | Target Cost Per ADD_TO_CART on web | bid_micro is treated as a goal, not a maximum, and can be exceeded |
PIXEL_PURCHASE | Target Cost Per PURCHASE on web | bid_micro is treated as a goal, not a maximum, and can be exceeded |
PIXEL_SIGNUP | Target Cost Per SIGNUP on web | bid_micro is treated as a goal, not a maximum, and can be exceeded |
APP_ADD_TO_CART** | Target Cost Per ADD_TO_CART on app | bid_micro is treated as a goal, not a maximum, and can be exceeded |
APP_PURCHASE** | Target Cost Per PURCHASE on app | bid_micro is treated as a goal, not a maximum, and can be exceeded |
APP_SIGNUP** | Target Cost Per PURCHASE on app | bid_micro is treated as a goal, not a maximum, and can be exceeded |
APP_REENGAGE_OPEN† | Target Cost Per App open | bid_micro is treated as a goal, not a maximum, and can be exceeded |
APP_REENGAGE_PURCHASE† | Target Cost Per App Purchase | bid_micro is treated as a goal, not a maximum, and can be exceeded |
Optimization goals PIXEL_ADD_TO_CART, PIXEL_PURCHASE, PIXEL_SIGNUP, APP_ADD_TO_CART, APP_PURCHASE and APP_SIGNUP are auto enabled only for ad accounts that meet the following criteria:
- Pixel; Ad Account has Snap Pixel created and installed on website, relevant Pixel events like ADD_TO_CART, SIGNUP and PURCHASE have been configured successfully
- In-App events; App has been set to trigger and pass relevant events, ADD_TO_CART, SIGNUP and PURCHASE via the MMP
- Both; Ad account must be driving at least 50+ attributed conversions for the event over a rolling 7-day period, based on a 28d swipe and 1d view attribution window † These optimization goals requires App Install State targeting for the App where the re-engagement takes place, see targeting example
Squad Optimization Goal Per Ad Type
This table outlines the Optimization Goals availability per Ad Type.
Optimization Goal | Ad Types |
---|---|
IMPRESSIONS | SNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, FILTER, LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_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 |
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 |
APP_REENGAGE_OPEN | DEEP_LINK, COLLECTION, STORY (COLLECTION and STORY Ads require deep_link_properties in Creative entity) |
APP_REENGAGE_PURCHASE | DEEP_LINK, COLLECTION, STORY (COLLECTION and STORY Ads require deep_link_properties in Creative entity) |
Squad Optimization Window
The optimization_window attribute allows you to optimize the AdSquad auction given a desired conversion window.
The optimization_window can only be used in conjunction with one of the following optimization goals, APP_INSTALLS, APP_PURCHASE, APP_SIGNUP, APP_ADD_TO_CART or APP_REENGAGE_OPEN.
Value | Description |
---|---|
SWIPE_28DAY_VIEW_1DAY | 28 Day Swipe, 1 Day View |
SWIPE_7D | 7 Day Swipe |
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 | Allowed Optimization Goals | string | IMPRESSIONS, SWIPES, VIDEO_VIEWS_15_SEC, VIDEO_VIEWS, STORY_OPENS, USES |
time_interval | Interval during which the frequency cap rule is applied. frequency_cap_count is reset at the end of the interval. (Max 30 days or 720 hours) | integer | |
frequency_cap_interval | Unit for time_interval | string | HOURS, DAYS |
"cap_and_exclusion_config": {
"frequency_cap_config": [
{
"frequency_cap_count": 4,
"frequency_cap_type": "impressions",
"time_interval": 48,
"frequency_cap_interval": "hours"
}
]
}
Third-Party Tracking Tags
Snap partners with select vendors are able to use a “tagless” integration, where measurement can be set at the ad squad level, which will then apply to all child ad units within the ad Squad.
Measurement Solution | Vendor Name |
---|---|
Viewability | Moat |
Viewability | DoubleVerify |
How to Apply Third Party Tracking
To apply third-party tracking for tagless integrations at the ad squad level, set the following value for the appropriate attribute:
Measurement Solution | Vendor Name | Required | Possible values |
---|---|---|---|
measurement_provider_names | Flag denotes auto-tagging of all child ads in the ad squad when set to the approved vendor’s enum. Supports Moat viewability tracking | O | MOAT_SS, DOUBLEVERIFY |
Ad Scheduling
With ad_scheduling_config, you can explicitly set which days of the week and, to what hours within each day your ads should run.
- Ad Squads that use ad scheduling must have a lifetime_budget_micro set instead of a daily_budget_micro
- The schedule set in ad_scheduling_config cannot conflict with the flight dates of the Ad Squad
- Ad Squads should have a minimum interval of 1 hour across any day they select to run on
- Ad scheduling will respect the user’s timezone. The flight dates will continue to respect the ad account timezone. So an Ad Squad scheduled for Sunday morning 8-11 AM will show for a user based in Los Angeles between 8 AM and 11 AM Pacific time and for a New York based user between 8 AM - 11 AM Eastern Time which is 5AM - 8AM Pacific Time.
- Ad scheduling is mutable
- Ad scheduling config can supoort multiple ranges per day
Usage
"ad_scheduling_config": {
"monday": {
"hour_of_day": [1, 2, 3, 8, 9, 10]
},
"tuesday": {
"hour_of_day": [11, 12, 13]
}
}
This would describe an ad running on Monday from 1am - 3am && 8am - 10am and Tuesday from 11am - 1pm. The possible values for the keys are: monday, tuesday, wednesday, thursday, friday, saturday, sunday
Attribute | Description | Type | Possible Values |
---|---|---|---|
hour_of_day | array of integers specifying the times of day | array of integers | 0-23 |
Targeting Spec Examples
See the Targeting Spec Examples
Content Type
included_content_types and excluded_content_types can be used to specify more granular placement depending on the type of content.
Depending on the placement, included_content_types and excluded_content_types may or may not be specified.
placement | included_content_types | excluded_content_types |
---|---|---|
SNAP_ADS | Cannot be specified | Can be specified |
CONTENT | Can be specified | Can be specified |
USER_STORIES | Cannot be specified | Cannot be specified |
DISCOVER_FEED | Cannot be specified | Cannot be specified |
Create an Ad Squad
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
curl "https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads?return_placement_v2=true" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b00b1500ff0476bcfb96faa20001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010b",
"adsquads": [
{
"sub_request_status": "success",
"adsquad": {
"id": "0633e159-0f41-4675-a0ba-224fbd70ac4d",
"updated_at": "2016-08-14T05:52:45.186Z",
"created_at": "2016-08-14T05:52:45.186Z",
"name": "Ad Squad Apples",
"status": "PAUSED",
"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
"type": "SNAP_ADS",
"targeting": {
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 1000000000,
"start_time": "2016-08-11T22:03:58.869Z",
"optimization_goal": "IMPRESSIONS"
}
},
{
"sub_request_status": "success",
"adsquad": {
"id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"updated_at": "2016-08-14T05:58:55.409Z",
"created_at": "2016-08-14T05:58:55.409Z",
"name": "Ad Squad Uno",
"status": "ACTIVE",
"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
"type": "SNAP_ADS",
"targeting": {
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 1000000,
"auto_bid": false,
"target_bid": true,
"bid_strategy": "TARGET_COST",
"daily_budget_micro": 1000000000,
"start_time": "2016-08-11T22:03:58.869Z",
"optimization_goal": "IMPRESSIONS"
}
}
]
}
This endpoint retrieves all ad squads within a specified campaign.
HTTP Request
GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads
Parameters
Parameter | Default | Description |
---|---|---|
campaign_id | Campaign ID | |
return_placement_v2 | true | optional parameter for retrieving placement_v2 attribute |
Get All Ad Squads under an Ad Account
curl "https://adsapi.snapchat.com/v1/adaccounts/8cf88872-048b-4447-95d1-eb48231788be/adsquads?return_placement_v2=true" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b00b1500ff0476bcfb96faa20001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010b",
"adsquads": [
{
"sub_request_status": "success",
"adsquad": {
"id": "0633e159-0f41-4675-a0ba-224fbd70ac4d",
"updated_at": "2016-08-14T05:52:45.186Z",
"created_at": "2016-08-14T05:52:45.186Z",
"name": "Ad Squad Apples",
"status": "PAUSED",
"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
"type": "SNAP_ADS",
"targeting": {
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 1000000000,
"start_time": "2016-08-11T22:03:58.869Z",
"optimization_goal": "IMPRESSIONS"
}
},
{
"sub_request_status": "success",
"adsquad": {
"id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"updated_at": "2016-08-14T05:58:55.409Z",
"created_at": "2016-08-14T05:58:55.409Z",
"name": "Ad Squad Uno",
"status": "ACTIVE",
"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
"type": "SNAP_ADS",
"targeting": {
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 1000000,
"auto_bid": false,
"target_bid": true,
"bid_strategy": "TARGET_COST",
"daily_budget_micro": 1000000000,
"start_time": "2016-08-11T22:03:58.869Z",
"optimization_goal": "IMPRESSIONS"
}
}
]
}
This endpoint retrieves all ad squads within a specified ad account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/adsquads
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID | |
return_placement_v2 | true | optional parameter for retrieving placement_v2 attribute |
Get a Specific Ad Squad
curl "https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe?return_placement_v2=true" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b00bd200ff0a1092e59e2ec90001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"adsquads": [
{
"sub_request_status": "success",
"adsquad": {
"id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"updated_at": "2016-08-14T05:58:55.409Z",
"created_at": "2016-08-14T05:58:55.409Z",
"name": "Ad Squad Uno",
"status": "ACTIVE",
"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
"type": "SNAP_ADS",
"targeting": {
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 1000000,
"auto_bid": false,
"target_bid": true,
"bid_strategy": "TARGET_COST",
"daily_budget_micro": 1000000000,
"start_time": "2016-08-11T22:03:58.869Z",
"optimization_goal": "IMPRESSIONS"
}
}
]
}
This endpoint retrieves a specific ad squad.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/<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
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* |
delivery_status | Delivery status | Read-only | See Delivery status |
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
curl -X POST \
-d '{"ads":[{"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe", "creative_id":"c1e6e929-acec-466f-b023-852b8cacc18f", "name": "Ad One", "type": "SNAP_AD", "status": "PAUSED"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b018c500ff0d22d3cefd730d0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010107",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:07:50.241Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "PAUSED",
"type": "SNAP_AD"
}
}
]
}
This endpoint creates an Ad within an Ad Squad.
HTTP Request
POST https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Parameters
Parameter | Default | Description |
---|---|---|
ad_squad_id | Ad Squad ID |
Update an Ad
curl -X PUT \
-d '{"ads":[{"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4", "ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe", "creative_id":"c1e6e929-acec-466f-b023-852b8cacc18f", "name": "Ad One", "type": "SNAP_AD", "status": "ACTIVE"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/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
curl "https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01b3400ff0608a82948df6b0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "2ded6d53-0805-4ff8-b984-54a7eb5c8918",
"updated_at": "2016-08-14T07:18:05.699Z",
"created_at": "2016-08-14T07:18:05.699Z",
"name": "Ad Two",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "PAUSED",
"type": "SNAP_AD"
}
},
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:14:45.174Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "ACTIVE",
"type": "SNAP_AD"
}
}
]
}
This endpoint retrieves all ads within a specified ad squad.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Parameters
Parameter | Default | Description |
---|---|---|
ad_squad_id | Ad Squad ID |
Get All Ads under a Campaign
curl "https://adsapi.snapchat.com/v1/campaigns/77b217e4-7a2c-455b-9fd6-02a55c924177/ads" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5f8453bc00ff0d27cde61b08060001737e616473617069736300016275696c642d32626566663136392d312d3339322d3000010102",
"paging": {},
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "0bfdb79e-38cc-470f-8593-789b51b83c97",
"updated_at": "2018-09-12T18:11:00.831Z",
"created_at": "2018-09-12T18:02:25.767Z",
"name": "Fur Coat Shine",
"ad_squad_id": "7fc34710-1c46-417e-bfc6-c4d5696aac4f",
"creative_id": "7ef92e04-e99f-4e22-9496-5cc82b129c77",
"status": "ACTIVE",
"type": "APP_INSTALL",
"render_type": "STATIC",
"review_status": "APPROVED",
"approval_type": "FULL",
"delivery_status": [
"VALID"
]
}
},
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "54d00642-58bb-4db4-8a04-84ffd56258f7",
"updated_at": "2018-08-31T16:34:37.673Z",
"created_at": "2018-08-31T15:36:57.096Z",
"name": "Fur coat conditioner",
"ad_squad_id": "71ca9842-4628-4660-9ba3-3be2e7d15778",
"creative_id": "348e9545-5706-4ff6-8701-2971db6e0017",
"status": "ACTIVE",
"type": "APP_INSTALL",
"render_type": "STATIC",
"review_status": "APPROVED",
"approval_type": "FULL",
"delivery_status": [
"VALID"
]
}
},
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "d1e3c618-b4a0-46ec-8982-b3b357c35507",
"updated_at": "2018-08-31T15:48:52.200Z",
"created_at": "2018-08-31T13:43:41.986Z",
"name": "Claw polish",
"ad_squad_id": "71ca9842-4628-4660-9ba3-3be2e7d15778",
"creative_id": "e261479b-4f2b-443f-8fde-583816fb0167",
"status": "ACTIVE",
"type": "APP_INSTALL",
"render_type": "STATIC",
"review_status": "APPROVED",
"approval_type": "FULL",
"delivery_status": [
"VALID"
]
}
}
]
}
This endpoint retrieves all Ads under a specified Campaign.
HTTP Request
GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/ads
Parameters
Parameter | Default | Description |
---|---|---|
campaign_id | Campaign ID |
Get All Ads under an Ad Account
curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/ads" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01b3400ff0608a82948df6b0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "2ded6d53-0805-4ff8-b984-54a7eb5c8918",
"updated_at": "2016-08-14T07:18:05.699Z",
"created_at": "2016-08-14T07:18:05.699Z",
"name": "Ad Two",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "PAUSED",
"type": "SNAP_AD"
}
},
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:14:45.174Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "ACTIVE",
"type": "SNAP_AD"
}
}
]
}
This endpoint retrieves all Ads under a specified Ad account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/ads
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Get a Specific Ad
curl "https://adsapi.snapchat.com/v1/ads/e8d6217f-32ab-400f-9e54-39a86a7963e4"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01adc00ff0a5290ad9d42c00001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010103",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:14:45.174Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "ACTIVE",
"type": "SNAP_AD"
}
}
]
}
This endpoint retrieves a specific ad.
HTTP Request
GET https://adsapi.snapchat.com/v1/ads/{ad_id}
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the ad to retrieve |
Delete an Ad
curl -X DELETE "https://adsapi.snapchat.com/v1/ads/2ded6d53-0805-4ff8-b984-54a7eb5c8918" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01b6200ff05d100ff30ca9b1d0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010101",
"ads": []
}
This endpoint deletes a specific ad.
HTTP Request
DELETE https://adsapi.snapchat.com/v1/ads/{ad_id}
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the ad to delete |
Third-Party Tracking Tags
On the 1st of January 2020 we will be sunsetting the fields on_swipe_tracking_urls
and third_party_tracking_urls
.
From the 1st of January 2020 it won’t be possible to update an Ad entity without removing the third-party tracking from the deprecated fields. This tracking can instead be implemented within the two fields third_party_on_swipe_tracking_urls
and third_party_paid_impression_tracking_urls
.
If you are trafficking third-party tags to the fields on_swipe_tracking_urls
and/or third_party_tracking_urls
you should amend your app as soon as possible and make use of the corresponding fields third_party_on_swipe_tracking_urls
and third_party_paid_impression_tracking_urls
.
Additionally MOAT tracking at Ad level will also be sunset on the 1st of January 2020, for any Ads where you wish to implement MOAT tracking you should instead activate the MOAT tracking at AdSquad level, using the new measurement_provider_names
attribute. Activation at AdSquad level will apply MOAT tracking to all Ad entities within the AdSquad.
Snap currently allows third-party tags from DCM, MDAR and Integral Ad Science (IAS).
MOAT tracking should be implemented at AdSquad level tracking activation via the measurement_provider_names
attribute.
curl -X PUT \
-d '{"ads":[{"id": "ebb64f61-0e12-4f3c-a55c-71a9a6d1ea63", "ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe", "creative_id":"c1e6e929-acec-466f-b023-852b8cacc18f", "name": "Ad One", "type": "SNAP_AD", "status": "ACTIVE", "third_party_paid_impression_tracking_urls": ["https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.222222222;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"],"third_party_on_swipe_tracking_urls": ["https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.333333333;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"]}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "58bb7c5000ff06616e9fa0e86e0001737e616473617069736300016275696c642d33333562626234342d312d35302d330001013d",
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "ebb64f61-0e12-4f3c-a55c-71a9a6d1ea63",
"updated_at": "2017-03-18T00:16:17.690Z",
"created_at": "2017-03-18T00:16:17.690Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"third_party_paid_impression_tracking_urls": [
{
"trackingUrlMetadata": null,
"expandedTrackingUrl": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.222222222;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?",
"tracking_url": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.222222222;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"
}
],
"third_party_on_swipe_tracking_urls": [
{
"trackingUrlMetadata": null,
"expandedTrackingUrl": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.33333333;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?",
"tracking_url": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.33333333;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"
}
],
"status": "PAUSED",
"type": "SNAP_AD",
"review_status": "APPROVED"
}
}
]
}
Additional Ad Attributes
Attribute | Description | Required |
---|---|---|
third_party_on_swipe_tracking_urls | Third-party swipe tags, executed on swipe of attachment | O |
third_party_paid_impression_tracking_urls | Third-party impression tags, executed on ad impression | O |
DEPRECATED, Use attribute third_party_on_swipe_tracking_urls |
- | |
DEPRECATED, Use attribute third_party_paid_impression_tracking_urls |
- |
Approved Third Party Tracking URL domains
URL | Description |
---|---|
secure-gl.imrworldwide.com | |
ad.doubleclick.net | |
pixel.adsafeprotected.com | |
DEPRECATED, Use AdSquad level tracking activation |
How to get tags
DCM and IAS: Refer to your DCM/IAS Account Manager to request tags or generate them using the campaign management tools.
mDAR: Clients should request their Snapchat Account Manager to provide a tag.
Notes
- Ensure all tags are secure and use https
- Choose standard type 1x1 pixel and not Javascript or iframe
- Make sure cachebusting parameter is ~.~TIMESTAMP~.~ and not [timestamp]
URL Macros
There are several dynamic placeholder macros that can be used within the URL that are replaced on-the-fly:
Macro | Description |
---|---|
~.~SERVER_ORG_ID~.~ | Organization ID |
~.~SERVER_AD_ACCOUNT_ID~.~ | Ad Account ID |
~.~SERVER_CAMPAIGN_ID~.~ | Campaign ID |
~.~SERVER_AD_SQUAD_ID~.~ | Ad Squad ID |
~.~SERVER_CREATIVE_ID~.~ | Creative ID |
~.~SERVER_AD_ID~.~ | Ad ID |
~.~SERVER_MOAT_PRODUCT_TYPE~.~ | Ad Product Type |
~.~TIMESTAMP~.~ | Timestamp |
Media
Media is a single video that can be used to construct Creative. Media objects are owned by an Ad Account and can be used by multiple Creatives simultaneously.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
download_link | URL to Media File | READ-ONLY | |
media_status | Media Status | READ-ONLY | PENDING_UPLOAD, READY |
name | Media name | R | |
type | Media Type | R | VIDEO, IMAGE, LENS_PACKAGE |
lens_package_metadata | Metadata for lens media created by Lens Studio | READ-ONLY |
Create Media
curl -X POST \
-d '{"media": [{"name":"Media A - Video", "type":"VIDEO","ad_account_id":"{ad_account_id}"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/media
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b00d1900ff08a0dae50ab27a0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010b",
"media": [
{
"sub_request_status": "success",
"media": {
"id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"updated_at": "2016-08-14T06:18:01.855Z",
"created_at": "2016-08-14T06:18:01.855Z",
"name": "Media A - Video",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "VIDEO",
"media_status": "PENDING_UPLOAD"
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/media
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Upload Media - Video
Name | Description | Dimensions | File size | File type | Length seconds |
---|---|---|---|---|---|
Top Snap | Used as Top Snap video in Snap Ads, Top Snap specs | 1080 x 1920 px | 32MB max size , up to 1 GB allowed using chunked upload | mp4, mov | min 3 seconds, max 180 seconds |
Long form video | Used for Long form video attachment, Long Form video attachment specs | min width 1080 px | 32MB max size , up to 1 GB allowed using chunked upload | mp4, mov | min 15 seconds |
curl -X POST -H 'content-type: multipart/form-data' -F 'file=@"/files/MOV_1808.mov";filename="MOV_1808.mov"' \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/media/a7bee653-1865-41cf-8cee-8ab85a205837/upload
The above command returns JSON structured like this:
{
"result": {
"id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"updated_at": "2016-08-14T06:24:28.378Z",
"created_at": "2016-08-14T06:23:37.086Z",
"name": "Media A - Video",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "VIDEO",
"media_status": "READY",
"file_name": "sample.mov"
},
"request_status": "success",
"request_id": "57b00e9a00ff0ccb4293400c840001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010103"
}
This endpoint receives the actual video data for the media. Snap Inc. hosts all media on behalf of the advertiser.
HTTP Request
POST https://adsapi.snapchat.com/v1/media/{media_id}/upload
Parameters
Parameter | Default | Description |
---|---|---|
media_id | Media ID |
Upload Media - Image
Media of the type IMAGE can be used in various different types of Creatives.
Name | Description | Dimensions | File size | File type |
---|---|---|---|---|
Top Snap Image | Used as Top Snap in Snap Ads, IMAGE type top snaps are converted into 5 sec videos and rendered on the client as videos, Top Snap specs | min 1080 x 1920 px | 5 MB max size | PNG, JPG |
App Icon | Used for App Install and Deep Link creatives, image shouldn’t have any borders or padding, App Install attachment specs , Deep Link attachment specs | aspect ratio 1:1 (square), min 200 x 200 px, max 2000 x 2000 px | - | PNG |
Preview Image | Used as Thumbnail in Story Ad Creatives, Story Ad specs | aspect ratio 3:5, min 360 x 600 px | 2 MB max size | PNG |
Logo Image | Used as Logo overlaid on Thumbnail in Story Ad Creatives, Story Ad specs | 993 x 284 px | 2 MB max size | PNG |
Audience Filter | Used as Filter, at least 50% of the image must be transparent, Filter specs | 1080 x 2340 px | 300kb or less | PNG |
Supported Optimization goals for ads using IMAGE type media are: IMPRESSIONS, SWIPES, APP_INSTALLS
curl -X POST -H 'content-type: multipart/form-data' -F 'file=@"/files/app_icon.png";filename="app_icon.png"' \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/media/8adc3db7-8148-4fbf-999c-8d2266369d75/upload
The above command returns JSON structured like this:
{
"result": {
"id": "77062ed3-4abf-49a8-ac3f-8157cf14cb41",
"updated_at": "2017-04-14T19:39:05.969Z",
"created_at": "2017-04-14T19:19:59.708Z",
"name": "IMAGE media",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d75",
"type": "IMAGE",
"media_status": "READY",
"file_name": "app_icon.png",
"download_link": "https://storage.googleapis.com/ad-manager-creatives-production/77062ed3-4abf-49a8-ac3f-8157cf14cb41/7d935b22-eb12-41b8-9e34-713b64f2e3b3.png"
},
"request_status": "SUCCESS",
"request_id": "58f1255800ff0d03cc7c0c03380001737e616473617069736300016275696c642d64373565633561632d312d35382d3100010"
}
HTTP Request
POST https://adsapi.snapchat.com/v1/media/{media_id}/upload
Parameters
Parameter | Default | Description |
---|---|---|
media_id | Media ID |
Upload Large Media (Chunked)
This endpoint receives the actual video data for the media. Snapchat hosts all media on behalf of the advertiser.
Files larger than 32MB need to be uploaded in chunks.
- Split the large file
- Initialize a chunked upload request
- Get the “add_path”, “finalize_path” and “upload_id” from the response, these will be unique to your upload
- Upload all parts of the file using the “add_path” , you will need to prepend it with https://adsapi.snapchat.com
- Finalize the chunked upload request using the “finalize_path”, you will need to prepend it with https://adsapi.snapchat.com
Request and Parameters for INIT
POST https://adsapi.snapchat.com/v1/media/{media_id}/multipart-upload-v2?action=INIT
Parameter | Description |
---|---|
action | INIT (query param) |
file_name | File Name |
file_size | Total file size in bytes (cannot exceed 1GB) |
number_of_parts | Number of parts to expect |
Request and Parameters for ADD
POST https://adsapi.snapchat.com + add_path
Parameter | Description |
---|---|
file | File Part |
part_number | File part number, used during re-assembly of file |
upload_id | Chunked Upload ID from INIT |
Request and Parameters for FINALIZE
POST https://adsapi.snapchat.com + finalize_path
Parameter | Description |
---|---|
upload_id | Chunked Upload ID from INIT |
1. Split the large file
Example: split -b 2m lfv.mov split_lfv.
2. Initialize a chunked upload request
curl -X POST -H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: multipart/form-data" \
-F "file_name=lfv.mov" \
-F "file_size=4887527" \
-F "number_of_parts=3" \
"https://adsapi.snapchat.com/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=INIT"
3. Extract upload_id, add_path and finalize_path from response:
{
"request_status":"SUCCESS",
"request_id":"57e56c0b00ff0e1b43229b96350001737e616473617069736300016275696c642d62646338336131372d312d31352d3100010109",
"upload_id":"cffc3975-f2b3-40d2-bf81-f0e7d97b9af5",
"add_path":"/us/v1/media/7bd44f53-5de7-41c4-90c7-50633e5dbb7e/multipart-upload-v2?action=ADD",
"finalize_path":"/v1/media/7bd44f53-5de7-41c4-90c7-50633e5dbb7e/multipart-upload-v2?action=FINALIZE"
}
4. Upload all parts using the add_path prepended with https://adsapi.snapchat.com:
curl -X POST -H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: multipart/form-data" \
-F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
-F "file=@split_lfv.aa" \
-F "part_number=1" \
"https://adsapi.snapchat.com/us/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=ADD"
curl -X POST -H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: multipart/form-data" \
-F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
-F "file=@split_lfv.ab" \
-F "part_number=2" \
"https://adsapi.snapchat.com/us/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=ADD"
curl -X POST -H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: multipart/form-data" \
-F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
-F "file=@split_lfv.ac" \
-F "part_number=3" \
"https://adsapi.snapchat.com/us/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=ADD"
5. Finalize the chunked upload request using finalize_path prepended with https://adsapi.snapchat.com
curl -X POST -H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: multipart/form-data" \
-F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
"https://adsapi.snapchat.com/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=FINALIZE"
The above command returns JSON structured like this:
{
"result": {
"id": "7536bbc5-0074-4dc4-b654-5ba9cd9f9441",
"updated_at": "2016-09-23T17:59:23.826Z",
"created_at": "2016-09-23T17:51:07.799Z",
"name": "Media Chunked - Video",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "VIDEO",
"media_status": "READY",
"file_name": "lfv.mov",
"download_link": "https://storage.googleapis.com/ad-manager-creatives-production-us/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/b195bd7c-aa7b-44c4-83a5-2c12e77a8784.mov"
},
"request_status": "SUCCESS",
"request_id": "57e56d7a00ff0b82bd232ea3d40001737e616473617069736300016275696c642d62646338336131372d312d31352d3100010134"
}
Get All Media
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 entities associated with an ad account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/media
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Get a Specific Media
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 entity.
HTTP Request
GET https://adsapi.snapchat.com/v1/media/{media_id}
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the media to retrieve |
Get Preview for a Specific Media
curl "https://adsapi.snapchat.com/v1/media/8e781365-ce4c-4336-8c53-f6a1f7c50af1/preview" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5aa8450b00ff00ff741e879aff00580001737e816473617069736300016275696x642d37633033663563332d312d3134392d310001015e",
"expires_at": "2018-03-14T21:39:23.303Z",
"link": "https://adsapisc.appspot.com/media/video_preview?media_id=8e781365-ce4c-4336-8c53-f6a1f7c50af1&expires_at=1521063563303&signature=MGQCMA1DRI6uBax3GSq93E8hp5b3P2Ebg0lIlPa8iGML9rs1B9WFmPeHH6ttvx_rmDG5AgIwY0pjIvEEpwOXM8o3h9Hst60DjRN9Mw7am7OmkdrBGfoI4IiHBflv0XpK87Tnb_BE"
}
This endpoint retrieves the preview for a specific media, this request only works on Media which is of the type VIDEO/IMAGE.
HTTP Request
GET https://adsapi.snapchat.com/v1/media/{media_id}/preview
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the media to retrieve, can only be of type VIDEO/IMAGE |
Get Thumbnail for a Specific Media
curl "https://adsapi.snapchat.com/v1/media/095a4a6d-01a0-4f6a-8901-41ea38c7a540/thumbnail" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b99772a00ff06928d3e31e94b0001737e616473617069736300016275696c642d33346634346232622d312d3230302d3200010154",
"expires_at": "2018-09-13T20:29:30.555Z",
"link": "https://adsapisc.appspot.com/media/video_thumbnail?media_id=095a4a6d-01b0-4f6c-8901-41ee38c7b540&expires_at=1536870570555&signature=MGQCMBQ_NfJM0yZCrdyLiEon4Lkbei0zFJF2HpLiHa2NvSLV2JyOVhLqHfQgqbDWUuzaCQIwHzPj_ZFtPNk688SoFiKWUIFEKKBMhSm8t4moy9xlfgnoSv-8LMQ1omM_P8QCj7O9"
}
This endpoint retrieves a thumbnail for media of the type VIDEO Thumbnails cannnot be fetched for other Media types (IMAGE, LENS_PACKAGE).
HTTP Request
GET https://adsapi.snapchat.com/v1/media/{media_id}/thumbnail
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the media (type VIDEO) to retrieve a thumbnail from |
Creatives
A Creative is the combination of one or more pieces of media. Creative is owned by an Ad Account and can be used by multiple Ads simultaneously.
See dedicated sections for examples on how to set up and launch FILTER and LENS creatives.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 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.
Creative Types and attachments
Creative Types
Name | Creative type | Description |
---|---|---|
Snap Ad | SNAP_AD | A Snap Ad comprised of a Top Snap only, latest Video/Image specs |
Snap Ad with attachment | APP_INSTALL, LONGFORM_VIDEO, WEB_VIEW, DEEP_LINK, AD_TO_LENS, AD_TO_CALL, AD_TO_MESSAGE | See below for list of all attachments |
Story Ad | COMPOSITE | Story Ad Creatives require a PREVIEW creative |
Collection Ad | COLLECTION | |
Lens | LENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_LONGFORM_VIDEO | See section on Lens creatives for specs and references |
Filter | FILTER | See section on Filter creatives for specs and references |
A basic Snap Ad is comprised of a top snap only. Snap Ads can be enhanced by using one of the following attachments:
Creative Type to Call To Actions Mapping
Creative type | Call To Actions |
---|---|
APP_INSTALL | BOOK_NOW, DONATE, DOWNLOAD, GET_NOW, INSTALL_NOW, ORDER_NOW, PLAY, SHOP_NOW, SIGN_UP, TRY, USE_APP, WATCH |
LENS_APP_INSTALL | BOOK_NOW, DONATE, DOWNLOAD, GET_NOW, INSTALL_NOW, ORDER_NOW, PLAY, SHOP_NOW, SIGN_UP, TRY, USE_APP, WATCH |
DEEP_LINK | DONATE, PLAY, SHOP_NOW, SIGN_UP, USE_APP, MORE, OPEN_APP, TRY, WATCH |
LENS_DEEP_LINK | DONATE, PLAY, SHOP_NOW, SIGN_UP, USE_APP, MORE, OPEN_APP, TRY, WATCH |
LONGFORM_VIDEO | DONATE, WATCH, WATCH_EPISODE |
LENS_LONGFORM_VIDEO | DONATE, WATCH, WATCH_EPISODE |
WEB_VIEW | APPLY_NOW, MORE, ORDER_NOW, PLAY, READ, SHOP_NOW, SHOW, SIGN_UP, VIEW, SHOW, WATCH, DONATE, DOWNLOAD, APPLY_NOW, ORDER_NOW, RESPOND, BUY_TICKETS, SHOWTIMES, BOOK_NOW, GET_NOW, LISTEN, TRY |
LENS_WEB_VIEW | APPLY_NOW, MORE, ORDER_NOW, PLAY, READ, SHOP_NOW, SHOW, SIGN_UP, VIEW, SHOW, WATCH, DONATE, DOWNLOAD, APPLY_NOW, ORDER_NOW, RESPOND, BUY_TICKETS, SHOWTIMES, BOOK_NOW, GET_NOW, LISTEN, TRY |
AD_TO_LENS | PLAY, TRY, SHOP_NOW |
AD_TO_MESSAGE | MESSAGE_NOW, OPEN_APP |
AD_TO_CALL | CALL_NOW, OPEN_APP |
AD_TO_PLACE | SEE_PLACE |
Attachments
Name | Creative type | Description |
---|---|---|
Long Form video attachment | LONGFORM_VIDEO | Creative requires longform_video_properties |
Web View attachment | WEB_VIEW | Creative requires web_view_properties |
App Install attachment | APP_INSTALL | Creative requires app_install_properties |
Deep Link attachment | DEEP_LINK | Creative requires deep_link_properties |
Lens attachment | AD_TO_LENS | Creative requires ad_to_lens_properties |
Call attachment | AD_TO_CALL | Creative requires ad_to_call_properties |
Text attachment | AD_TO_MESSAGE | Creative requires ad_to_message_properties |
Create a Snap Ad
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 25 characters max |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | SNAP_AD |
forced_view_eligibility | Indicates whether Creative can be used as a Commercial, see Commercials section for instructions on how to determine and set this value | O | FULL_DURATION, SIX_SECONDS, NONE |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837", "name": "Creative Creative", "type": "SNAP_AD", "brand_name": "Maxiumum Brand", "headline": "Healthy Living", "shareable": true}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0136f00ff085e3d63d358a20001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010108",
"creatives": [
{
"sub_request_status": "success",
"creative": {
"id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"updated_at": "2016-08-14T06:45:04.300Z",
"created_at": "2016-08-14T06:45:04.300Z",
"name": "Creative Creative",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "SNAP_AD",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE"
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap Ad with Long form Video attachment
The Long Form video attachment opens up a video on swipe up, this video should be a minimum of 15 seconds long and can be up to 1 GB in size.
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 | WATCH, WATCH_EPISODE |
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 | LONGFORM_VIDEO |
forced_view_eligibility | Indicates whether Creative can be used as a Commercial, see Commercials section for instructions on how to determine and set this value | O | FULL_DURATION, SIX_SECONDS, NONE |
Additional Attributes
The following attributes should be added to the basic creative under the property longform_video_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
video_media_id | Long form video media ID | R |
This endpoint creates a Creative within an Ad Account.
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"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap Ad with App Install attachment
App Install attachments allow users to swipe up and download the advertised app.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 25 characters max |
call_to_action | Call to Action | O | BOOK_NOW, DONATE, DOWNLOAD, GET_NOW, INSTALL_NOW, ORDER_NOW, PLAY, SHOP_NOW, SIGN_UP, TRY, USE_APP, WATCH |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | APP_INSTALL |
forced_view_eligibility | Indicates whether Creative can be used as a Commercial, see Commercials section for instructions on how to determine and set this value | O | FULL_DURATION, SIX_SECONDS, NONE |
Additional Attributes
The following attributes should be added to the basic creative under the property app_install_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
app_name | App name | R | |
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 |
Icon Media specifications
- Minimum 200 x 200 px, Maximum 2000 x 2000 px
- Must be PNG format
- The image should be square
- The image should not have any borders or padding
Mobile Measurement Partners - Setup Details
curl -X POST \
-d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837", "name": "Creative App Install", "type": "APP_INSTALL", "shareable": true, "call_to_action": "INSTALL_NOW", "app_install_properties": {"app_name": "Cool App Yo", "ios_app_id": "447188370", "android_app_url": "com.snapchat.android", "icon_media_id": "ab32d7e5-1f80-4e1a-a76b-3c543d2b28e4"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0163000ff05bee93989450c0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010107",
"creatives": [
{
"sub_request_status": "success",
"creative": {
"id": "1c7065c2-ad9f-41cc-b2c5-d48d9810439b",
"updated_at": "2016-08-14T06:56:48.631Z",
"created_at": "2016-08-14T06:56:48.631Z",
"name": "Creative App Install",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "APP_INSTALL",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "INSTALL_NOW",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"app_install_properties": {
"app_name": "Cool App Yo",
"ios_app_id": "447188370",
"android_app_url": "com.snapchat.android",
"icon_media_id": "ab32d7e5-1f80-4e1a-a76b-3c543d2b28e4"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap Ad with Web View attachment
Web View attachments allow users to swipe up to view a web page, you have the option of preloading the website as directed by the block_preload attribute
. You can see more details on preloading and recommendations for optimizations here.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 25 characters max |
call_to_action | Call to Action | O | APPLY_NOW, MORE, ORDER_NOW, PLAY, READ, SHOP_NOW, SHOW, SIGN_UP, VIEW, SHOW, WATCH, DONATE, DOWNLOAD, APPLY_NOW, ORDER_NOW, RESPOND, BUY_TICKETS, SHOWTIMES, BOOK_NOW, GET_NOW, LISTEN, TRY |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | WEB_VIEW |
forced_view_eligibility | Indicates whether Creative can be used as a Commercial, see Commercials section for instructions on how to determine and set this value | O | FULL_DURATION, SIX_SECONDS, NONE |
Additional Attributes
The following attributes should be added to the basic creative under the property web_view_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
url | Web view URL | R | |
allow_snap_javascript_sdk | Allow Snapchat Javascript SDK to autofill form fields, with this feature you can request Name, Phone Number and Email to be auto filled if the user agrees | O | true/false (default) |
block_preload | Block Snapchat from preloading the web page | O | true/false (default) |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837", "name": "Creative WV", "type": "WEB_VIEW", "shareable": true, "call_to_action": "VIEW", "web_view_properties": {"url": "http://snapchat.com/ads"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0168400ff06efecfdcdc8da0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010c",
"creatives": [
{
"sub_request_status": "success",
"creative": {
"id": "67e4296c-486b-4bf3-877b-f34e8eeb173c",
"updated_at": "2016-08-14T06:58:12.768Z",
"created_at": "2016-08-14T06:58:12.768Z",
"name": "Creative WV",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "WEB_VIEW",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "VIEW",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"web_view_properties": {
"url": "http://snapchat.com/ads"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap Ad with Deep Link attachment
The Deep Link attachment allows users who have the app installed to be directed to the location defined in the deep_link_properties
, users who do not have the app installed will be directed to the App store to install the app.
If you have a web view with deep links there is no need to specify the deep links in a separate field on the Creative. The deep links inside the web view will be auto detected.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 25 characters max |
call_to_action | Call to Action | O | DONATE, PLAY, SHOP_NOW, SIGN_UP, USE_APP, MORE, OPEN_APP, TRY, WATCH |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | DEEP_LINK |
Additional Attributes
The following attributes should be added to the basic creative under the property deep_link_properties.
Attribute | Description | Required |
---|---|---|
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 |
Icon Media specifications
- Minimum 200 x 200 px, Maximum 2000 x 2000 px
- Must be PNG format
- The image should be square
- The image should not have any borders or padding
curl -X POST \
-d '{"creatives": [{"name": "Deep Link test","ad_account_id": "{{ad_account_id}}","type": "DEEP_LINK","shareable": true,"headline": "some headline","brand_name": "some brand name","top_snap_media_id": "{{media_id}}","top_snap_crop_position": "MIDDLE","call_to_action": "{{cta}}","deep_link_properties": {"deep_link_uri":"spotify://somelink","ios_app_id": "1234","android_app_url": "com.snapchat.android","app_name": "not hotdog app","icon_media_id": "{{app_icon_media_id}}"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0168400ff06efecfdcdc8da0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010c",
"creatives": [
{
"sub_request_status": "success",
"creative": {
"id": "67e4296c-486b-4bf3-877b-f34e8eeb173c",
"updated_at": "2016-08-14T06:58:12.768Z",
"created_at": "2016-08-14T06:58:12.768Z",
"name": "Deep Link test",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "DEEP_LINK",
"packaging_status": "PENDING",
"review_status": "PENDING_REVIEW",
"shareable": true,
"call_to_action": "VIEW",
"top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"top_snap_crop_position": "MIDDLE",
"deep_link_properties": {
"deep_link_uri":"spotify://somelink",
"ios_app_id": "1234",
"android_app_url": "com.snapchat.android",
"app_name": "not hotdog app",
"icon_media_id": "{{app_icon_media_id}}"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap Ad with Lens attachment
The lens attachment will open up an AR Lens upon swipe up
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 25 characters max |
call_to_action | Call to Action | O | PLAY, TRY, SHOP_NOW |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | AD_TO_LENS |
forced_view_eligibility | Indicates whether Creative can be used as a Commercial, see Commercials section for instructions on how to determine and set this value | O | FULL_DURATION, SIX_SECONDS, NONE |
Additional Attributes
The following attributes should be added to the basic creative under the property ad_to_lens_properties.
Attribute | Description | Required |
---|---|---|
lens_media_id | The Media ID of the lens to be opened upon swipe up | R |
Lens Media file for a Lens Creative is not uploaded via the API, it’s instead created in Snapchat Lens Studio or Lens Web Builder and then transferred to the Ad Account in question via Lens Studio.
curl -X POST \
-d '{"creatives": [{"name":"Swipe to Lens","ad_account_id":"0b5176e0-9d5e-467c-8275-c1b619bd87d1","type":"AD_TO_LENS","shareable":true,"headline":"Headline Headline","brand_name":"Best Brand","call_to_action":"TRY","top_snap_media_id":"77f0c0a5-3374-4196-ac71-eb9fce49a5f3","top_snap_crop_position":"MIDDLE","ad_product":"SNAP_AD","ad_to_lens_properties":{"lens_media_id":"708ba95f-74e4-4e95-b443-21ccd2091a96"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b52250700ff0c3438c927b7db0001737e616473617069736300016275696c642d31393039356634322d312d3138352d310001011b",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "0df4bc92-00c8-4a6d-af89-533def1e5750",
"updated_at": "2018-07-20T14:32:09.102Z",
"created_at": "2018-07-20T14:29:44.160Z",
"name": "Swipe to lens",
"ad_account_id": "0b5176e0-9d5e-467c-8275-c1b619bd87d1",
"type": "AD_TO_LENS",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Headline Healine",
"brand_name": "Best Brand",
"call_to_action": "TRY",
"top_snap_media_id": "77f0c0a5-3374-4196-ac71-eb9fce49a5f3",
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"ad_to_lens_properties": {
"lens_media_id": "708ba95f-74e4-4e95-b443-21ccd2091a96"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Swipe to Call/Text - Phone number verification
All Phone Numbers used in Swipe to Call/Text Creatives need to be Verified via Snap Ads Manager as we use 2 factor authentication. You can do this by using Snap Ads Manager to set up a first Swipe to Call/Text Creative in your account, this set up will include adding a phone number and verifying it, see this guide for more details on how to verify your phone number.
After successful verification of the phone number you will be able to retrieve a phone number ID for the number in question.
curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/phone_numbers" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e6fb44400ff098283dd16a12e0001737e616473617069736300016275696c642d31636430373832652d312d3333342d300001010a",
"paging": {},
"phone_numbers": [
{
"sub_request_status": "SUCCESS",
"phone_number": {
"id": "d85758e1-4aac-435d-9660-de29e9b97548",
"updated_at": "2020-02-06T22:10:46.573Z",
"created_at": "2020-02-06T22:10:37.609Z",
"name": "Phone number - Pizza",
"country_code": "us",
"numerical_country_code": "1",
"phone_number": "1111333444",
"verification_status": "VERIFIED"
}
},
{
"sub_request_status": "SUCCESS",
"phone_number": {
"id": "dab10be9-6147-4ef4-9ad5-328f39777625",
"updated_at": "2020-02-06T22:07:40.452Z",
"created_at": "2020-02-06T22:07:26.553Z",
"name": "Phone number - Chicken",
"country_code": "us",
"numerical_country_code": "1",
"phone_number": "1111222333",
"verification_status": "VERIFIED"
}
}
]
}
This endpoint retrieves all verified phone numbers for an Ad Account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/phone_numbers
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap ad with Swipe to Call attachment
Call attachments allow users to swipe up to initiate a call.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 25 characters max |
call_to_action | Call to Action | O | CALL_NOW, OPEN_APP |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | AD_TO_CALL |
Additional Attributes
The following attributes should be added to the basic creative under the property ad_to_call_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
phone_number_id | ID of the phone number to be used | R |
curl -X POST \
-d '{"creatives": [{"ad_account_id": "497979f0-ed17-4971-8288-054883f1cbca","name" : "A new AD_TO_CALL Creative","type": "AD_TO_CALL","top_snap_media_id": "2fbaa906-d2d2-423d-b8e3-9535f1281998","ad_product": "SNAP_AD","headline": "Order your meal now","brand_name": "Honey Foods","call_to_action": "OPEN_APP","ad_to_call_properties": {"phone_number_id": "715b6ee0-357c-41d2-9246-feb09c199fc9"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e6fb51900ff040ef4db1db40b0001737e616473617069736300016275696c642d31636430373832652d312d3333342d300001010a",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "dbf052de-139c-4860-9f29-9dc4fa580620",
"updated_at": "2020-03-16T17:19:24.063Z",
"created_at": "2020-03-16T17:19:24.063Z",
"name": "A new AD_TO_CALL Creative",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2",
"type": "AD_TO_CALL",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Order your meal now",
"brand_name": "Honey Foods",
"call_to_action": "OPEN_APP",
"render_type": "STATIC",
"top_snap_media_id": "2fbaa906-d2d2-423d-b8e3-9535f1281998",
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"ad_to_call_properties": {
"phone_number_id": "715b6ee0-357c-41d2-9246-feb09c199fc9",
"message": null
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Snap Ad with Swipe to Text attachment
Text attachments allow users to swipe up to initiate a text message.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
brand_name | Brand Name | R | 25 characters max |
call_to_action | Call to Action | O | MESSAGE_NOW, OPEN_APP |
headline | Headline (displayed under brand name) | R | 34 characters max |
shareable | Allow Users to Share with Friends | O | true (default), false |
name | Creative name | R | |
top_snap_media_id | Top Snap Media ID | R | |
top_snap_crop_position | Top Snap Crop Position | O | OPTIMIZED (default), MIDDLE, TOP, BOTTOM |
type | Creative Type | R | AD_TO_MESSAGE |
Additional Attributes
The following attributes should be added to the basic creative under the property ad_to_message_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
phone_number_id | ID of the phone number to be used | R | |
message | A pre-populated message for the user to send, max 160 characters | O |
curl -X PUT \
-d '{"creatives":[{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2","name" : "A new AD_TO_MESSAGE Creative","type": "AD_TO_MESSAGE", "top_snap_media_id": "2fbaa906-d2d2-423d-b8e3-9535f1281998","ad_product": "SNAP_AD","headline": "Honey Dating","brand_name": "Dating for honey bears","call_to_action": "OPEN_APP","ad_to_message_properties": {"phone_number_id": "715b6ee0-357c-41d2-9246-feb09c199fc9","message": "Please send me details of Single Polar Bears"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e6fb51900ff040ef4db1db40b0001737e616473617069736300016275696c642d31636430373832652d312d3333342d300001010a",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "48c1a68d-782c-48af-8dba-ceef18d22a3c",
"updated_at": "2020-03-16T17:19:24.250Z",
"created_at": "2020-03-16T17:19:24.250Z",
"name": "A new AD_TO_MESSAGE Creative",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2",
"type": "AD_TO_MESSAGE",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Honey Dating",
"brand_name": "Dating for honey bears",
"call_to_action": "OPEN_APP",
"render_type": "STATIC",
"top_snap_media_id": "2fbaa906-d2d2-423d-b8e3-9535f1281998",
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"ad_to_message_properties": {
"phone_number_id": "715b6ee0-357c-41d2-9246-feb09c199fc9",
"message": "Send me details of Single Polar Bears"
}
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives
Parameters
Parameter | Default | Description |
---|---|---|
ad_account_id | Ad Account ID |
Create a Story Ad Creative
Story Ad Creatives are made up of two separate creatives, a Preview Creative and a Composite Creative.
The Preview Creative is used to display the thumbnail within the Discover tab of the app, the Composite Creative is used to define the individual Snap Ads that make up the story.
Create the Preview Creative
Additional Attributes
The following attributes should be added to the basic creative under the property preview_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
preview_media_id | Image that is the preview for Story Ads | R | |
logo_media_id | Logo shown on the tile for Story Ads | R | |
preview_headline | Preview Headline shown on the tile for Story Ads | R | 55 Character limit, emoji unicode characters allowed |
Preview Image Specifications - Resolution 3:5 - Minimum dimensions: 360 x 600 px - Maximum file size: 2MB - File Type: png
Logo Specifications - Dimensions: 993 x 284 px - Maximum file size: 2MB - File Type: png
curl -X POST \
-d '{"creatives": [{"ad_account_id": "0cf0aace-39d4-4502-8656-8f42daa473c7", "name": "Story Ad Preview", "type": "PREVIEW", "preview_properties": {"preview_media_id": "00a76e9f-186c-4ed4-87d7-d58a7dd06749", "logo_media_id": "6d54643b-e6e1-4c50-ab9a-a1f05965bf33", "preview_headline": "test preview headline"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/0cf0aace-39d4-4502-8656-8f42daa473c7/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5ae7ac0a00ff09a390a9b9b4d60001737e616473617069736300016275696c642d36393364326336352d312d3136322d3400010101",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "62537bbc-1a3a-4a40-b46f-43d181eac8ee",
"updated_at": "2018-04-30T23:51:40.466Z",
"created_at": "2018-04-30T23:51:40.466Z",
"name": "Story Ad Preview",
"ad_account_id": "0cf0aace-39d4-4502-8656-8f42daa473c7",
"type": "PREVIEW",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"top_snap_crop_position": "MIDDLE",
"preview_properties": {
"preview_media_id": "00a76e9f-186c-4ed4-87d7-d58a7dd06749",
"logo_media_id": "6d54643b-e6e1-4c50-ab9a-a1f05965bf33",
"preview_headline": "test preview headline"
}
}
}
]
}
Create the Composite Creative
Additional Attributes
The following attributes should be added to the basic creative under the property composite_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
creative_ids | List of creative ids that make up composite creative | R (For Story Ads) | Creative types SNAP_AD, APP_INSTALL, WEB_VIEW, 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
- The Creative types listed in creative_ids
attribute can be mixed as long as they are of the supported type listed above
- Creatives are shown to the user in the order listed at creation
- The order of the Creatives is immutable once created
- The shareable attribute on the composite overrides the shareable value of the individual creatives
curl -X POST \
-d '{"creatives": [{"ad_account_id": "0cf0aace-39d4-4502-8656-8f42daa473c7", "name": "First Composite Creative", "type": "COMPOSITE", "headline": "Test headline", "brand_name": "Test brand name",*", "shareable": true, "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 Lens Creative
Lens Creatives can run both in regular auction and in Reach and Frequency, for creation of Lens creatives see the Lens Section.
curl -X POST \
-d '{"creatives": [{"name":"Lens Creative","ad_account_id":"0b5176e0-9d5e-467c-8275-c1b619bd87d1","type":"LENS","shareable":true,"headline":"Headline Headline","brand_name":"Best Brand", "top_snap_media_id":"77f0c0a5-3374-4196-ac71-eb9fce49a5f3","ad_product":"LENS"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b52250700ff0c3438c927b7db0001737e616473617069736300016275696c642d31393039356634322d312d3138352d310001011b",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "0df4bc92-00c8-4a6d-af89-533def1e5750",
"updated_at": "2018-07-20T14:32:09.102Z",
"created_at": "2018-07-20T14:29:44.160Z",
"name": "Lens Creative",
"ad_account_id": "0b5176e0-9d5e-467c-8275-c1b619bd87d1",
"type": "LENS",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Headline Healine",
"brand_name": "Best Brand",
"top_snap_media_id": "77f0c0a5-3374-4196-ac71-eb9fce49a5f3",
"top_snap_crop_position": "MIDDLE",
"ad_product": "LENS"
}
}
]
}
Create a Lens Creative with Attachment
You can create a Lens Creative with any of the following attachments and the corresponding field then becomes required. The attachment unit will behave in the same way as it would in a Snap Ad. For measurement, you can also use the Snap Pixel with the attachment if it is a webview, make sure to associate the pixel_id at the Adsquad level. For attributes and examples, see the Lens Section.
Attachment For Lens | Creative Type | Required Field |
---|---|---|
WEB_VIEW | LENS_WEB_VIEW | web_view_properties |
APP_INSTALL | LENS_APP_INSTALL | app_install_properties |
LONGFORM_VIDEO | LONGFORM_VIDEO | longform_video_properties |
DEEP_LINK | LENS_DEEP_LINK | deep_link_properties |
Lens Creatives are also available for Reach and Frequency Campaigns.
curl -X POST \
-d '{"creatives": [{"name":"Lens Creative","ad_account_id":"0b5176e0-9d5e-467c-8275-c1b619bd87d1","type":"LENS_WEB_VIEW","shareable":true,"headline":"Headline Headline","brand_name":"Best Brand", "top_snap_media_id":"77f0c0a5-3374-4196-ac71-eb9fce49a5f3","ad_product":"LENS", "web_view_properties": {"url": "http://snapchat.com/ads"}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b52250700ff0c3438c927b7db0001737e616473617069736300016275696c642d31393039356634322d312d3138352d310001011b",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "0df4bc92-00c8-4a6d-af89-533def1e5750",
"updated_at": "2018-07-20T14:32:09.102Z",
"created_at": "2018-07-20T14:29:44.160Z",
"name": "Lens Creative",
"ad_account_id": "0b5176e0-9d5e-467c-8275-c1b619bd87d1",
"type": "LENS_WEB_VIEW",
"packaging_status": "SUCCESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Headline Healine",
"brand_name": "Best Brand",
"top_snap_media_id": "77f0c0a5-3374-4196-ac71-eb9fce49a5f3",
"top_snap_crop_position": "MIDDLE",
"ad_product": "LENS",
"web_view_properties": {
"url": "http://snapchat.com/ads"
}
}
}
]
}
Create a Collection Ad Creative
Additional Attributes
The following attributes should be added to the basic creative under the property collection_properties.
Attribute | Description | Required | Possible Values |
---|---|---|---|
interaction_zone_id | ID of the interaction zone to be used | R | |
default_fallback_interaction_type | The interation type when user swipes up on the full unit | R | WEB_VIEW, DEEP_LINK (must match the interaction type of the creative elements in the collection) |
web_view_properties | Web View properties | Required if default_fallback_interaction_type=WEB_VIEW | Same as web_view_properties for Web View Creative |
deep_link_properties | Deep Link properties | Required if default_fallback_interaction_type=DEEP_LINK | Same as deep_link_properties for Creative with deep links |
For Collection Ad creatives, call_to_action
must be set to null, and the headline
property of the interaction zone is used instead.
curl -X POST \
-d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74","name" : "Collection Ad creative","type": "COLLECTION","top_snap_media_id": "a871dcfd-3970-4917-a44a-b251220ce731","headline": "Collection Ad headline","brand_name": "My brand","collection_properties":{"interaction_zone_id":"a218dc8b-7a79-4da6-9a1c-e5a581c7bd44","default_fallback_interaction_type":"WEB_VIEW","web_view_properties":{"url":"https://snapchat.com"}}}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5bef549b00ff07105bd7e8604d0001737e616473617069736300016275696c642d61353965373533332d312d3232302d3100010144",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "e6ef3dea-0a5a-438e-928d-56726343d121",
"updated_at": "2018-11-16T23:37:01.555Z",
"created_at": "2018-11-16T23:37:01.555Z",
"name": "Collection Ad creative",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "COLLECTION",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": true,
"headline": "Collection Ad headline",
"brand_name": "My brand",
"top_snap_media_id": "a871dcfd-3970-4917-a44a-b251220ce731",
"top_snap_crop_position": "MIDDLE",
"ad_product": "SNAP_AD",
"collection_properties": {
"interaction_zone_id": "a218dc8b-7a79-4da6-9a1c-e5a581c7bd44",
"default_fallback_interaction_type": "WEB_VIEW",
"web_view_properties": {
"url": "https://snapchat.com",
"allow_snap_javascript_sdk": false,
"use_immersive_mode": false,
"deep_link_urls": [],
"block_preload": false
}
}
}
}
]
}
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 Creative.
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
curl "https://adsapi.snapchat.com/v1/creatives/c1e6e929-acec-466f-b023-852b8cacc54f/snapcode" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5aa15e8000ff03acde535d9a200001737e616473617069736300016275696c642d62633562363761342d312d3134372d3600013326",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc54f",
"expires_at": "2018-03-09T15:51:33.248Z",
"snapcode_link": "https://adsapisc.appspot.com/snapcodeimage/c1e6e929-acec-466f-b023-852b8cacc54f/352a899e-4a9d-3fdf-8efe-9bac9b8a0a21"
}
This endpoint generates a snapcode preview for a specific creative, the lifetime of the snapcode is 7 days. The attribute expires_at
defines the time that the snapcode will stop functioning.
HTTP Request
GET https://adsapi.snapchat.com/v1/creatives/<ID>/snapcode
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the creative to retrieve |
Commercials
Commercials are non-skippable video Snap Ads that allow you to drive awareness within Snap’s high-quality premium content.
A commercial is not a separate entity in the API, rather Creatives are eligible to be used as commercials given that they match a set of criteria including the length of the top snap video and the Creative type.
When this type of Creative is used in an Ad and targeted at Snap’s premium content bundles 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 a minimum of 3 seconds are eligible to be used in a Creative with the intent of running as a Commercial.
Media of the type
IMAGE are not eligible to be used as Commercials.
Media Attribute | Value |
---|---|
type | VIDEO |
duration_in_seconds | 3 second minimum |
Creative requirements
Only Snap Ads can run as Commercials, the only allowed attachments are Webview, 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 classified as SIX_SECONDS qualify to run as Commercials and will be unskippable for the first six seconds of the video, the rest of the video will be skippable.
Creatives of any other type than AD_TO_LENS, 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 |
7 seconds or longer | AD_TO_LENS, LONGFORM_VIDEO, SNAP_AD, WEB_VIEW | SIX_SECONDS | The first six seconds of the video will be unskippable |
any | APP_INSTALL, DEEP_LINK, PREVIEW, COMPOSITE, LENS, COLLECTION,LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK, 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 seconds or longer it can be used in a Creative intended to run as a Commercial.
In this case the duration_in_seconds is 5.25 seconds meaning this Media can be used to set up a Creative with the forced_view_eligibility
attribute set to FULL_DURATION
.
The above request returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5db307d500ff0113ad83cc14370001737e616473617069736300016275696c642d63396263633066392d312d3239392d3100010161",
"media": [
{
"sub_request_status": "SUCCESS",
"media": {
"id": "5f186aa6-51e4-4c86-95fc-f273e33247e1",
"updated_at": "2017-10-17T12:32:09.493Z",
"created_at": "2017-10-17T12:31:19.069Z",
"name": "6569282748022784.mp4",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
"type": "VIDEO",
"media_status": "READY",
"file_name": "6569282748022784.mp4",
"download_link": "https://storage.googleapis.com/rsp-ads-prod/22225ba6-7559-4000-9663-bace8adff5f2/6569282748022784.mp4",
"duration_in_seconds": 6.72,
"video_metadata": {
"width_px": 1080,
"height_px": 1920,
"rotation": null,
"integrated_loudness": -18.2,
"true_peak": -8.1
},
"file_size_in_bytes": 6061140,
"is_demo_media": false,
"hash": "3WQFkg=="
}
}
]
}
Create a Creative with the attribute forced_view_eligibility
curl -X POST \
-d '{
"creatives": [
{
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
"name" : "Honey Badger - Webview - Commercial - FULL_TIME",
"type": "WEB_VIEW",
"headline": "Honey Badger Motion Picture",
"brand_name": "Honey Badger Movies",
"shareable": false,
"forced_view_eligibility": "FULL_DURATION",
"call_to_action": "WATCH",
"top_snap_media_id": "5f186aa6-51e4-4c86-95fc-f273e33247e1",
"web_view_properties": {
"url": "http://snapchat.com/ads"
}
}
]
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/creatives
Having checked the type and duration_in_seconds
of the Media used in top_snap_media_id
we know we can set the attribute forced_view_eligibility
to the value FULL_DURATION, this will allow the Creative to be used as a Commercial which is unskippable for it’s full duration.
The above request returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5db309da00ff04a2bcf03681950001737e616473617069736300016275696c642d63396263633066392d312d3239392d3100010106",
"creatives": [
{
"sub_request_status": "SUCCESS",
"creative": {
"id": "2edef461-6998-4dd6-9afe-2ee2bf0d5b6c",
"updated_at": "2019-10-25T14:42:35.810Z",
"created_at": "2019-10-25T14:42:35.810Z",
"name": "Honey Badger - Webview - Commercial - FULL_TIME",
"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
"type": "WEB_VIEW",
"packaging_status": "IN_PROGRESS",
"review_status": "PENDING_REVIEW",
"shareable": false,
"forced_view_eligibility": "FULL_DURATION",
"headline": "Honey Badger Motion Picture",
"brand_name": "Honey Badger Movies",
"call_to_action": "WATCH",
"render_type": "STATIC",
"top_snap_media_id": "5f186aa6-51e4-4c86-95fc-f273e33247e4",
"top_snap_crop_position": "MIDDLE",
"web_view_properties": {
"url": "http://snapchat.com/ads",
"allow_snap_javascript_sdk": false,
"use_immersive_mode": false,
"deep_link_urls": [],
"block_preload": false
},
"ad_product": "SNAP_AD"
}
}
]
}
Creating an AdSquad that targets premium bundles
curl -X POST \
-d '{
"adsquads":[
{
"campaign_id":"44f535d7-fde6-4b72-b76d-2d8ccf03f591",
"name":"Ad Squad - Commercial test",
"type":"SNAP_ADS",
"placement":"SNAP_ADS",
"optimization_goal":"IMPRESSIONS",
"daily_budget_micro":1000000000,
"billing_event":"IMPRESSION",
"auto_bid":true,
"target_bid":false,
"targeting":{
"regulated_content":false,
"geos":[
{
"country_code":"uk"
}
]
},
"placement_v2":{
"config":"CUSTOM",
"platforms":[
"SNAPCHAT"
],
"snapchat_positions":[
"INSTREAM"
],
"inclusion":{
"premium_content_bundle_ids":[
"31b1a5e4-2193-4542-affe-9ce62b7b17b8"
]
}
},
"start_time":"2019-10-27T13:08:53.873Z",
"pixel_id":"5eda10b7-a5fe-4ac6-80f4-417e68d748fb",
"delivery_constraint":"DAILY_BUDGET",
"pacing_type":"STANDARD"
}
]
}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/campaigns/44f535d7-fde6-4b72-b76d-2d8ccf03f591/adsquads
In the placement_v2 we specify the bundle id 31b1a5e4-2193-4542-affe-9ce62b7b17b8 , this represents content made up of Lifestyle and Sports Shows (no News shows), the 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 |
---|---|---|---|
app_install_states | Defines whether targeted user has App installed or not | O | For usage see App Install states |
demographics | List of Demographic Targets | O | Required when using Multi-country targeting |
devices | List of Device Targets | O | |
geos | List of Geo/Location Targets | R | Multi-country targeting is allowed from 1st April 2020, each country needs to be placed in a geos entry, a targeting spec that uses multi-country targeting needs to also include a demographics entry that incorporates a single languages entry |
interests | List of Interest Targets | O | |
locations | List of Location categories/Circles | O | |
regulated_content | Flag to mark content within the Ad Squad as Regulated Content | O | FALSE (default), TRUE |
segments | List of 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 Inclusion / Exclusion
Category | Type | Support | Description |
---|---|---|---|
app_install_states | app installation state | See App Install states | Defines whether targeted user has App installed or not |
demographics | gender, languages, age_group, min_age, max_age, DLXD | INCLUDE | Gender, Language, Age Groups, Age Range, Advanced Demographics |
devices | connection_type, os_type, os_version, carrier, marketing_name | INCLUDE | Connection type, OS Type, OS Version, Carrier, Make |
geos | country | INCLUDE/EXCLUDE | Multi-country targeting is allowed from 1st April 2020, each country needs to be placed in a geos entry, a targeting spec that uses multi-country targeting needs to also include a demographics entry that incorporates a single languages entry |
geos | region | INCLUDE/EXCLUDE | Region/State |
geos | metro | INCLUDE/EXCLUDE | Metro/DMA |
geos | postal_code | INCLUDE/EXCLUDE | Zipcode/Post code |
interests | SLC | INCLUDE/EXCLUDE | Snap Lifestyle Categories |
interests | DLX, DLXS, DLXC, NLN | INCLUDE | Oracle Datalogix DLX/DLXS/DLXC Interest Targeting, Nielsen Interest Targeting |
locations | categories_loi, circles | INCLUDE | Location Categories, Location Point Radius |
segments | segment_id | INCLUDE/EXCLUDE | Snap Audience Match, Pixel Custom Audiences, Mobile Audiences, Engagement Audiences |
App Install states
App Install states targeting can be used with the Creative types APP_INSTALL and DEEP_LINK and allows you to target a user given the user’s install state for a specific App that you own. Using App Install state targeting comes with two prerequisites:
- A Snap App ID for the App needs to be set up in order to verify your app setting up your Snap App ID.
- The Ad Squad needs to have the
event_sources
attribute set up, the Snap App ID used inevent_sources
should match the Snap App ID used in theapp_install_states
App Install state targeting can be applied in two different scenarios:
- When using the Optimization Goal APP_REENGAGE_OPEN or APP_REENGAGE_PURCHASE, see targeting example
- When using Dynamic Product Ads and
product_audiences
, see below table and targeting example
App Install state / Optimization Goals
Ad type | Install state | Optimization goals | Description |
---|---|---|---|
APP_INSTALL | NOT_INSTALLED | IMPRESSIONS, SWIPES, APP_INSTALL, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGNUP | Targets users that don’t have the app installed |
DEEP_LINK | INSTALLED | IMPRESSIONS, SWIPES, APP_REENGAGE_OPEN, APP_REENGAGE_PURCHASE | Targets users that have the app installed |
DEEP_LINK | NOT_INSTALLED | IMPRESSIONS, SWIPES, APP_INSTALLS, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGN_UP | Targets users that don’t have the app installed |
DEEP_LINK | ALL | IMPRESSIONS, SWIPES | All users targeted |
App Install state / Product Audience
Ad type | Product Audience | Install state | Optimization goals |
---|---|---|---|
APP_INSTALL | Prospecting | NOT_INSTALLED | IMPRESSIONS, SWIPES, APP_INSTALL, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGNUP |
DEEP_LINK | Retargeting | INSTALLED | IMPRESSIONS, SWIPES, APP_REENGAGE_OPEN, APP_REENGAGE_PURCHASE |
DEEP_LINK | Prospecting | NOT_INSTALLED | IMPRESSIONS, SWIPES, APP_INSTALLS, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGN_UP |
DEEP_LINK | Prospecting | ALL | IMPRESSIONS, SWIPES |
Targeting Dimensions
All targeting dimensions will now have a deprecated boolean flag that will show whether the targeting dimension is deprecated. If a dimension has deprecated=true you will no longer be able to use it in the targeting_spec of an Ad Squad.
Targeting Type Support by Country
curl "https://adsapi.snapchat.com/v1/targeting/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 target ages using “min_age” and “max_age” attributes without using predefined age groups. Leaving out “max_age” from the targeting_spec will result in no age cap. Leaving out “min_age” will target 13 as the minimum age.
Attribute | Description | Possible values |
---|---|---|
min_age | 35+ is deprecated but may be found in existing ad squads | 35+ |
min_age | integer, defines the minimum age targeted | 13 - 35 |
max_age | integer, defines the maximum age targeted. If you want no maximum cap, do not set a max_age | 13 - 49 |
See the Targeting Spec Examples for usage examples.
Demographics - Gender
Get Gender Targeting Options
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, phone number 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
Identifiers should be grouped in batches of a maximum of 100,000 identifiers/request.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
id | Segment ID | R | |
schema | List of one type of Schema | R | EMAIL_SHA256, MOBILE_AD_ID_SHA256, PHONE_SHA256 |
data | List of hashed identifiers | R | max 100,000 identifiers/request |
HTTP Request
POST https://adsapi.snapchat.com/v1/segments/{segment_id}/users
Parameters
Parameter | Default | Description |
---|---|---|
segment_id | Segment ID |
Normalizing & Hashing
Each raw identifier (plain text email or mobile identifier) must be normalized before being hashed.
Normalizing Identifiers
- Normalize email addresses by trimming leading and trailing whitespace and converting all characters to lowercase before hashing
- Normalize mobile advertiser id by using all lowercase. Do not remove hyphens.
- Normalize phone numbers by including the country code, remove any double 0 in front of the country code, if the number itself begins with a 0 this should be removed. Also exclude any non-numeric characters such as whitespace, parentheses, ‘+’, or ‘-’.
Phone normalization example | Before normalization | After normalization | Action |
---|---|---|---|
US phone number example | 001-234-567-8910 | 12345678910 | 00 of country code and ‘-’ characters removed |
UK phone number example | +44 844 412 4653 | 448444124653 | Initial 0 of number, whitespaces and ‘+’ character removed |
Hashing Identifiers
Hash raw identifiers with lowercase hex SHA256 format.
Adding Users (Single-Key)
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, phone number or mobile identifier. You can send a maximum of 100,000 identifiers / request.
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.
Identifiers should be grouped in batches of a maximum of 100,000 identifiers/request.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
id | Segment ID | R | |
schema | List of one type of Schema | R | EMAIL_SHA256, MOBILE_AD_ID_SHA256, PHONE_SHA256 |
data | List of hashed identifiers | R | max 100,000 identifiers/request |
HTTP Request
DELETE https://adsapi.snapchat.com/v1/segments/{segment_id}/users
Parameters
Parameter | Default | Description |
---|---|---|
segment_id | Segment ID |
Removing Users (Single-Key)
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.
If the original seed Segment has new identfiers added to it, the Lookalike segment will also be updated with new users.
Attributes
Attribute | Description | Required | Possible Values |
---|---|---|---|
ad_account_id | Ad Account ID | R | |
creation_spec | Lookalike Creation Spec dictionary | R | (see below) |
description | Audience Segment Description | O | |
name | Audience Segment name | R | |
retention_in_days | # of days to retain audience members | R | (Max 180) |
source_type | Data source type | R | LOOKALIKE |
Creation Spec Details
Attribute | Description | Required | Possible Values |
---|---|---|---|
seed_segment_id | Seed Audience Segment ID | R | |
type | The type of Lookalike to be created | O | BALANCE (default), SIMILARITY, REACH |
countries | List of ISO-2 Country Code | R | [“UK”, “US”] OR [“US”] etc |
country [Deprecated] | ISO-2 Country Code | R |
Create an Lookalike Segment
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"
}
]
}
Example 19
Snap Lifestyle Category inclusion of SLC_1, SLC_124 and exclusion of SLC_2
{
"interests": [
{
"category_id": [
"SLC_1",
"SLC_124"
],
"operation": "INCLUDE"
},
{
"category_id": [
"SLC_2"
],
"operation": "EXCLUDE"
}
]
}
Example 20
App Install State targeting using a Snap App ID
{
"app_install_states": [
{
"state": "INSTALLED",
"snap_app_ids": [
"85a0bfd4-2f0c-4797-bceb-b0a8375c5828"
]
}
]
}
App Install State targeting is required for Ad Squads that use the optimization goal APP_REENGAGE_OPEN or APP_REENGAGE_PURCHASE.
Example 21
App Install State targeting - Prospecting Product Audience
App Install State targeting in use with Dynamic Product Ads of the type APP_INSTALL
{
"product_audiences": [
{
"product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
"event_type": "PAGE_VIEW",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
},
{
"product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
"event_type": "ADD_CART",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
},
{
"product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
"event_type": "PURCHASE",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
},
{
"product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
"event_type": "VIEW_CONTENT",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
}
],
"app_install_states": [
{
"state": "NOT_INSTALLED",
"snap_app_ids": [
"2e1154ae-35fc-4b9e-8c40-4816dfb42038"
]
}
]
}
Example 22
App Install State targeting - Retargeting Product Audience
App Install State targeting in use with Dynamic Product Ads of the type DEEP_LINK
{
"product_audiences": [
{
"product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
"event_type": "PAGE_VIEW",
"retention_seconds": 1209600,
"operation": "INCLUDE"
},
{
"product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
"event_type": "ADD_CART",
"retention_seconds": 1209600,
"operation": "INCLUDE"
},
{
"product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
"event_type": "VIEW_CONTENT",
"retention_seconds": 1209600,
"operation": "INCLUDE"
},
{
"product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
"event_type": "PURCHASE",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
}
],
"app_install_states": [
{
"state": "INSTALLED",
"snap_app_ids": [
"85a0bfd4-2f0c-4797-bceb-b0a8375c5828"
]
}
]
}
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/{ad_account_id}/audience_size_v2
URL Parameters
Parameter | Description |
---|---|
ad_account_id | Ad Account ID |
By Ad Squad ID
curl -X GET
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/c7b98952-4c6e-4f95-8cd1-cf0f17a77988/audience_size_v2
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "58474ee700ff017f0381aeb1a90001737e616473617069736300016275696c642d32356261313161372d312d32372d3100010120",
"audience_size": {
"ad_squad_id": "c7b98952-4c6e-4f95-8cd1-cf0f17a77988",
"audience_size_minimum": 16450000,
"audience_size_maximum": 19925000
}
}
This endpoint retrieves the estimated audience size for a specific ad squad.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/audience_size_v2
URL Parameters
Parameter | Description |
---|---|
ad_squad_id | Ad squad ID |
By Targeting Spec
curl -X POST \
-H "Content-Type: application/json" \
-d '{"geos":[{"country_code": "us"}], "demographics": [{"age_groups": ["21-24"]}]}' \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/d8c1e7e9-f119-4ed3-b77e-33b7eae13411/audience_size
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5848847200ff049b9c18549b500001737e616473617069736300016275696c642d39323764616530622d312d32372d3300010124",
"audience_size": {
"audience_size_minimum": 12400000,
"audience_size_maximum": 15025000
}
}
This endpoint retrieves the estimated audience size for a specific targeting spec, whether or not the targeting is in use by an ad squad.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/<ID>/audience_size
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the ad account |
Bid Estimate
The Bid Estimate API returns a bid estimate min and max for a given Ad Squad or Targeting Spec.
By Ad Squad
curl -X GET
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/c5995202-bfbc-45a0-9702-dd6841af52fe/bid_estimate
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57affee300ff0d91229fabb9710001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010110",
"bid_estimate": {
"ad_squad_id":"c5995202-bfbc-45a0-9702-dd6841af52fe",
"optimization_goal": "IMPRESSIONS",
"bid_estimate_minimum":8000000,
"bid_estimate_maximum":9000000
}
}
This endpoint retrieves the bid estimate for a specific ad squad.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/<ID>/bid_estimate
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the ad squad |
By Targeting Spec
curl -X POST \
-H 'Content-Type: application/json' \
-d '{"optimization_goal": "IMPRESSIONS", "targeting": {"geos": [{"country_code": "us"}],"demographics": [{"age_groups": ["21-24"],"gender": "MALE"}]}}' \
-H 'Authorization: Bearer meowmewmeow' \
https://adsapi.snapchat.com/v1/adaccounts/8abc3db7-8148-4fbf-999c-8d2266369d75/bid_estimate
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57affee300ff0d91229fabb9710001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010110",
"bid_estimate": {
"optimization_goal": "IMPRESSIONS",
"bid_estimate_minimum":8000000,
"bid_estimate_maximum":9000000
}
}
This endpoint retrieves the bid estimate for a specific targeting spec, whether or not the targeting is in use by an ad squad.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/<ID>/bid_estimate
URL Parameters
Parameter | Description |
---|---|
ID | The ID of the ad account |
Attributes
Attribute | Description | Required | Note |
---|---|---|---|
optimization_goal | Optimization Goal | R | Available for all valid optimization goals |
targeting | A valid Targeting Spec | R |
Delivery Status
The delivery status provides details of an entity’s status given delivery within the Snap ad platform.
Attributes
Entity | Status | Description |
---|---|---|
Common | PENDING | Default |
VALID | Entity is valid for delivery | |
INVALID_NOT_ACTIVE | Entity status isn’t active | |
INVALID_NOT_EFFECTIVE_ACTIVE | Entity has a valid state and is active, but a parent entity has something wrong with it and is preventing this entity becoming active | |
INVALID_START_TIME | Start time is after the present time | |
INVALID_END_TIME | End time is before the present time | |
INVALID_EFFECTIVE_START_TIME | Effective start time is after the present time | |
INVALID_EFFECTIVE_END_TIME | Effective end time is before now | |
Ad Account | TEST_AD_ACCOUNT | Ad account is test account |
INVALID_REMAINING_AD_ACCOUNT_BUDGET | Remaining ad account budget is less or equal to 0 | |
INVALID_AD_ACCOUNT_LIFETIME_SPEND_CAP | Ad account has invalid lifetime spend cap | |
INVALID_OVER_BUDGET_AD_ACCOUNT_FINALIZED_LIFETIME_SPEND | Ad account finalized lifetime spend exceeds lifetime spend cap | |
INVALID_OVER_BUDGET_AD_ACCOUNT_REALTIME_LIFETIME_SPEND | Ad account realtime lifetime spend exceeds lifetime spend cap | |
Campaign | INVALID_CAMPAIGN_LIFETIME_SPEND_CAP | Campaign has invalid lifetime spend cap |
INVALID_OVER_BUDGET_CAMPAIGN_FINALIZED_LIFETIME_SPEND | Campaign finalized lifetime spend exceeds lifetime spend cap | |
INVALID_OVER_BUDGET_CAMPAIGN_REALTIME_LIFETIME_SPEND | Campaign realtime lifetime spend exceeds lifetime spend cap | |
INVALID_OVER_BUDGET_CAMPAIGN_DAILY_SPEND | Campaign daily spend exceeds daily spend cap | |
NO_VALID_AD_SQUAD | Campaign has no valid ad squad | |
INVALID_RF_FOR_RESERVED_BUY | Reach frequency is invalid for reserved buy | |
INVALID_UNKNOWN_FORECAST_ERROR | Unknown error from forecast | |
Ad Squad | INVALID_TARGETING_REACH_STATUS | AdSquad targeting reach status is invalid |
INVALID_PENDING_TARGETING_REACH_STATUS | AdSquad targeting reach status is pending | |
INVALID_AD_SQUAD_HAS_NO_ACTIVE_ADS | AdSquad doesn’t have any active ad | |
INVALID_AD_SQUAD_WIREOBJECT | Failed to convert ad squad entity to wire object | |
INVALID_INTERNAL_PLACEMENT | AdSquad has invalid internal placement v2 and non-empty ads | |
INVALID_AD_SQUAD_HAS_UNSUPPORTED_AD_TYPE | AdSquad has unsupported ad type | |
INVALID_UNSUPPORTED_AD_SQUAD_TYPE | AdSquad has an unsupported type | |
INVALID_AD_SQUAD_LIFETIME_SPEND_CAP | Ad squad has invalid lifetime spend cap | |
INVALID_OVER_BUDGET_AD_SQUAD_FINALIZED_LIFETIME_SPEND | Ad squad finalized lifetime spend exceeds lifetime spend cap | |
INVALID_OVER_BUDGET_AD_SQUAD_REALTIME_LIFETIME_SPEND | Ad squad realtime lifetime spend exceeds lifetime spend cap | |
INVALID_AD_SQUAD_DAILY_SPEND_CAP | Ad squad has invalid daily spend cap | |
INVALID_OVER_BUDGET_AD_SQUAD_DAILY_SPEND | Ad squad daily spend exceeds daily spend cap | |
Ad | NOT_APPROVED_AD | Ad has non-approved review status |
INVALID_NOT_APPROVED_REVIEW_STATUS | The Ad has failed Ad review | |
INVALID_PENDING_REVIEW_STATUS | Ad review is still pending | |
INVALID_DYNAMIC_CONTENT_MARKUP | Creative has invalid dynamic content markup | |
INVALID_UNSUPPORTED_AD_TYPE | Ad type isn’t supported |
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 |
action_report_time | Specifies the time f conversion reporting | O | conversion (default), impression** |
swipe_up_attribution_window | Attribution window for swipe ups | O | 1_DAY, 7_DAY, 28_DAY (default) |
view_attribution_window | Attribution window for views | O | 1_HOUR, 3_HOUR, 6_HOUR, 1_DAY (default), 7_DAY, 28_DAY |
position_stats | Position metric breakdown for Snap Ads within a Story Ad | O | true |
omit_empty | Omits records with zero data for all metrics for a given date/entity. If there is data for any metric for a given date/entity, all metrics for that date/entity are returned | O | false (default), true |
conversion_source_types | Conversion source breakout by platform | O | web, app, offline**, total |
platform_stats | Breaks down metrics by Snapchat Client/Audience network | O | true, false |
limit | The limit parameter specifies how many entities should be returned per page | O | integer, max 200 |
** offline conversion data source ( conversion_source_types=offline ) and impression based conversions ( action_report_time=impression ) are available from 1 May 2020 onwards.
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 Reporting
The action_report_time parameter specifies the timing to use when requesting conversion reporting. Passing the value conversion will return conversions based on the time the user triggered the conversion event, passing the value impression will return conversions based on the time the ad impression took place.
Reporting for conversions based on ad impression (action_report_time=impression), are available from 1st May 2020 onwards.
Conversion Event Stats
The following conversion event metrics are available for ads that have been setup to track conversions through Snap Pixel.
Fields | Granularity | Description |
---|---|---|
conversion_purchases | Any | # of attributed “PURCHASE” conversion events |
conversion_purchases_value | Any | Value of attributed “PURCHASE” conversion events (microcurrency in Ad Account’s currency) |
conversion_save | Any | # of attributed “SAVE” conversion events |
conversion_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 |
conversion_visit | Any | # of attributed “VISIT” 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 a breakout of conversions based on where the conversions occurred.
Parameter | Description |
---|---|
total | All conversion events |
web | Events reported via the Snap Pixel SDK |
app | Events reported within an App |
offline | Events reported from an offline source (in-store) |
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":