Introduction
Welcome to the Snapchat Marketing API!
We have code samples in Curl and Python (coming soon)! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.
Upcoming Breaking Changes
April 2020
curl "https://adsapi.snapchat.com/v1/adsquads/079abe5b-8aa3-4009-9932-66e0b0a2c75c?return_placement_v2=true" \
-H "Authorization: Bearer meowmeowmeow"
Example, this Ad Squad using multi-country targeting is targeting the US and Canada:
{
"request_status": "SUCCESS",
"request_id": "5e821b1100ff00ff5566930ea67e0001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d61643137333166302d312d3333382d3000010145",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "079abe5b-8aa3-4009-9932-66e0b0a2c75c",
"updated_at": "2020-03-10T20:34:09.826Z",
"created_at": "2020-03-10T20:33:58.614Z",
"name": "Multi country Ad Squad Example",
"status": "ACTIVE",
"campaign_id": "f5b84e48-dc8b-4ddb-bf9b-edf07fadd6c6",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": false,
"demographics": [
{
"languages": [
"en"
]
}
],
"geos": [
{
"country_code": "us",
"operation": "INCLUDE"
},
{
"country_code": "ca",
"operation": "INCLUDE"
}
],
"enable_targeting_expansion": true
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 1000000,
"auto_bid": false,
"target_bid": true,
"bid_strategy": "TARGET_COST",
"daily_budget_micro": 50000000,
"start_time": "2019-12-17T01:38:19.961Z",
"optimization_goal": "APP_INSTALLS",
"conversion_window": "SWIPE_28DAY_VIEW_1DAY",
"delivery_constraint": "DAILY_BUDGET"
}
}
]
}
Multi-country targeting
Multi-country targeting is available through the API starting April 1st! This will enable advertisers to set up Ad Squads targeting any combination of countries across the world.
Multi-country targeting will help extend reach and optimize ads globally to the best audience. While setting up multi-country Ad 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
dimensionandpivotsas described in the following section will be deprecated. - The new parameter
report_dimensionoffers the same functionality with the added benefit of supporting DAY, TOTAL and LIFETIME granularity. - Delivery Insights via
report_dimensionare only available from January 1st, 2020. - After the deprecation you will still be able to use
dimensionandpivotsto 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_strategyattribute replaces the attributesauto_bidandtarget_bid bid_strategyis an enumeration that holds the bid method for the Ad Squad- Apps should be adjusted to use only
bid_strategyon Creation and Update requests, the attributesauto_bid/target_bidshould not be sent in requests - During the 90 day transition period
bid_strategywill co-exist withauto_bidandtarget_bid - See section on bid_strategy
Deprecation of placement in favour of placement_v2
Deprecation Schedule
Announcement Date: March 20th, 2020
Sunset Date: June 20th, 2020
- All Ad Squads are required to use
placement_v2 - The attributes at
included_content_typesandexcluded_content_typesat AdSquad level will be deprecated in favour of the attributesinclusionandexclusiondefined inplacement_v2 - During the 90 day transition period
placementwill co-exist withplacement_v2 - See section on placement_v2 for full information on how to implement
Overview
The highest level object is an Organization. Each Organization is tied to a specific Brand, Advertiser, or Partner. An Organization has an over-arching line of credit established with Snap Inc.
An Organization owns:
- One or more Funding Sources. A Funding Source references the Organization’s line of credit or a portion thereof.
- One or more Ad Accounts. An Ad Account references one or more Funding Sources.
Ad Accounts are the primary vehicle for organizing all relevant advertising objects. An Ad Account owns:
- One or more ad Campaigns (and all of its children).
- One or more Media objects. Media are the most atomic objects - a single video file is a Media object.
- One or more Creative objects. A Creative references at least one Media object along with metadata regarding how the creative should be presented to the user.
- Zero or more Audience Segments. An Audience Segment is a targetable list of user identifers using the advertiser’s first-party data.
An Organization (Org A) can grant another Organization (Org B) permission to access one or more of their Ad Accounts. A common case is a Brand granting a Snapchat MPP permission to advertise on their behalf using the Brand’s line of credit.
Quick Start
Here’s a high-level look at what it takes to launch a Snap Ad.
Let’s Run a Snap Ad!
- Snap Inc. creates your Organization, Funding Source, and Ad Account.
- Create a Media object.
- Upload the video file to the Media object.
- Create a Creative using the Media object ID.
- Create a Campaign.
- Create an Ad Squad. Set the bid, objective, and targeting at this stage.
- Create an Ad referencing the Creative object ID.
- Fin!
API Patterns
The API has a consistent pattern for requests.
Get Many Entities
Pattern:
GET /v1/{PLURAL_PARENT_ENTITY_NAME}/{PARENT_ENTITY_ID}/{PLURAL_ENTITY_NAME}
Example:
GET /v1/adaccounts/ff869d1f-0923-4d28-8577-4c36291f0fca/campaigns
Get a Single Entity
Pattern:
GET /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}
Example:
GET /v1/adaccounts/ff869d1f-0923-4d28-8577-4c36291f0fca
Pagination
curl "https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/ads?limit=50" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b3f92d000ff0943024587937a0001737e616473617069736300016275696c642d33346664346130642d312d3138322d320001010d",
"paging": {
"next_link": "https://adsapisc.appspot.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/ads?cursor=CnEKFgoJY3JlYXRlZEF0EgkIoLnp8JLP0QISU2oKc35hZHNhcGlzY3ItCxIDQWRzIiQzMmFkZmYzMC1iNDk0LTQ4NWQtODMwYi04MjZlNDAzZTVkNjgMogEVYWQtbWFuYWdlci1wcm9kdWN0aW9uGAAgAQ&limit=50"
},
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "8ade8ef7-0cde-4eaa-bde6-990133575229",
"updated_at": "2018-04-04T00:59:02.774Z",
"created_at": "2018-04-04T00:56:35.051Z",
"created_by_app_id": "87947032-5fbd-46a7-ba60-073ca8efefbb",
"created_by_user": "1dcd753d-aca4-4f2d-8818-1edd38053a36",
"last_updated_by_app_id": "87947032-5fbd-46a7-ba60-073ca8efefbb",
"last_updated_by_user": "1dcd753d-aca4-4f2d-8818-1edd38053a36",
"name": "Test",
"ad_squad_id": "4c8e53c2-1747-4b50-a8a8-8200fe75aac5",
"creative_id": "6ad4e432-f679-4a9b-af1d-c5781212dd75",
"status": "ACTIVE",
"type": "SNAP_AD",
"review_status": "APPROVED"
}...
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "32adff30-b494-485d-830b-826e403e5d68",
"updated_at": "2017-07-31T21:34:50.311Z",
"created_at": "2017-01-19T21:26:02.020Z",
"created_by_app_id": "4bc57a9c-c2ab-4a12-ba71-adda3c0189f9",
"last_updated_by_app_id": "4bc57a9c-c2ab-4a12-ba71-adda3c0189f9",
"name": "happy time in 910 2",
"ad_squad_id": "33a7ea1e-6413-4bb7-a4ac-35b0a258681e",
"creative_id": "9e37d1ee-5f27-45ff-8317-ab35a57a5bf4",
"status": "PAUSED",
"type": "SNAP_AD",
"review_status": "APPROVED"
}
}
]
}
For calls that fetch many entities we recommend that you use pagination. The limit parameter specifies how many entities should be returned per page.
The returned result will contain a paging attribute, this in turn holds a next_link attribute which holds the API call to fetch the next page. Paginated calls are ordered by the attribute CreatedAt, non-paginated calls are unsorted.
Paginated calls are supported for these requests;
- Get all Ads under an Ad Account
- Get all Ad Squads under an Ad Account
- Get all Creatives under an Ad Account
- Get all Media under an Ad Account
- Get all Campaigns under an Ad Account
- Get all Ad Accounts under an Organization
- Get all Audience Segments under an Ad Account
- Get Zipcode targeting options
- Get change logs request
| Parameter | Required | Description |
|---|---|---|
| limit | O | integer, min 50, max 1000 |
Pattern:
GET /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}?limit={value between 50 - 1000}
Example:
GET /v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/ads?limit=50
Entity Request Limits
Whilst the Create and Update endpoints support the creation/editing of several objects in a single POST request there is a limit to the number of entities that can be created/edited in a single request.
| Entity type | Create/Update limit per Request |
|---|---|
| Creative | 10 |
| Media | 10 |
| Organization | 15 |
| Ad Account | 15 |
| Segments | 15 |
| Campaign | 30 |
| Ad Squad | 30 |
| Ad | 30 |
Create One or More Entities
The Create endpoints support bulk creation, meaning you can create several objects at the same time as long as they share the same parent. For example, you can create muliple Campaigns within a single Ad Account in a single POST request.
Pattern:
POST /v1/{PLURAL_PARENT_ENTITY_NAME}/{PARENT_ENTITY_ID}/{PLURAL_ENTITY_NAME}
Example:
POST /v1/adaccounts/ff869d1f-0923-4d28-8577-4c36291f0fca/campaigns
Update One or More Entities
The Update endpoints support bulk update, meaning you can update several objects at the same time as long as they share the same parent. For example, you can update muliple Campaigns within a single Ad Account in a single PUT request.
Pattern:
PUT /v1/{PLURAL_PARENT_ENTITY_NAME}/{PARENT_ENTITY_ID}/{PLURAL_ENTITY_NAME}
Example:
PUT /v1/adaccounts/ff869d1f-0923-4d28-8577-4c36291f0fca/campaigns
Delete a Single Entity
Pattern:
DELETE /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}
Example:
DELETE /v1/campaigns/0be21d8a-2720-4668-9576-0fa566a6ff55
Monetary Values
All Monetary Values are presented in micro-currency, wherein 1.00 in the Ad Account’s currency (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
meowmeowmeowwith your access token.
Snapchat Marketing API uses access tokens to control access and authenticate requests.
The access token should be included in all API requests to the server in the Authorization header like so:
Authorization: Bearer meowmeowmeow
Obtain App Credentials
OAuth apps are set up in the ‘Business Details’ section in Snap Business Manager, you need to be an Organization Admin to see the app dashboard, when setting up an app you need to agree to the Snap Marketing API terms and the Snap Audience Match Terms.
When setting up an OAuth app you need to provide a name and a redirect_uri, the redirect_uri is where the user is redirected upon authentication.
Depending on your objectives you may want the redirect_uri to simply display the code value so that you can copy it and use it in an app built elsewhere to generate tokens, or you may choose to build the entry point for your entire app on the redirect_uri so that it may read the code value automatically upon user authentication.
Upon creation of an app you will be presented with client_id and client_secret, the secret is only ever displayed at the point of creation so you will need to keep track of this.
User Auth via Redirect
Direct the user’s browser to the Authorization URL. They will be presented with a login screen and confirmation prompt to grant access to their account.
GET https://accounts.snapchat.com/login/oauth2/authorize
Parameters
| Parameter | Default | Description |
|---|---|---|
| client_id | Client ID | |
| redirect_uri | URLEncoded Redirect URI (must match URI on OAuth App) | |
| response_type | Must be “code” | |
| scope | Must be “snapchat-marketing-api” | |
| state | Optional; Will be passed through in redirect; Used for verification of request authenticity |
Receive the Redirected User
After the user approves or cancels the authorization, they will be redirected to your Redirect URI. If the user approved the request to access their account, there will be 2 query parameters passed along to your Redirect URI.
Parameters
| Parameter | Default | Description |
|---|---|---|
| code | One-time use code that can be exchanged for an Access Token and a Refresh Token | |
| state | Optional; Used for verification of request authenticity |
Generate an Access Token
In order to access the API you must have an Access Token. To generate an Access Token you must first receive a Code from a successful user OAuth Web Redirect Flow described above. Once you have the Code you can exchange it for a short-lived Access Token and long-lived Refresh Token.
# With shell, you can just pass the correct header with each request
curl -X POST \
-d "grant_type=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 generate response.
When a request is attempted with an expired token, the response will be a 401 Not Authorized with additional headers.
< HTTP/1.1 401 Unauthorized
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Headers: Content-Type, Authorization
< WWW-Authenticate: Bearer error="invalid_token", error_description="The access token expired"
< X-Cloud-Trace-Context: e0fdbe35c49ad238e624635b6a45813d;o=1
< Date: Mon, 15 Aug 2016 21:10:01 GMT
< Content-Type: text/html
< Server: Google Frontend
< Content-Length: 0
User
Get Authenicated User
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.users.me()
curl "https://adsapi.snapchat.com/v1/me"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"me": {
"id": "2f5dd7e6-fcd1-4324-8455-1ea4d96caaaa",
"updated_at": "2016-08-12T01:56:39.841Z",
"created_at": "2016-08-12T01:56:39.842Z",
"email": "honey.badger@hooli.com",
"organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"display_name": "Honey Badger"
},
"request_id": "57ae093a00ff00ff43b8c63fda390001737e616473617069736300016275696c642d34363138393265642d312d31312d32000100"
}
This endpoint retrieves the authenticated user.
HTTP Request
GET https://adsapi.snapchat.com/v1/me
Organizations
Represents a partner, ad agency or a brand. Creation requires approval from Snap Inc.
Attributes
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| name | Organization name | R |
Create an Organization
The Partner Management team creates all Organizations on behalf of partners and advertisers. Please use this form to request an organization.
Get All Organizations
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.organizations.get()
curl "https://adsapi.snapchat.com/v1/me/organizations" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57affee300ff0d91229fabb9710001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010110",
"organizations": [
{
"sub_request_status": "success",
"organization": {
"id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"updated_at": "2017-05-26T15:14:44.877Z",
"created_at": "2017-05-26T15:14:44.877Z",
"name": "My Organization",
"address_line_1": "101 Stewart St",
"locality": "Seattle",
"administrative_district_level_1": "WA",
"country": "US",
"postal_code": "98134",
"type": "ENTERPRISE"
}
},
{
"sub_request_status": "success",
"organization": {
"id": "507d7a57-94de-4239-8a74-e93c00ca53e6",
"updated_at": "2016-08-01T15:14:44.877Z",
"created_at": "2017-08-01T15:14:44.877Z",
"name": "Hooli",
"address_line_1": "1100 Silicon Vallety Rd",
"locality": "San Francisco",
"administrative_district_level_1": "CA",
"country": "US",
"postal_code": "94110",
"type": "ENTERPRISE"
}
}
]
}
This endpoint retrieves all organizations.
HTTP Request
GET https://adsapi.snapchat.com/v1/me/organizations
Get All Organizations with Ad Accounts
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.organizations.get()
curl "https://adsapi.snapchat.com/v1/me/organizations?with_ad_accounts=true" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b985a7300ff0b4b064df945b80001737e616473617069736300016275696c642d33346634346232622d312d3230302d320001011f",
"organizations": [
{
"sub_request_status": "SUCCESS",
"organization": {
"id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"updated_at": "2018-09-04T16:27:01.066Z",
"created_at": "2016-08-09T17:12:49.707Z",
"name": "Hooli Inc",
"country": "US",
"postal_code": "90291",
"locality": "Venice",
"contact_name": "",
"contact_email": "",
"contact_phone": "",
"tax_type": "NONE",
"address_line_1": "64 Market St",
"administrative_district_level_1": "CA",
"partner_orgs": {
"507d7a57-94ae-4239-8a74-e93c00aa53e6": "Cyberdyne Corp. ",
"306bb6f4-e80c-4c9c-9e39-2a4d673998a8": "Initech Inc",
"8c68b16f-03a6-4203-9480-f969fa1492d9": "Nextably App",
"5b3e970a-fa32-4a6a-a51d-bbf483a6d405": "Givester App",
"94da8871-921a-4e45-b032-8045795aecaf": "Pied Piper corp"
},
"accepted_term_version": "8",
"is_agency": true,
"configuration_settings": {
"notifications_enabled": true
},
"type": "ENTERPRISE",
"state": "ACTIVE",
"roles": [
"member"
],
"ad_accounts": [
{
"id": "8b8e40af-fc64-455d-925b-ca80f7af6914",
"updated_at": "2018-03-07T23:39:20.469Z",
"created_at": "2018-03-27T23:42:43.513Z",
"name": "Hooli Originals",
"type": "PARTNER",
"status": "ACTIVE",
"currency": "USD",
"timezone": "America/Los_Angeles",
"roles": [
"reports"
]
},
{
"id": "497979f0-ea17-4971-8288-054883f1caca",
"updated_at": "2017-01-04T22:58:38.179Z",
"created_at": "2018-09-07T14:41:36.002Z",
"name": "Pied piper Test Account",
"type": "PARTNER",
"status": "ACTIVE",
"currency": "USD",
"timezone": "America/Los_Angeles",
"roles": [
"admin"
]
},
{
"id": "22ada972-f2aa-4d06-a45a-a7a80f53ae34",
"updated_at": "2017-07-28T02:32:03.914Z",
"created_at": "2017-12-08T21:56:57.305Z",
"name": "Initech Corp",
"type": "PARTNER",
"status": "ACTIVE",
"currency": "USD",
"timezone": "America/Los_Angeles",
"roles": [
"creative"
]
}
],
"my_display_name": "Honey Badger",
"my_invited_email": "honey.badget@hooli.com",
"my_member_id": "8454ada6-cec8-4e97-a0a7-c0b262c4137b"
}
}
]
}
This endpoint retrieves all organizations the logged in user has access to and the ad accounts beneath each of those organizations.
HTTP Request
GET https://adsapi.snapchat.com/v1/me/organizations?with_ad_accounts=true
Get a Specific Organization
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.organizations.get('40d6719b-da09-410b-9185-0cc9c0dfed1d')
curl "https://adsapi.snapchat.com/v1/organizations/40d6719b-da09-410b-9185-0cc9c0dfed1d" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5928472c00ff04f7eaae709d770001737e7465616d6b6f363139000161646d616e616765722d61706",
"organizations": [
{
"sub_request_status": "SUCCESS",
"organization": {
"id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
"updated_at": "2017-05-26T15:14:44.877Z",
"created_at": "2017-05-26T15:14:44.877Z",
"name": "My Organization",
"address_line_1": "101 Stewart St",
"locality": "Seattle",
"administrative_district_level_1": "WA",
"country": "US",
"postal_code": "98134",
"type": "ENTERPRISE"
}
}
]
}
This endpoint retrieves a specific organization.
HTTP Request
GET https://adsapi.snapchat.com/v1/organizations/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the organization to retrieve |
Funding Sources
An Funding Source is owned by an Organization and defines the financial instrument/terms responsible for the ad spend. 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 |
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 | |
| 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 | 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 |
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_signalsset totrueIf the ad account will be used for political advertising the attribute
paying_advertiser_nameneeds 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_clientneeds to be set totrueIf 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_clientneeds to be set totrue - The attribute
client_paying_invoicesneeds to be set totrueif the agency is paying the invoices, orfalseif the advertiser they represent is paying the invoices - The attribute
client_based_in_countryneeds to be set tofr - The attribute
agency_client_metadataneeds to be set using the attributesname,email,address_line_1,city,administrative_district_level_1,country,zipcodeandtax_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.
Assign Funding Source
curl -X PUT \
-H 'Authorization: Bearer meowmeowmeow' \
-H 'Content-Type: application/json' \
-d '{"type":"CREDIT_CARD","exclusive":true}' \
https://adsapi.snapchat.com/v1/adaccounts/d6923e88-bfd0-4f39-ac80-8154f21e8e5f/assign_payment_methods/8ca1687a-f2b4-437d-8554-a85403a714c5
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5eaacb7a00ff0418e163f94fe50001737e616473617069736300016275696c642d63386238336332372d312d3334372d310001014b",
"fundingsource": {
"id": "8ca1687a-f2b4-437d-8554-a85403a714c5",
"updated_at": "2017-10-17T12:28:44.440Z",
"created_at": "2017-10-17T12:28:44.440Z",
"type": "CREDIT_CARD",
"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
"name": "H Bear",
"card_type": "VISA",
"last_4": "5555",
"daily_spend_limit_micro": 15000000000,
"daily_spend_limit_currency": "USD",
"expiration_month": "03",
"expiration_year": "2023",
"status": "ACTIVE"
}
}
The following API request assigns a Funding Source to an Ad Account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/assign_payment_methods/{funding_source_id}
URL Parameters
| Parameter | Description |
|---|---|
| ad_account_id | The ID of the Ad Account that will have the funding source assigned |
| funding_source_id | The ID of the funding source to be assigned |
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_clienthas been set totrueclient_based_in_countryhas been set toFRclient_paying_invoiceshas been set tofalseas the Advertiser is paying the invoices (note that this should be set totrueif the Agency pays the invoices)agency_client_metadatahas been filled out with the address of the Advertiser and their French Tax ID
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” } |
** Coming soon. See Reach And Frequency
++ The regulations attribute alongside restricted_delivery_signals is required for Campaigns running Ads promoting Credit, Housing, Employment (CHE), this attribute has to be activated at Ad Account level first or it cannot be used at Campaign level; https://businesshelp.snapchat.com/en-US/a/create-ad-account
+- The regulations attribute alongside the candidate_ballot_information field is optional, but may be required in certain states The paying_advertiser attribute has to be activated at Ad Account level first or the candidate/ballot field cannot be used at Campaign level; https://businesshelp.snapchat.com/en-US/a/create-ad-account
To enable app install and post-install attribution on ads, the ‘measurement_spec’ field must be populated with the corresponding iOS and Android app IDs on campaign creation.
lifetime_spend_cap_micro can be increased and removed. Reducing the limit is allowed as long as the new limit is 1.1 times the amount already spent. daily_budget_micro set at the campaign level & the new lifetime_spend_cap_micro are evaluated independently. Delivery stops when either the Ad Account spend cap or the Campaign Lifetime spend cap is reached.
Create a Campaign
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"campaigns": [{"name": "Cool Campaign", "ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1d0d", "status": "PAUSED", "start_time": "2016-08-11T22:03:58.869Z"}]}' \
"https://adsapi.snapchat.com/v1/adaccounts/{ad_acount_id}/campaigns"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b002ad00ff07e1f50fd2267f0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"campaigns": [
{
"sub_request_status": "success",
"campaign": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"updated_at": "2016-08-14T05:33:33.876Z",
"created_at": "2016-08-14T05:33:33.876Z",
"name": "Cool Campaign",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"status": "PAUSED",
"start_time": "2016-08-11T22:03:58.869Z"
}
}
]
}
This endpoint will create a campaign within a specified ad account.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/campaigns
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_account_id | Ad Account ID |
Update a Campaign
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"campaigns": [{"name": "Cool Campaign", "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "status": "PAUSED", "start_time": "2016-08-11T22:03:58.869Z", "end_time": "2016-08-21T22:03:58.869-0700", "id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39"}]}'
https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/campaigns
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0032700ff07e0cfdaa5e1a40001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010105",
"campaigns": [
{
"sub_request_status": "success",
"campaign": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"updated_at": "2016-08-14T05:35:35.943Z",
"created_at": "2016-08-14T05:33:33.876Z",
"name": "Cool Campaign",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"status": "PAUSED",
"start_time": "2016-08-11T22:03:58.869Z",
"end_time": "2016-08-22T05:03:58.869Z"
}
}
]
}
This endpoint will update a specified campaign.
Attributes that can be updated
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| end_time | End time | O | |
| name | Campaign name | R | |
| daily_budget_micro | Daily Spend Cap (micro-currency) | O | |
| lifetime_spend_cap_micro | Lifetime spend cap for the campaign (micro-currency) | O | |
| start_time | Start time | O | |
| status | Campaign status | R | ACTIVE, PAUSED |
HTTP Request
PUT https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/campaigns
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_account_id | Ad Account ID |
Get All Campaigns
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()
curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_acount_id}/campaigns" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b003c700ff0f2e66c37f96c20001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010103",
"campaigns": [
{
"sub_request_status": "success",
"campaign": {
"id": "06302efa-4c0f-4e36-b880-a395a36cef64",
"updated_at": "2016-08-12T20:28:58.738Z",
"created_at": "2016-08-12T20:28:58.738Z",
"name": "Campaign One",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"daily_budget_micro": 200000000,
"status": "ACTIVE",
"start_time": "2016-08-10T17:12:49.707Z",
"end_time": "2016-08-13T17:12:49.707Z"
}
},
{
"sub_request_status": "success",
"campaign": {
"id": "0fc8e179-6f3b-46e7-be8e-ca53fd404ece",
"updated_at": "2016-08-12T21:06:18.343Z",
"created_at": "2016-08-12T21:06:18.343Z",
"name": "Campaign Deux",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"daily_budget_micro": 500000000,
"status": "ACTIVE",
"start_time": "2016-08-10T17:12:49.707Z",
"end_time": "2016-08-13T17:12:49.707Z"
}
},
[[[ snip ]]]
{
"sub_request_status": "success",
"campaign": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"updated_at": "2016-08-14T05:36:46.441Z",
"created_at": "2016-08-14T05:33:33.876Z",
"name": "Cool Campaign",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"status": "PAUSED",
"start_time": "2016-08-11T22:03:58.869Z",
"end_time": "2016-08-22T05:03:58.869Z"
}
},
{
"sub_request_status": "success",
"campaign": {
"id": "fedf8e04-0176-4ce3-a1ca-148204aee62c",
"updated_at": "2016-08-12T02:18:33.412Z",
"created_at": "2016-08-12T02:18:33.412Z",
"name": "Crazy Campaign",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"start_time": "2016-08-11T22:03:58.869Z",
"status": "PAUSED"
}
}
]
}
This endpoint retrieves all campaigns within a specified ad account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/campaigns
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_account_id | Ad Account ID |
Get a Specific Campaign
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get('92e1c28a-a331-45b4-8c26-fd3e0eea8c39')
curl "https://adsapi.snapchat.com/v1/campaigns/92e1c28a-a331-45b4-8c26-fd3e0eea8c39" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b0049c00ff0e8cb21af5199c0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010107",
"campaigns": [
{
"sub_request_status": "success",
"campaign": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"updated_at": "2016-08-14T05:36:46.441Z",
"created_at": "2016-08-14T05:33:33.876Z",
"name": "Cool Campaign",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"status": "PAUSED",
"start_time": "2016-08-11T22:03:58.869Z",
"end_time": "2016-08-22T05:03:58.869Z"
}
}
]
}
This endpoint retrieves a specific campaign.
HTTP Request
GET https://adsapi.snapchat.com/v1/campaigns/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the campaign to retrieve |
Delete a Specific Campaign
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get('92e1c28a-a331-45b4-8c26-fd3e0eea8c39')
curl -X DELETE "https://adsapi.snapchat.com/v1/campaigns/92e1c28a-a331-45b4-8c26-fd3e0eea8c39" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b004dc00ff0e29c26b5d51840001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010106",
"campaigns": []
}
This endpoint deletes a specific campaign.
HTTP Request
DELETE https://adsapi.snapchat.com/v1/campaigns/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the campaign to delete |
Ad Squads
An Ad Squad is owned by a Campaign and contains one or more Ads.
Attributes
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| campaign_id | Campaign ID | R | |
| bid_micro | Max Bid (micro-currency) | R | 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 minimum ROAS for the MIN_ROAS BidStrategy | R if BidStrategy = MIN_ROAS | Minimum desired ROAS |
| pixel_id | Pixel to be associated with the Ad Squad | O | |
| measurement_provider_names | approved measurement provider | O | MOAT_SS, DOUBLEVERIFY |
| reach_and_frequency_status** | Status of the reach and frequency booking | R | Must be set to PENDING which automatically updates to ACTIVE or FAILED after booking |
| delivery_constraint | Type of delivery | R | 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 |
** See Reach And Frequency
Bid Strategy
Example request setting
bid_strategyandbid_micro
curl -X PUT \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"adsquads":[{"campaign_id":"88b76b40-5888-4086-a028-7d18a8e82988","name":"Postman - bid_strategy test LOWEST_COST_WITH_MAX_BID", "type":"SNAP_ADS","placement_v2":{"config": "AUTOMATIC"},"optimization_goal":"IMPRESSIONS","daily_budget_micro":50000000,"bid_strategy": "LOWEST_COST_WITH_MAX_BID","bid_micro":100000,"targeting":{"regulated_content":true,"geos":[{"country_code":"us"}], "demographics":[{"age_groups":["21-24","18-20","25-34","35+"]}]},"delivery_constraint":"DAILY_BUDGET", "start_time":"2020-07-13T21:12:45Z","status":"ACTIVE"}]}'
https://adsapi.snapchat.com/v1/campaigns/88539b6b-93f2-4b3a-8181-ca869cb45088/adsquads
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e722f8800ff07b4e7eea281bb0001737e616473617069736300016275696c642d63333065633630652d312d3333352d300001013d",
"adsquads": [
{
"sub_request_status": "SUCCESS",
"adsquad": {
"id": "88539b6b-93f2-4b3a-8181-ca869cb45088",
"updated_at": "2020-03-18T14:26:16.939Z",
"created_at": "2020-03-18T14:26:16.939Z",
"name": "Postman - bid_strategy test LOWEST_COST_WITH_MAX_BID",
"status": "ACTIVE",
"campaign_id": "88b76b40-5888-4086-a028-7d18a8e82988",
"type": "SNAP_ADS",
"targeting": {
"regulated_content": true,
"demographics": [
{
"age_groups": [
"21-24",
"18-20",
"25-34",
"35+"
]
}
],
"geos": [
{
"country_code": "us"
}
]
},
"targeting_reach_status": "VALID",
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 100000,
"auto_bid": false,
"target_bid": false,
"bid_strategy": "LOWEST_COST_WITH_MAX_BID",
"daily_budget_micro": 50000000,
"start_time": "2020-07-13T21:12:45.000Z",
"optimization_goal": "IMPRESSIONS",
"delivery_constraint": "DAILY_BUDGET",
"pacing_type": "STANDARD"
}
}
]
}
On the 20th of March 2020 we announced the deprecation of the attributes auto_bid and target_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 |
| TARGET_COST | Achieves the most volume while aiming to keep your average cost per action below your target cost | use bid_micro to set bid |
Optimization Goals allowed per Bid Strategy.
| bid_strategy | Optimization goals |
|---|---|
| AUTO_BID | 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 bid 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_micro1000000 in an Ad Account using the currency USD, means an expectation of $1 in revenue per $1 bid - A
roas_value_micro500000 in an Ad Account using the currency GBP, means an expectation of £1 in revenue per £0.50 bid - A
roas_value_micro1500000 in an Ad Account using the currency EUR, means an expectation of €1 in revenue per €1.50 bid
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 chose the optimal placement for your ad. All the other properties in placement_v2 cannot be provided |
| CUSTOM | Advertiser will chose all the settings for the placement. platforms must contain a value and snapchat_positions must not be empty |
snapchat_positions
| Value | Description |
|---|---|
| INTERSTITIAL_USER | Ads run between friend stories. Ad Squad type must be SNAP_ADS |
| INTERSTITIAL_CONTENT | Ads run before and after stories in publisher and our stories. Ad Squad type must be SNAP_ADS |
| INSTREAM | Ads run inside i.e. in between stories in publisher and our stories. Ad Squad type must be SNAP_ADS |
| FEED | “Tile-based” ads. Currently, only in Discover feed. Ad Squad type must be SNAP_ADS. Ad type must be STORY |
| CAMERA | Ads run in Filter or Lens carousel. Ad Squad type should either be LENS or FILTER |
| GAMES | Ads run as Commercials within Snap Games. Ad Squad type must be SNAP_ADS |
Example
{
"config": "CUSTOM",
"platforms": [
"SNAPCHAT",
],
"snapchat_positions": [
"INTERSTITIAL_USER",
"INSTREAM"
],
"inclusion": {
"content_types": [
"BEAUTY"
]
}
placement_v2 config Examples for different types of Ad Squads based on Ad type
Example 1
Snap Ads running with Automatic placement
"placement_v2": {
"config": "AUTOMATIC"
},
Example 2
Snap Ads running between User stories only
"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"INTERSTITIAL_USER"
]
},
Example 3
Snap Ads running between User stories and Curated content
"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"INTERSTITIAL_CONTENT",
"INTERSTITIAL_USER"
]
},
Example 4
Snap Ads running inside of curated content
"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"INSTREAM"
]
},
Example 5
Snap Ads running as commercials via premium content bundle
"placement_v2":{
"config":"CUSTOM",
"platforms":[
"SNAPCHAT"
],
"snapchat_positions":[
"INSTREAM"
],
"inclusion":{
"premium_content_bundle_ids":[
"c7e251af-3606-4f03-91f1-98456161655d"
]
},
Example 6
Snap Ads running as commercials via premium content bundle and Snap Games
"placement_v2":{
"config":"CUSTOM",
"platforms":[
"SNAPCHAT"
],
"snapchat_positions":[
"INSTREAM",
"GAMES"
],
"inclusion":{
"premium_content_bundle_ids":[
"c7e251af-3606-4f03-91f1-98456161655d"
]
},
Example 7
Story Ad running in the Discover feed
"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"FEED"
]
},
Example 8
Lens/Filter Ad placed in the Camera
"placement_v2": {
"config": "CUSTOM",
"platforms": [
"SNAPCHAT"
],
"snapchat_positions": [
"CAMERA"
]
},
Pacing Types
Validations
If pacing_type is set to ACCELERATED for accelerated delivery the following validations apply:
bid_strategymust be set to ‘LOWEST_COST_WITH_MAX_BID’bid_micromust be setoptimization_goalmust be one of IMPRESSIONS, USES, SWIPES, VIDEO_VIEWS, VIDEO_VIEWS_15_SEC or STORY_OPENS
pacing_type is immutable and can be changed given the correct validations are in place.
Squad Optimization Goals
Goal-Based Bidding (GBB) allows a squad to be optimized toward a specific outcome.
Optimization Goal changes how the squad’s bid_micro is interpreted.
Note: No matter what Optimization Goal is selected, the Billing Event will still be IMPRESSION. This may change in the future.
| Optimization Goal | Bid Interpretation | Details |
|---|---|---|
| IMPRESSIONS | Cost Per 1000 Impressions (CPM) | bid_micro will not be exceeded |
| SWIPES | Target Cost Per Swipe | bid_micro is treated as a goal, not a maximum, and can be exceeded |
| APP_INSTALLS | Target Cost Per Install | bid_micro is treated as a goal, not a maximum, and can be exceeded |
| VIDEO_VIEWS | Target Cost per 2 second Video View | bid_micro is treated as a goal, not a maximum, and can be exceeded |
| VIDEO_VIEWS_15_SEC | Target Cost per 15 second Video View | bid_micro is treated as a goal, not a maximum, and can be exceeded |
| 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 |
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
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) |
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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()
curl "https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads?return_placement_v2=true" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b00b1500ff0476bcfb96faa20001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010b",
"adsquads": [
{
"sub_request_status": "success",
"adsquad": {
"id": "0633e159-0f41-4675-a0ba-224fbd70ac4d",
"updated_at": "2016-08-14T05:52:45.186Z",
"created_at": "2016-08-14T05:52:45.186Z",
"name": "Ad Squad Apples",
"status": "PAUSED",
"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
"type": "SNAP_ADS",
"targeting": {
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 1000000000,
"start_time": "2016-08-11T22:03:58.869Z",
"optimization_goal": "IMPRESSIONS"
}
},
{
"sub_request_status": "success",
"adsquad": {
"id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"updated_at": "2016-08-14T05:58:55.409Z",
"created_at": "2016-08-14T05:58:55.409Z",
"name": "Ad Squad Uno",
"status": "ACTIVE",
"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
"type": "SNAP_ADS",
"targeting": {
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 1000000,
"auto_bid": false,
"target_bid": true,
"bid_strategy": "TARGET_COST",
"daily_budget_micro": 1000000000,
"start_time": "2016-08-11T22:03:58.869Z",
"optimization_goal": "IMPRESSIONS"
}
}
]
}
This endpoint retrieves all ad squads within a specified campaign.
HTTP Request
GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads
Parameters
| Parameter | Default | Description |
|---|---|---|
| campaign_id | Campaign ID | |
| return_placement_v2 | true | optional parameter for retrieving placement_v2 attribute |
Get All Ad Squads under an Ad Account
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.ad_accounts.get()
curl "https://adsapi.snapchat.com/v1/adaccounts/8cf88872-048b-4447-95d1-eb48231788be/adsquads?return_placement_v2=true" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b00b1500ff0476bcfb96faa20001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010b",
"adsquads": [
{
"sub_request_status": "success",
"adsquad": {
"id": "0633e159-0f41-4675-a0ba-224fbd70ac4d",
"updated_at": "2016-08-14T05:52:45.186Z",
"created_at": "2016-08-14T05:52:45.186Z",
"name": "Ad Squad Apples",
"status": "PAUSED",
"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
"type": "SNAP_ADS",
"targeting": {
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"auto_bid": true,
"target_bid": false,
"bid_strategy": "AUTO_BID",
"daily_budget_micro": 1000000000,
"start_time": "2016-08-11T22:03:58.869Z",
"optimization_goal": "IMPRESSIONS"
}
},
{
"sub_request_status": "success",
"adsquad": {
"id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"updated_at": "2016-08-14T05:58:55.409Z",
"created_at": "2016-08-14T05:58:55.409Z",
"name": "Ad Squad Uno",
"status": "ACTIVE",
"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
"type": "SNAP_ADS",
"targeting": {
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 1000000,
"auto_bid": false,
"target_bid": true,
"bid_strategy": "TARGET_COST",
"daily_budget_micro": 1000000000,
"start_time": "2016-08-11T22:03:58.869Z",
"optimization_goal": "IMPRESSIONS"
}
}
]
}
This endpoint retrieves all ad squads within a specified ad account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/adsquads
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_account_id | Ad Account ID | |
| return_placement_v2 | true | optional parameter for retrieving placement_v2 attribute |
Get a Specific Ad Squad
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get('f016fc4b-5b2d-44cf-be60-b9e7955829d2')
curl "https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe?return_placement_v2=true" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b00bd200ff0a1092e59e2ec90001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"adsquads": [
{
"sub_request_status": "success",
"adsquad": {
"id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"updated_at": "2016-08-14T05:58:55.409Z",
"created_at": "2016-08-14T05:58:55.409Z",
"name": "Ad Squad Uno",
"status": "ACTIVE",
"campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
"type": "SNAP_ADS",
"targeting": {
"geos": [
{
"country_code": "us"
}
]
},
"placement_v2": {
"config": "AUTOMATIC"
},
"billing_event": "IMPRESSION",
"bid_micro": 1000000,
"auto_bid": false,
"target_bid": true,
"bid_strategy": "TARGET_COST",
"daily_budget_micro": 1000000000,
"start_time": "2016-08-11T22:03:58.869Z",
"optimization_goal": "IMPRESSIONS"
}
}
]
}
This endpoint retrieves a specific ad squad.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/<ID>
URL Parameters
| Parameter | Default | Description |
|---|---|---|
| ID | The ID of the adsquad to retrieve | |
| return_placement_v2 | true | optional parameter for retrieving placement_v2 attribute |
Delete an Ad Squad
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get('f016fc4b-5b2d-44cf-be60-b9e7955829d2')
curl -X DELETE "https://adsapi.snapchat.com/v1/adsquads/0633e159-0f41-4675-a0ba-224fbd70ac4d" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b00c6a00ff068aea0cfe17bd0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010109",
"adsquads": []
}
This endpoint deletes a specific ad squad.
HTTP Request
DELETE https://adsapi.snapchat.com/v1/adsquads/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the adsquad to delete |
Ads
Ad is a light weight entity that contains all the information needed to display the ad. It also contains a third party measurement URL if needed.
Attributes
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| ad_squad_id | Ad Squad ID | R | |
| creative_id | Creative ID | R | |
| name | Ad name | R | |
| paying_advertiser_name | Name of the paying advertiser/political entity | O | This value is inherited from the Ad Account entity and is immutable |
| review_status | Ad Review Status | READ ONLY | PENDING, APPROVED, REJECTED |
| review_status_reason | List of Ad Review Rejection Reasons | READ ONLY | if rejected, list of reasons |
| status | Ad status | R | ACTIVE, PAUSED |
| type | Ad type | R | SNAP_AD, LONGFORM_VIDEO, APP_INSTALL, REMOTE_WEBPAGE, DEEP_LINK, STORY, AD_TO_LENS, AD_TO_CALL, AD_TO_MESSAGE, FILTER, LENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_LONGFORM_VIDEO, COLLECTION* |
Ad Type <-> Creative Type Mapping
| Ad Type | Allowed Creative Type |
|---|---|
| APP_INSTALL | APP_INSTALL |
| LONGFORM_VIDEO | LONGFORM_VIDEO |
| SNAP_AD | SNAP_AD (aka top snap only) |
| REMOTE_WEBPAGE | WEB_VIEW |
| DEEP_LINK | DEEP_LINK |
| STORY | COMPOSITE |
| AD_TO_LENS | AD_TO_LENS |
| AD_TO_CALL | AD_TO_CALL |
| AD_TO_MESSAGE | AD_TO_MESSAGE |
| FILTER | FILTER |
| LENS | LENS |
| LENS_REMOTE_WEBPAGE | LENS_WEB_VIEW |
| LENS_APP_INSTALL | LENS_APP_INSTALL |
| LENS_DEEP_LINK | LENS_DEEP_LINK |
| LENS_LONGFORM_VIDEO | LENS_LONGFORM_VIDEO |
| COLLECTION | COLLECTION |
Create an Ad
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get()
curl -X POST \
-d '{"ads":[{"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe", "creative_id":"c1e6e929-acec-466f-b023-852b8cacc18f", "name": "Ad One", "type": "SNAP_AD", "status": "PAUSED"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b018c500ff0d22d3cefd730d0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010107",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:07:50.241Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "PAUSED",
"type": "SNAP_AD"
}
}
]
}
This endpoint creates an Ad within an Ad Squad.
HTTP Request
POST https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_squad_id | Ad Squad ID |
Update an Ad
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()
curl -X PUT \
-d '{"ads":[{"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4", "ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe", "creative_id":"c1e6e929-acec-466f-b023-852b8cacc18f", "name": "Ad One", "type": "SNAP_AD", "status": "ACTIVE"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/1933aa48-249b-4ce4-8330-dfe3977312dd/ads
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01a6300ff0c09d23a7706470001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010108",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:14:45.174Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "ACTIVE",
"type": "SNAP_AD"
}
}
]
}
This endpoint updated an Ad within an Ad Squad.
HTTP Request
PUT https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_squad_id | Ad Squad ID |
Attributes that can be updated
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| name | Ad name | R | |
| status | Ad status | R | ACTIVE, PAUSED |
| on_swipe_tracking_urls | Third-party swipe-up tags | O | |
| third_party_tracking_urls | Third-party impression tags | O |
HTTP Request
PUT https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_squad_id | Ad Squad ID |
Get All Ads under an Ad Squad
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()
curl "https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01b3400ff0608a82948df6b0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "2ded6d53-0805-4ff8-b984-54a7eb5c8918",
"updated_at": "2016-08-14T07:18:05.699Z",
"created_at": "2016-08-14T07:18:05.699Z",
"name": "Ad Two",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "PAUSED",
"type": "SNAP_AD"
}
},
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:14:45.174Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "ACTIVE",
"type": "SNAP_AD"
}
}
]
}
This endpoint retrieves all ads within a specified ad squad.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/ads
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_squad_id | Ad Squad ID |
Get All Ads under an Ad Account
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()
curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/ads" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01b3400ff0608a82948df6b0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "2ded6d53-0805-4ff8-b984-54a7eb5c8918",
"updated_at": "2016-08-14T07:18:05.699Z",
"created_at": "2016-08-14T07:18:05.699Z",
"name": "Ad Two",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "PAUSED",
"type": "SNAP_AD"
}
},
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:14:45.174Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "ACTIVE",
"type": "SNAP_AD"
}
}
]
}
This endpoint retrieves all ads within a specified ad account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/ads
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_account_id | Ad Account ID |
Get a Specific Ad
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.ads.get('e8d6217f-32ab-400f-9e54-39a86a7963e4')
curl "https://adsapi.snapchat.com/v1/ads/e8d6217f-32ab-400f-9e54-39a86a7963e4"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01adc00ff0a5290ad9d42c00001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010103",
"ads": [
{
"sub_request_status": "success",
"ad": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"updated_at": "2016-08-14T07:14:45.174Z",
"created_at": "2016-08-14T07:07:50.241Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"status": "ACTIVE",
"type": "SNAP_AD"
}
}
]
}
This endpoint retrieves a specific ad.
HTTP Request
GET https://adsapi.snapchat.com/v1/ads/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the ad to retrieve |
Delete an Ad
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get('f016fc4b-5b2d-44cf-be60-b9e7955829d2')
curl -X DELETE "https://adsapi.snapchat.com/v1/ads/2ded6d53-0805-4ff8-b984-54a7eb5c8918" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b01b6200ff05d100ff30ca9b1d0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010101",
"ads": []
}
This endpoint deletes a specific ad.
HTTP Request
DELETE https://adsapi.snapchat.com/v1/ads/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the ad to delete |
Third-Party Tracking Tags
On the 1st of January 2020 we will be sunsetting the fields on_swipe_tracking_urls and third_party_tracking_urls.
From the 1st of January 2020 it won’t be possible to update an Ad entity without removing the third-party tracking from the deprecated fields. This tracking can instead be implemented within the two fields third_party_on_swipe_tracking_urls and third_party_paid_impression_tracking_urls.
If you are trafficking third-party tags to the fields on_swipe_tracking_urls and/or third_party_tracking_urls you should amend your app as soon as possible and make use of the corresponding fields third_party_on_swipe_tracking_urls and third_party_paid_impression_tracking_urls.
Additionally MOAT tracking at Ad level will also be sunset on the 1st of January 2020, for any Ads where you wish to implement MOAT tracking you should instead activate the MOAT tracking at AdSquad level, using the new measurement_provider_names attribute. Activation at AdSquad level will apply MOAT tracking to all Ad entities within the AdSquad.
Snap currently allows third-party tags from DCM, MDAR and Integral Ad Science (IAS).
MOAT tracking should be implemented at AdSquad level tracking activation via the measurement_provider_names attribute.
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.ads.create()
curl -X PUT \
-d '{"ads":[{"id": "ebb64f61-0e12-4f3c-a55c-71a9a6d1ea63", "ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe", "creative_id":"c1e6e929-acec-466f-b023-852b8cacc18f", "name": "Ad One", "type": "SNAP_AD", "status": "ACTIVE", "third_party_paid_impression_tracking_urls": ["https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.222222222;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"],"third_party_on_swipe_tracking_urls": ["https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.333333333;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"]}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "58bb7c5000ff06616e9fa0e86e0001737e616473617069736300016275696c642d33333562626234342d312d35302d330001013d",
"ads": [
{
"sub_request_status": "SUCCESS",
"ad": {
"id": "ebb64f61-0e12-4f3c-a55c-71a9a6d1ea63",
"updated_at": "2017-03-18T00:16:17.690Z",
"created_at": "2017-03-18T00:16:17.690Z",
"name": "Ad One",
"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
"third_party_paid_impression_tracking_urls": [
{
"trackingUrlMetadata": null,
"expandedTrackingUrl": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.222222222;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?",
"tracking_url": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.222222222;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"
}
],
"third_party_on_swipe_tracking_urls": [
{
"trackingUrlMetadata": null,
"expandedTrackingUrl": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.33333333;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?",
"tracking_url": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.33333333;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"
}
],
"status": "PAUSED",
"type": "SNAP_AD",
"review_status": "APPROVED"
}
}
]
}
Additional Ad Attributes
| Attribute | Description | Required |
|---|---|---|
| third_party_on_swipe_tracking_urls | Third-party swipe tags, executed on swipe of attachment | O |
| third_party_paid_impression_tracking_urls | Third-party impression tags, executed on ad impression | O |
DEPRECATED, Use attribute third_party_on_swipe_tracking_urls |
- | |
DEPRECATED, Use attribute third_party_paid_impression_tracking_urls |
- |
Approved Third Party Tracking URL domains
| URL | Description |
|---|---|
| secure-gl.imrworldwide.com | |
| ad.doubleclick.net | |
| pixel.adsafeprotected.com | |
| DEPRECATED, Use AdSquad level tracking activation |
How to get tags
DCM and IAS: Refer to your DCM/IAS Account Manager to request tags or generate them using the campaign management tools.
mDAR: Clients should request their Snapchat Account Manager to provide a tag.
Notes
- Ensure all tags are secure and use https
- Choose standard type 1x1 pixel and not Javascript or iframe
- Make sure cachebusting parameter is ~.~TIMESTAMP~.~ and not [timestamp]
URL Macros
There are several dynamic placeholder macros that can be used within the URL that are replaced on-the-fly:
| Macro | Description |
|---|---|
| ~.~SERVER_ORG_ID~.~ | Organization ID |
| ~.~SERVER_AD_ACCOUNT_ID~.~ | Ad Account ID |
| ~.~SERVER_CAMPAIGN_ID~.~ | Campaign ID |
| ~.~SERVER_AD_SQUAD_ID~.~ | Ad Squad ID |
| ~.~SERVER_CREATIVE_ID~.~ | Creative ID |
| ~.~SERVER_AD_ID~.~ | Ad ID |
| ~.~SERVER_MOAT_PRODUCT_TYPE~.~ | Ad Product Type |
| ~.~TIMESTAMP~.~ | Timestamp |
Media
Media is a single video that can be used to construct Creative. Media objects are owned by an Ad Account and can be used by multiple Creatives simultaneously.
Attributes
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| ad_account_id | Ad Account ID | R | |
| download_link | URL to Media File | READ-ONLY | |
| media_status | Media Status | READ-ONLY | PENDING_UPLOAD, READY |
| name | Media name | R | |
| type | Media Type | R | VIDEO, IMAGE, LENS_PACKAGE |
| lens_package_metadata | Metadata for lens media created by Lens Studio | READ-ONLY |
Create Media
curl -X POST \
-d '{"media": [{"name":"Media A - Video", "type":"VIDEO","ad_account_id":"{ad_account_id}"}]}' \
-H "Content-Type: application/json" \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/media
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b00d1900ff08a0dae50ab27a0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010b",
"media": [
{
"sub_request_status": "success",
"media": {
"id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"updated_at": "2016-08-14T06:18:01.855Z",
"created_at": "2016-08-14T06:18:01.855Z",
"name": "Media A - Video",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "VIDEO",
"media_status": "PENDING_UPLOAD"
}
}
]
}
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/media
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_account_id | Ad Account ID |
Upload Media - Video
curl -X POST -H 'content-type: multipart/form-data' -F 'file=@"/files/MOV_1808.mov";filename="MOV_1808.mov"' \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/media/a7bee653-1865-41cf-8cee-8ab85a205837/upload
The above command returns JSON structured like this:
{
"result": {
"id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"updated_at": "2016-08-14T06:24:28.378Z",
"created_at": "2016-08-14T06:23:37.086Z",
"name": "Media A - Video",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "VIDEO",
"media_status": "READY",
"file_name": "sample.mov"
},
"request_status": "success",
"request_id": "57b00e9a00ff0ccb4293400c840001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010103"
}
This endpoint receives the actual video data for the media. Snap Inc. hosts all media on behalf of the advertiser.
HTTP Request
POST https://adsapi.snapchat.com/v1/media/{media_id}/upload
Parameters
| Parameter | Default | Description |
|---|---|---|
| media_id | Media ID |
Upload Media - Image
Media of type ‘IMAGE’ can be used either for app icons used in APP INSTALL creatives or as top snap media for other Snap Ads. Snapchat hosts all media on behalf of the advertiser.
Specifications for app icon:
- File type should be PNG
- Minimum dimensions; 200 x 200 px, Maximum dimensions; 2000 x 2000 px
- Image should be square
- Image shouldn’t have any borders or padding
Specifications for top snap image:
- File type should be PNG, JPG or JPEG
- Minimum image size: 1080 x 1920 pixels
- Max file size: 5MB
IMAGE type top snaps are converted into 5 sec videos and rendered on the client as videos. Supported Optimization goals for ads using IMAGE type media are: IMPRESSIONS, SWIPES, APP_INSTALLS
curl -X POST -H 'content-type: multipart/form-data' -F 'file=@"/files/app_icon.png";filename="app_icon.png"' \
-H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/media/8adc3db7-8148-4fbf-999c-8d2266369d75/upload
The above command returns JSON structured like this:
{
"result": {
"id": "77062ed3-4abf-49a8-ac3f-8157cf14cb41",
"updated_at": "2017-04-14T19:39:05.969Z",
"created_at": "2017-04-14T19:19:59.708Z",
"name": "IMAGE media",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d75",
"type": "IMAGE",
"media_status": "READY",
"file_name": "app_icon.png",
"download_link": "https://storage.googleapis.com/ad-manager-creatives-production/77062ed3-4abf-49a8-ac3f-8157cf14cb41/7d935b22-eb12-41b8-9e34-713b64f2e3b3.png"
},
"request_status": "SUCCESS",
"request_id": "58f1255800ff0d03cc7c0c03380001737e616473617069736300016275696c642d64373565633561632d312d35382d3100010"
}
Upload Large Media (Chunked)
This endpoint receives the actual video data for the media. Snapchat hosts all media on behalf of the advertiser.
Files larger than 32MB need to be uploaded in chunks.
- Split the large file
- Initialize a chunked upload request
- Get the “add_path”, “finalize_path” and “upload_id” from the response, these will be unique to your upload
- Upload all parts of the file using the “add_path” , you will need to prepend it with https://adsapi.snapchat.com
- Finalize the chunked upload request using the “finalize_path”, you will need to prepend it with https://adsapi.snapchat.com
Request and Parameters for INIT
POST https://adsapi.snapchat.com/v1/media/{media_id}/multipart-upload-v2?action=INIT
| Parameter | Description |
|---|---|
| action | INIT (query param) |
| file_name | File Name |
| file_size | Total file size in bytes (cannot exceed 1GB) |
| number_of_parts | Number of parts to expect |
Request and Parameters for ADD
POST https://adsapi.snapchat.com + add_path
| Parameter | Description |
|---|---|
| file | File Part |
| part_number | File part number, used during re-assembly of file |
| upload_id | Chunked Upload ID from INIT |
Request and Parameters for FINALIZE
POST https://adsapi.snapchat.com + finalize_path
| Parameter | Description |
|---|---|
| upload_id | Chunked Upload ID from INIT |
1. Split the large file
Example: split -b 2m lfv.mov split_lfv.
2. Initialize a chunked upload request
curl -X POST -H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: multipart/form-data" \
-F "file_name=lfv.mov" \
-F "file_size=4887527" \
-F "number_of_parts=3" \
"https://adsapi.snapchat.com/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=INIT"
3. Extract upload_id, add_path and finalize_path from response:
{
"request_status":"SUCCESS",
"request_id":"57e56c0b00ff0e1b43229b96350001737e616473617069736300016275696c642d62646338336131372d312d31352d3100010109",
"upload_id":"cffc3975-f2b3-40d2-bf81-f0e7d97b9af5",
"add_path":"/us/v1/media/7bd44f53-5de7-41c4-90c7-50633e5dbb7e/multipart-upload-v2?action=ADD",
"finalize_path":"/v1/media/7bd44f53-5de7-41c4-90c7-50633e5dbb7e/multipart-upload-v2?action=FINALIZE"
}
4. Upload all parts using the add_path prepended with https://adsapi.snapchat.com:
curl -X POST -H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: multipart/form-data" \
-F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
-F "file=@split_lfv.aa" \
-F "part_number=1" \
"https://adsapi.snapchat.com/us/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=ADD"
curl -X POST -H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: multipart/form-data" \
-F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
-F "file=@split_lfv.ab" \
-F "part_number=2" \
"https://adsapi.snapchat.com/us/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=ADD"
curl -X POST -H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: multipart/form-data" \
-F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
-F "file=@split_lfv.ac" \
-F "part_number=3" \
"https://adsapi.snapchat.com/us/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=ADD"
5. Finalize the chunked upload request using finalize_path prepended with https://adsapi.snapchat.com
curl -X POST -H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: multipart/form-data" \
-F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
"https://adsapi.snapchat.com/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=FINALIZE"
The above command returns JSON structured like this:
{
"result": {
"id": "7536bbc5-0074-4dc4-b654-5ba9cd9f9441",
"updated_at": "2016-09-23T17:59:23.826Z",
"created_at": "2016-09-23T17:51:07.799Z",
"name": "Media Chunked - Video",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "VIDEO",
"media_status": "READY",
"file_name": "lfv.mov",
"download_link": "https://storage.googleapis.com/ad-manager-creatives-production-us/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/b195bd7c-aa7b-44c4-83a5-2c12e77a8784.mov"
},
"request_status": "SUCCESS",
"request_id": "57e56d7a00ff0b82bd232ea3d40001737e616473617069736300016275696c642d62646338336131372d312d31352d3100010134"
}
Get All Media
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get()
curl "https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/media" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b00ee800ff0a7e553a9389710001737e616473617069736300016275696c642d35396264653638322d312d31312d37000100",
"media": [
{
"sub_request_status": "success",
"media": {
"id": "7f65f9ff-63d8-41e7-991a-06b95a1ffbde",
"updated_at": "2016-08-12T20:39:57.029Z",
"created_at": "2016-08-12T20:39:57.029Z",
"name": "Media 2",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "VIDEO",
"media_status": "PENDING_UPLOAD"
}
},
{
"sub_request_status": "success",
"media": {
"id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"updated_at": "2016-08-14T06:24:28.378Z",
"created_at": "2016-08-14T06:23:37.086Z",
"name": "Media A - Video",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "VIDEO",
"media_status": "READY",
"file_name": "sample.mov"
}
},
{
"sub_request_status": "success",
"media": {
"id": "ab32d7e5-1f80-4e1a-a76b-3c543d2b28e4",
"updated_at": "2016-08-12T17:38:01.918Z",
"created_at": "2016-08-12T17:36:59.740Z",
"name": "App Icon",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "IMAGE",
"media_status": "READY",
"file_name": "Mobile Strike.png"
}
}
]
}
This endpoint retrieves all media associated with an ad account.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/media
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_account_id | Ad Account ID |
Get a Specific Media
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get(2)
curl "https://adsapi.snapchat.com/v1/media/a7bee653-1865-41cf-8cee-8ab85a205837" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b00f5f00ff0bd6909e4148c30001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010102",
"media": [
{
"sub_request_status": "success",
"media": {
"id": "a7bee653-1865-41cf-8cee-8ab85a205837",
"updated_at": "2016-08-14T06:24:28.378Z",
"created_at": "2016-08-14T06:23:37.086Z",
"name": "Media A - Video",
"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
"type": "VIDEO",
"media_status": "READY",
"file_name": "sample.mov"
}
}
]
}
This endpoint retrieves a specific media.
HTTP Request
GET https://adsapi.snapchat.com/v1/media/<ID>
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the media to retrieve |
Get Preview for a Specific Media
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get(2)
curl "https://adsapi.snapchat.com/v1/media/8e781365-ce4c-4336-8c53-f6a1f7c50af1/preview" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5aa8450b00ff00ff741e879aff00580001737e816473617069736300016275696x642d37633033663563332d312d3134392d310001015e",
"expires_at": "2018-03-14T21:39:23.303Z",
"link": "https://adsapisc.appspot.com/media/video_preview?media_id=8e781365-ce4c-4336-8c53-f6a1f7c50af1&expires_at=1521063563303&signature=MGQCMA1DRI6uBax3GSq93E8hp5b3P2Ebg0lIlPa8iGML9rs1B9WFmPeHH6ttvx_rmDG5AgIwY0pjIvEEpwOXM8o3h9Hst60DjRN9Mw7am7OmkdrBGfoI4IiHBflv0XpK87Tnb_BE"
}
This endpoint retrieves the preview for a specific media.
HTTP Request
GET https://adsapi.snapchat.com/v1/media/<ID>/preview
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the media to retrieve |
Get Thumbnail for a Specific Media
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get(2)
curl "https://adsapi.snapchat.com/v1/media/095a4a6d-01a0-4f6a-8901-41ea38c7a540/thumbnail" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b99772a00ff06928d3e31e94b0001737e616473617069736300016275696c642d33346634346232622d312d3230302d3200010154",
"expires_at": "2018-09-13T20:29:30.555Z",
"link": "https://adsapisc.appspot.com/media/video_thumbnail?media_id=095a4a6d-01b0-4f6c-8901-41ee38c7b540&expires_at=1536870570555&signature=MGQCMBQ_NfJM0yZCrdyLiEon4Lkbei0zFJF2HpLiHa2NvSLV2JyOVhLqHfQgqbDWUuzaCQIwHzPj_ZFtPNk688SoFiKWUIFEKKBMhSm8t4moy9xlfgnoSv-8LMQ1omM_P8QCj7O9"
}
This endpoint retrieves a thumbnail for media of the type VIDEO Thumbnails cannnot be fetched for other Media types (IMAGE, LENS_PACKAGE).
HTTP Request
GET https://adsapi.snapchat.com/v1/media/<ID>/thumbnail
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the media (type VIDEO) to retrieve a thumbnail from |
Creatives
A Creative is the combination of one or more pieces of media. Creative is owned by an Ad Account and can be used by multiple Ads simultaneously.
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:
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, 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, 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 | 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 | 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 | 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
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get(2)
curl "https://adsapi.snapchat.com/v1/creatives/c1e6e929-acec-466f-b023-852b8cacc54f/snapcode" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5aa15e8000ff03acde535d9a200001737e616473617069736300016275696c642d62633562363761342d312d3134372d3600013326",
"creative_id": "c1e6e929-acec-466f-b023-852b8cacc54f",
"expires_at": "2018-03-09T15:51:33.248Z",
"snapcode_link": "https://adsapisc.appspot.com/snapcodeimage/c1e6e929-acec-466f-b023-852b8cacc54f/352a899e-4a9d-3fdf-8efe-9bac9b8a0a21"
}
This endpoint retrieves the snapcode preview for a specific creative.
HTTP Request
GET https://adsapi.snapchat.com/v1/creatives/<ID>/snapcode
URL Parameters
| Parameter | Description |
|---|---|
| ID | The ID of the creative to retrieve |
Commercials
Commercials are non-skippable 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 |
|---|---|---|---|
| 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 |
|---|---|---|---|
| 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 |
Targeting Dimensions
All targeting dimensions will now have a deprecated boolean flag that will show whether the targeting dimension is deprecated. If a dimension has deprecated=true you will no longer be able to use it in the targeting_spec of an Ad Squad.
Targeting Type Support by Country
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.get()
curl "https://adsapi.snapchat.com/v1/targeting/options/US" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "58db128000099520da4b9237",
"targeting_option": {
"snap_ads": [
"demographics:advanced_demographics",
"demographics:age_groups",
"demographics:gender",
"devices:carrier",
"devices:connection_type",
"devices:os_type",
"geos:country",
"geos:metro",
"geos:region",
"interests:dlxc",
"interests:dlxs",
"interests:slc",
"regulated_content",
"segments:ab_segments",
"segments:engagement",
"segments:first_party",
"segments:lookalike"
]
}
}
This endpoint retrieves all targeting options available for the specified country code.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/options/{country_code}
Parameters
| Parameter | Default | Description |
|---|---|---|
| country_code | ISO ALPHA-2 Country Code (lowercase) |
Demographics
Demographics targeting allows an advertiser to find a user based on a variety of criteria.
Demographics - Age Groups
Get Age Group Targeting Options
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.demographics.age_groups()
curl "https://adsapi.snapchat.com/v1/targeting/demographics/age_group" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "57d1cb6900ff0c21bb32e920a00001737e616473617069736300016275696c642d66333735626434642d312d31332d3700010111",
"targeting_dimensions": [
{
"sub_request_status": "SUCCESS",
"age_group": {
"name": "13-17",
"id": "13"
}
},
{
"sub_request_status": "SUCCESS",
"age_group": {
"name": "18-20",
"id": "18"
}
},
{
"sub_request_status": "SUCCESS",
"age_group": {
"name": "21-24",
"id": "21"
}
},
{
"sub_request_status": "SUCCESS",
"age_group": {
"name": "25-34",
"id": "25"
}
},
{
"sub_request_status": "SUCCESS",
"age_group": {
"name": "35+",
"id": "35"
}
}
]
}
This endpoint retrieves the list of age group targeting options.
HTTP Request
GET https://adsapi.snapchat.com/v1/targeting/demographics/age_group
Demographics - Age Range
You can 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 or mobile identifier.
This endpoint will add users to the specified Snap Audience Match Segment using either a single key/identifier per user. We do not accept multiple type of schemas in one request, you need to pass only one schema type with the request , but this needs to happen via a LIST
Attributes
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| id | Segment ID | R | |
| schema | List of one type of Schema | R | EMAIL_SHA256, MOBILE_AD_ID_SHA256, PHONE_SHA256 |
| data | List of hashed identifiers | R |
HTTP Request
POST https://adsapi.snapchat.com/v1/segments/{segment_id}/users
Parameters
| Parameter | Default | Description |
|---|---|---|
| segment_id | Segment ID |
Normalizing & Hashing
Each raw identifier (plain text email or mobile identifier) must be normalized before being hashed.
Normalizing Identifiers
- Normalize email addresses by trimming leading and trailing whitespace and converting all characters to lowercase before hashing
- Normalize mobile advertiser id by using all lowercase. Do not remove hyphens.
- Normalize phone numbers by including country code, and exclude any non-numeric characters such as whitespace, parentheses, ‘+’, or ‘-’
Hashing Identifiers
Hash raw identifiers with lowercase hex SHA256 format.
Adding Users (Single-Key)
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"users":[{"id": "5132209967071232", "schema":["EMAIL_SHA256"],"data":[["c3a75685a45a565954512a7f006b691b5e06c0efe6ac28bd5c09e84bbe022b55"],["5b5fbfe6a42915ca4d0f11620e76abd1a4ac621bcca95395ce3b6b11ec01bef6"]]}]}' \
"https://adsapi.snapchat.com/v1/segments/{segment_id}/users"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "57c4d34700ff0d538b8ba40ed90001737e7465616d6b6f363139000173616d2d68616f6d696e672d757365722d746573740001010c",
"users": [
{
"sub_request_status": "SUCCESS",
"user": {
"number_uploaded_users": 2
}
}
]
}
This example uses a single key/identifier per user.
Removing Users
Users can also be removed from the segment at any time. The API supports matching via email or mobile identifier.
This endpoint will remove users from the specified Snap Audience Match segment using a single key/identifier per user. We do not accept multiple type of schemas in one request, you need to pass only one schema type with the request , but this needs to happen via a LIST
Attributes
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| id | Segment ID | R | |
| schema | List of one type of Schema | R | EMAIL_SHA256, MOBILE_AD_ID_SHA256, PHONE_SHA256 |
| data | List of hashed identifiers | R |
HTTP Request
DELETE https://adsapi.snapchat.com/v1/segments/{segment_id}/users
Parameters
| Parameter | Default | Description |
|---|---|---|
| segment_id | Segment ID |
Removing Users (Single-Key)
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
curl -X DELETE \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"users":[{"id": "5132209967071232", "schema":["EMAIL_SHA256"],"data":[["c3a75685a45a565954512a7f006b691b5e06c0efe6ac28bd5c09e84bbe022b55"],["5b5fbfe6a42915ca4d0f11620e76abd1a4ac621bcca95395ce3b6b11ec01bef6"]]}]}' \
"https://adsapi.snapchat.com/v1/segments/{segment_id}/users"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "57c4d34700ff0d538b8ba40ed90001737e7465616d6b6f363139000173616d2d68616f6d696e672d757365722d746573740001010c",
"users": [
{
"sub_request_status": "SUCCESS",
"user": {
"number_uploaded_users": 2
}
}
]
}
This example uses a single key/identifier per user.
Remove All Users from a Segment
This endpoint allows you to remove all the users from a specified Snap Audience Match segment
HTTP Request
DELETE https://adsapi.snapchat.com/v1/segments/{segment_id}/all_users
Parameters
| Parameter | Default | Description |
|---|---|---|
| segment_id | Segment ID |
Remove All Users
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
curl -X DELETE \
-H "Authorization: Bearer meowmeowmeow" \
"https://adsapi.snapchat.com/v1/segments/{segment_id}/all_users"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "58af318900ff0cb66aa3a103dd0001737e616473617069736300016275696c642d61666139346564352d312d34342d3000010109",
"segments": [
{
"sub_request_status": "SUCCESS",
"segment": {
"id":"5769345128988888",
"updated_at":"2017-02-23T19:01:30.080Z",
"created_at":"2017-02-23T18:34:48.900Z",
"name":"super duper sam",
"ad_account_id":"8adc3db7-8148-4fbf-999c-8d1111111d11",
"description":"all the sams in the world",
"status":"ACTIVE",
"source_type":"FIRST_PARTY",
"retention_in_days":180,
"approximate_number_users":0
}
}
]
}
Delete an Audience Segment
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
curl -X DELETE \
-H "Authorization: Bearer meowmeowmeow" \
"https://adsapi.snapchat.com/v1/segments/{segment_id}"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5b994e4900ff02dce52463d1020001737e616473617069736300016275696c642d33346634346232622d312d3230302d32000100",
"segments": []
}
This endpoint will delete the Audience Segment with the corresponding segment id.
HTTP Request
DELETE https://adsapi.snapchat.com/v1/segments/{segment_id}
Parameters
| Parameter | Default | Description |
|---|---|---|
| segment_id | Segment ID |
SAM - Lookalikes
A lookalike segment can be created from a first-party seed Snap Audience Match Segment. The segment can be used to target or exclude a specific group of users that “behave like” the seed audience segment.
Attributes
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| ad_account_id | Ad Account ID | R | |
| creation_spec | Lookalike Creation Spec dictionary | R | (see below) |
| description | Audience Segment Description | O | |
| name | Audience Segment name | R | |
| retention_in_days | # of days to retain audience members | R | (Max 180) |
| source_type | Data source type | R | LOOKALIKE |
Creation Spec Details
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| country | ISO-2 Country Code | R | |
| seed_segment_id | Seed Audience Segment ID | R | |
| type | The type of Lookalike to be created | O | BALANCE (default), SIMILARITY, REACH |
Create an Lookalike Segment
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
curl -X POST \
-H "Authorization: Bearer meowmeowmeow" \
-H "Content-Type: application/json" \
-d '{"segments": [{"name": "lookalikes of all the sams in the world", "description": "similar to all the sams in the world", "source_type": "LOOKALIKE", "retention_in_days": 180, "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "creation_spec":{"seed_segment_id": "5677923948298240", "country": "US", "type": "REACH"}}]}' \
"https://adsapi.snapchat.com/v1/adaccounts/{ad_acount_id}/segments"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "57e18036000733c0f1abd670",
"segments": [
{
"sub_request_status": "SUCCESS",
"segment": {
"id": "5652536396611584",
"updated_at": "2016-09-20T11:30:15.448-07:00",
"created_at": "2016-09-20T11:30:15.429-07:00",
"name": "lookalikes of all the sams in the world",
"ad_account_id": "d47d2516-4f1f-46f0-a63c-31a46804c3aa",
"description": "similar to all the sams in the world",
"status": "ACTIVE",
"source_type": "LOOKALIKE",
"retention_in_days": 180,
"approximate_number_users": 0,
"creation_spec": {
"seed_segment_id": "5677923948298240",
"country": "US"
"type": "REACH"
}
}
}
]
}
This endpoint will create a Snap Audience Match Lookalike Segment within a specified ad account.
HTTP Request
POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/segments
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_account_id | Ad Account ID |
Example Targeting Specs
Targeting Spec Examples for an Ad Squad
Example 1
United States, Male+Female, All Age Ranges
You can target both Male and Female by leaving out GENDER from the targeting spec.
{
"geos": [{
"country_code": "us"
}]
}
Example 2
United States, Male, Age Groups 21-34
{
"geos": [{
"country_code": "us"
}],
"demographics": [{
"age_groups": [
"21-24",
"25-34"
],
"gender": "MALE"
}]
}
Example 3
Canada, Female, 13-20, iOS
{
"demographics": [{
"min_age": 13,
"max_age": 20,
"gender": "FEMALE"
}],
"geos": [{
"country_code": "ca"
}],
"devices": [{
"os_type": "iOS"
}]
}
Example 4
UK, Male+Female, Age 25, WIFI Only
{
"demographics": [{
"min_age": 25,
"max_age": 25
}],
"geos": [{
"country_code": "uk"
}],
"devices": [{
"connection_type": "WIFI"
}]
}
Example 5
United States - All States Except Arizona or Texas, M+F, All Ages
{
"geos": [{
"country_code": "us"
}, {
"country_code": "us",
"region_id": ["3", "44"],
"operation": "EXCLUDE"
}]
}
Example 6
United States, Female, 18-34, “Fashion & Style Gurus” OR “Film & TV Fans”
{
"demographics": [{
"gender": "FEMALE",
"age_groups": [
"18-20",
"21-24",
"25-34"
]
}],
"interests": [{
"category_id": ["SLC_7", "SLC_8"]
}],
"geos": [{
"country_code": "us"
}]
}
Example 7
United States, All genders/ages, “Comedy Fans”
{
"interests": [{
"category_id": ["SLC_36"]
}],
"geos": [{
"country_code": "us"
}]
}
Example 8
United States, Male, 18-20, member of SAM segment ID “12345”
{
"demographics": [{
"gender": "MALE",
"age_groups": [
"18-20"
]
}],
"geos": [{
"country_code": "us"
}],
"segments": [{
"segment_id": ["12345"]
}]
}
Example 9
United States, Male, 18-20, NOT a member of SAM segment ID “98765”
{
"demographics": [{
"gender": "MALE",
"age_groups": [
"18-20"
]
}],
"geos": [{
"country_code": "us"
}],
"segments": [{
"segment_id": ["98765"],
"operation": "EXCLUDE"
}]
}
Example 10
United States, AT&T
{
"geos": [{
"country_code": "us"
}],
"devices": [{
"carrier_id": ["US_ATT"]
}]
}
Example 11
United States, 21-24, (College Graduates OR Married People), Apparel Shoppers
{
"regulated_content": "false",
"demographics": [{
"age_groups": [
"21-24"
],
"advanced_demographics": [
"DLXD_100",
"DLXD_300"
]
}],
"geos": [{
"country_code": "us"
}],
"interests": [{
"category_id": ["DLXS_1"]
}]
}
Example 12
United States, metros New York or Los Angeles only
{
"geos": [{
"country_code": "us",
"metro_id": ["501", "803"]
}]
}
Example 13
USA, Female, Spanish speaking, 13-17, iOS version 10.3.2
{
"demographics": [{
"age_groups": [
"13-17"
],
"gender": "FEMALE",
"languages": ["es"]
}],
"geos": [{
"country_code": "us"
}],
"devices": [{
"os_type": "iOS",
"os_version_min": "9.0",
"os_version_max": "10.3.2"
}]
}
Example 14
Zipcode Targeting
{
"geos": [{
"country_code": "us",
"postal_code": ["90291", "90026"]
}]
}
Example 15
Device Make: All iPhone 7 plus and iPhone 6s Plus users
{
"devices": [{
"marketing_name": ["Apple/iPhone 7 Plus/", "Apple/iPhone 6s Plus/"]
}]
}
Example 16
Location Categories: Targeting Sports Arenas, Fitness Centers
{
"locations": [
{
"location_type": [
"LOI_15004", // Sports Stadiums and Arenas
"LOI_15002" // Gyms and Fitness Centers
],
,
"proximity_unit": "MILES", // Proximity in miles
"proximity": 1
}
]
}
Example 17
Location Point Radius: Targeting 500 meter radius around Nordstrom locations in Seattle/Bellevue
{
"locations": [
{
"circles": [
{
"latitude": 47.612447,
"longitude": -122.336751,
"radius": 500
},
{
"latitude": 47.617102,
"longitude": -122.203961,
"radius": 50,
"unit": "KILOMETERS"
}
],
"operation": "INCLUDE"
}
]
}
Example 18
Multi-country targeting: Targeting the US and Canada
{
"geos": [
{
"country_code": "us",
"operation": "INCLUDE"
},
{
"country_code": "ca",
"operation": "INCLUDE"
}
]
}
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"
}
]
}
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 |
Measurement
Measurement endpoints provides stats data that is updated approximately every 15 minutes.
All stats requests can be made with TOTAL, DAY, or HOUR granularity.
Request/Response Pattern
Stats endpoints have a consistent request and response pattern.
Request Pattern
Pattern:
GET /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}/stats
Example:
GET /v1/campaigns/ff869d1f-0923-4d28-8577-4c36291f0fca/stats
Response Pattern - TOTAL Granularity
Response pattern for TOTAL Granularity requests
{
"request_status": "success",
"request_id": "57ad1ad600076e58fa35e192",
"total_stats": [
{
"sub_request_status": "success",
"total_stat": {
"id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
}
]
}
Response Pattern - DAY Granularity
Response pattern for DAY Granularity requests
{
"request_status": "success",
"request_id": "57ad240f000756e8d435a6cd",
"timeseries_stats": [
{
"sub_request_status": "success",
"timeseries_stat": {
"id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
"type": "CAMPAIGN",
"granularity": "DAY",
"start_time": "2016-08-05T22:00:00.000-07:00",
"end_time": "2016-08-07T22:00:00.000-07:00",
"timeseries": [
{
"start_time": "2016-08-05T22:00:00.000-07:00",
"end_time": "2016-08-06T22:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
},
{
"start_time": "2016-08-06T22:00:00.000-07:00",
"end_time": "2016-08-07T22:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
]
}
}
]
}
Response Pattern - HOUR Granularity
Response pattern for HOUR Granularity requests
{
"request_status": "success",
"request_id": "57ad245a000e3c88bc33ea4e",
"timeseries_stats": [
{
"sub_request_status": "success",
"timeseries_stat": {
"id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
"type": "CAMPAIGN",
"granularity": "HOUR",
"start_time": "2016-08-05T18:00:00.000-07:00",
"end_time": "2016-08-06T18:00:00.000-07:00",
"timeseries": [
{
"start_time": "2016-08-05T18:00:00.000-07:00",
"end_time": "2016-08-05T19:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
},
{
"start_time": "2016-08-05T19:00:00.000-07:00",
"end_time": "2016-08-05T20:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
},
[[[ snip ]]]
{
"start_time": "2016-08-06T16:00:00.000-07:00",
"end_time": "2016-08-06T17:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
},
{
"start_time": "2016-08-06T17:00:00.000-07:00",
"end_time": "2016-08-06T18:00:00.000-07:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
]
}
}
]
}
Request Parameters
| Attribute | Description | Required | Possible Values |
|---|---|---|---|
| breakdown | Object-level breakdown | O | ad, adsquad [Only available on Campaign Stats endpoint], campaign [Only available on Ad Account Stats endpoint] |
| fields | Metrics requested (comma-separated) | O | (see table below; default: impressions,spend) |
| end_time | End Time (ISO 8601) | R* | |
| start_time | Start Time (ISO 8601) | R* | |
| granularity | Metrics granularity | R | TOTAL, DAY, HOUR, LIFETIME |
| test | Return Sample (fake) Stats | O | false (default), true |
| dimension | Insight-level breakdown | O | GEO, DEMO, INTEREST, DEVICE |
| pivot | The pivot to be used for insights breakdown | O | country, region, dma, gender, age_bucket, interest_category_id, interest_category_name, operating_system, make, model |
| swipe_up_attribution_window | Attribution window for swipe ups | O | 1_DAY, 7_DAY, 28_DAY (default) |
| view_attribution_window | Attribution window for views | O | 1_HOUR, 3_HOUR, 6_HOUR, 1_DAY (default), 7_DAY, 28_DAY |
| position_stats | Position metric breakdown for Snap Ads within a Story Ad | O | true |
| omit_empty | Omits records with zero data for all metrics for a given date/entity. If there is data for any metric for a given date/entity, all metrics for that date/entity are returned | O | false (default), true |
| conversion_source_types | Conversion source breakout by platform | O | web, app, total |
| limit | The limit parameter specifies how many entities should be returned per page | O | integer, max 200 |
Response Parameters
| Attribute | Description |
|---|---|
| finalized_data_end_time | This defines the time up until when reporting metrics are finalized. You can query for all metrics before this time including uniques and reach and they will have the final numbers. For any time after the finalized_data_end_time the metrics are still undergoing de-duplication and finalization and may change accordingly. |
| paging | If you are using pagination the paging attribute will contain a next_link attribute which holds the API call to fetch the next page. |
Pagination
For calls that fetch stats for many entities we recommend that you use pagination. The limit parameter specifies how many entities should be returned per page. The maximum pagination limit is 200.
The returned result will contain a paging attribute, this in turn holds a next_link attribute which holds the API call to fetch the next page. Paginated calls are rdered by time of creation, non-paginated calls are unsorted.
Core Metrics
The following metrics are available for all Snap Ads.
| Field Name | Description |
|---|---|
| impressions | Impression Count |
| swipes | Swipe-Up Count |
| view_time_millis | Use screen_time_millis instead. Total Time Spent on top Snap Ad (milliseconds) |
| screen_time_millis | Total Time Spent on top Snap Ad (milliseconds) |
| quartile_1 | Video Views to 25% |
| quartile_2 | Video Views to 50% |
| quartile_3 | Video Views to 75% |
| view_completion | Video Views to completion |
| spend | Amount Spent (micro-currency) |
| video_views | The total number of impressions that meet the qualifying video view criteria of at least 2 seconds of consecutive watch time or a swipe up action on the Top Snap |
Additional Metrics
The following metrics are available for specific Snap Ads with Attachments and/or at TOTAL granularity. Italicized metrics are available in the real-time stats pipeline. Non-italicized are available in real-time for the granularities DAY and HOUR, for LIFETIME granularity the data is only accessible as finalized data, available after 48-72 hours.
| Field Name | Snap Ad Types | Description |
|---|---|---|
| android_installs | APP_INSTALL | # of Android App Installs |
| attachment_avg_view_time_millis | Any Attachment | Average Attachment View Time (milli-seconds) |
| attachment_frequency | Any Attachment | Average # of Attachment Views per User Reached |
| attachment_quartile_1 | LONGFORM_VIDEO | Long Form Video Views to 25% |
| attachment_quartile_2 | LONGFORM_VIDEO | Long Form Video Views to 50% |
| attachment_quartile_3 | LONGFORM_VIDEO | Long Form Video Views to 75% |
| attachment_total_view_time_millis | Any Attachment | Total Attachment View Time (milli-seconds) |
| attachment_uniques | Any Attachment | # of unique attachment impressions |
| attachment_view_completion | LONGFORM_VIDEO | Long Form Video Views to completion |
| attachment_video_views | LONGFORM_VIDEO | Long Form Video Attachment Views, viewed for at least 10 consecutive seconds or reached 97% of the Long Form Video duration |
| avg_view_time_millis | Any | Use avg_screen_time_millis instead. Average Top Snap view time per User Reached |
| avg_screen_time_millis | Any | Average Top Snap view time across all impressions |
| frequency | Any | Average # of Impressions per User Reached |
| ios_installs | APP_INSTALL | # of iOS App Installs |
| swipe_up_percent | Any Attachment | % of Impressions that Swiped-Up |
| total_installs | APP_INSTALL | Total # of App Installs |
| uniques | Any | # of unique impressions |
| video_views_time_based | Any | The total number of impressions that meet the qualifying video view criteria of at least 2 seconds, not including swipe ups |
| video_views_15s | Any | The total number of impressions that meet the qualifying video view criteria of at least 15 seconds, or 97% completion if it’s shorter than 15 seconds, or a swipe up action on the ad |
| story_opens | STORY | # of times users tapped on the ad tile in the feed to view the Story Ad |
| story_completes | STORY | # of times users viewed through to the last Snap of your Story Ad |
| position_impressions | STORY | # the impression number for this story ad position |
| position_uniques | STORY | # the unique viewer numbers for this story ad position |
| position_frequency | STORY | # the frequency for this story ad position |
| position_screen_time_millis | STORY | # the total view time in milliseconds for this story ad position |
| position_swipe_up_percent | STORY | # the swipe up rate for this story ad position |
| avg_position_screen_time_millis | STORY | # the average view time for this story ad position |
| shares | LENS, AD_TO_LENS, FILTER | # of times lens/filter was shared in a Chat or Story |
| saves | LENS, AD_TO_LENS, FILTER | # of times lens/filter was saved to Memories |
Conversion Event Stats
The following conversion event metrics are available for ads that have been setup to track conversions through Snap Pixel.
| Fields | Granularity | Description |
|---|---|---|
| conversion_purchases | Any | # of attributed “PURCHASE” conversion events |
| conversion_purchases_value | Any | Value of attributed “PURCHASE” conversion events (microcurrency in Ad Account’s currency) |
| conversion_save | Any | # of attributed “SAVE” conversion events |
| conversion_start_checkout | Any | # of attributed “START_CHECKOUT” conversion events |
| conversion_add_cart | Any | # of attributed “ADD_CART” conversion events |
| conversion_view_content | Any | # of attributed “VIEW_CONTENT” conversion events |
| conversion_add_billing | Any | # of attributed “ADD_BILLING” conversion events |
| conversion_sign_ups | Any | # of attributed “SIGN_UP” conversion events |
| conversion_searches | Any | # of attributed “SEARCH” conversion events |
| conversion_level_completes | Any | # of attributed “LEVEL_COMPLETE” conversion events |
| conversion_app_opens | Any | # of attributed “APP_OPEN” conversion events |
| conversion_page_views | Any | # of attributed “PAGE_VIEW” conversion events |
| conversion_subscribe | Any | # of attributed “SUBSCRIBE” conversion events |
| conversion_ad_click | Any | # of attributed “AD_CLICK” conversion events |
| conversion_ad_view | Any | # of attributed “AD_VIEW” conversion events |
| conversion_complete_tutorial | Any | # of attributed “COMPLETE_TUTORIAL” conversion events |
| conversion_invite | Any | # of attributed “INVITE” conversion events |
| conversion_login | Any | # of attributed “LOGIN” conversion events |
| conversion_share | Any | # of attributed “SHARE” conversion events |
| conversion_reserve | Any | # of attributed “RESERVE” conversion events |
| conversion_achievement_unlocked | Any | # of attributed “ACHIEVEMENT_UNLOCKED” conversion events |
| conversion_add_to_wishlist | Any | # of attributed “ADD_TO_WISHLIST” conversion events |
| conversion_spend_credits | Any | # of attributed “SPENT_CREDITS” conversion events |
| conversion_rate | Any | # of attributed “RATE” conversion events |
| conversion_start_trial | Any | # of attributed “START_TRIAL” conversion events |
| conversion_list_view | Any | # of attributed “LIST_VIEW” conversion events |
| custom_event_1 | Any | # of attributed “CUSTOM_EVENT_1” conversion events |
| custom_event_2 | Any | # of attributed “CUSTOM_EVENT_2” conversion events |
| custom_event_3 | Any | # of attributed “CUSTOM_EVENT_3” conversion events |
| custom_event_4 | Any | # of attributed “CUSTOM_EVENT_4” conversion events |
| custom_event_5 | Any | # of attributed “CUSTOM_EVENT_5” conversion events |
Conversion breakout
The parameter conversion_source_types provides breakout of conversions based on where the conversions occurred.
| Parameter | Metric | Description |
|---|---|---|
| total | conversion_purchases | All purchase events |
| web | conversion_purchases_web | Purchases from a web browser |
| app | conversion_purchases_app | Purchases from an app |
Conversion breakout example
curl "https://adsapi.snapchat.com/v1/adsquads/0b7e62aa-a8bc-48f6-a410-c65eee9cc9a7/stats?fields=conversion_purchases,impressions,spend,swipe_up_percent,swipes,view_completion&conversion_source_types=total,web,app"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5de004c100ff03ea1eeb1050430001737e616473617069736300016275696c642d61663733336133322d312d3330372d3000010103",
"total_stats": [
{
"sub_request_status": "SUCCESS",
"total_stat": {
"id": "0b7e62aa-a8bc-48f6-a410-c65eee9cc9a7",
"type": "AD_SQUAD",
"granularity": "TOTAL",
"stats": {
"impressions": 2337371,
"swipes": 14745,
"view_completion": 69506,
"swipe_up_percent": 0.0063,
"spend": 3449137066,
"conversion_purchases": 1141,
"conversion_purchases_web": 659,
"conversion_purchases_app": 482
},
"finalized_data_end_time": "2019-11-28T02:00:00.000-08:00"
}
}
]
}
This parameter breaks down conversions based on where the conversion occurred.
Omitting empty records example
curl "https://adsapi.snapchat.com/v1/campaigns/9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37/stats?granularity=DAY&start_time=2019-11-12T00%3A00%3A00-08%3A00&end_time=2019-11-16T00%3A00%3A00-08%3A00&&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&fields=conversion_purchases,impressions,swipes,spend&conversion_source_types=web,app,total"
-H "Authorization: Bearer meowmeowmeow"
An example not using omit_empty, this returns several day entries with no metrics.
{
"request_status": "SUCCESS",
"request_id": "5de0f99900ff02f49ea1540d1c0001737e616473617069736300016275696c642d61663733336133322d312d3330372d300001013c",
"timeseries_stats": [
{
"sub_request_status": "SUCCESS",
"timeseries_stat": {
"id": "9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37",
"type": "CAMPAIGN",
"granularity": "DAY",
"swipe_up_attribution_window": "28_DAY",
"view_attribution_window": "7_DAY",
"start_time": "2019-11-12T00:00:00.000-08:00",
"end_time": "2019-11-16T00:00:00.000-08:00",
"finalized_data_end_time": "2019-11-28T00:00:00.000-08:00",
"timeseries": [
{
"start_time": "2019-11-12T00:00:00.000-08:00",
"end_time": "2019-11-13T00:00:00.000-08:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"conversion_purchases": 0,
"conversion_purchases_web": 0,
"conversion_purchases_app": 0
}
},
{
"start_time": "2019-11-13T00:00:00.000-08:00",
"end_time": "2019-11-14T00:00:00.000-08:00",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"conversion_purchases": 0,
"conversion_purchases_web": 0,
"conversion_purchases_app": 0
}
},
{
"start_time": "2019-11-14T00:00:00.000-08:00",
"end_time": "2019-11-15T00:00:00.000-08:00",
"stats": {
"impressions": 599725,
"swipes": 3790,
"spend": 594736665,
"conversion_purchases": 62,
"conversion_purchases_web": 42,
"conversion_purchases_app": 20
}
},
{
"start_time": "2019-11-15T00:00:00.000-08:00",
"end_time": "2019-11-16T00:00:00.000-08:00",
"stats": {
"impressions": 670692,
"swipes": 4189,
"spend": 716170632,
"conversion_purchases": 125,
"conversion_purchases_web": 82,
"conversion_purchases_app": 43
}
}
]
}
}
]
}
curl "https://adsapi.snapchat.com/v1/campaigns/9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37/stats?granularity=DAY&start_time=2019-11-12T00%3A00%3A00-08%3A00&end_time=2019-11-16T00%3A00%3A00-08%3A00&&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&fields=conversion_purchases,impressions,swipes,spend&conversion_source_types=web,app,total&omit_empty=true"
-H "Authorization: Bearer meowmeowmeow"
An example using omit_empty, this returns only day entries with metrics:
{
"request_status": "SUCCESS",
"request_id": "5de0fa4900ff0942bb5374cb8f0001737e616473617069736300016275696c642d61663733336133322d312d3330372d300001014d",
"timeseries_stats": [
{
"sub_request_status": "SUCCESS",
"timeseries_stat": {
"id": "9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37",
"type": "CAMPAIGN",
"granularity": "DAY",
"swipe_up_attribution_window": "28_DAY",
"view_attribution_window": "7_DAY",
"start_time": "2019-11-12T00:00:00.000-08:00",
"end_time": "2019-11-16T00:00:00.000-08:00",
"finalized_data_end_time": "2019-11-28T00:00:00.000-08:00",
"timeseries": [
{
"start_time": "2019-11-14T00:00:00.000-08:00",
"end_time": "2019-11-15T00:00:00.000-08:00",
"stats": {
"impressions": 599725,
"swipes": 3790,
"spend": 594736665,
"conversion_purchases": 62,
"conversion_purchases_web": 42,
"conversion_purchases_app": 20
}
},
{
"start_time": "2019-11-15T00:00:00.000-08:00",
"end_time": "2019-11-16T00:00:00.000-08:00",
"stats": {
"impressions": 670692,
"swipes": 4189,
"spend": 716170632,
"conversion_purchases": 125,
"conversion_purchases_web": 82,
"conversion_purchases_app": 43
}
}
]
}
}
]
}
The parameter omit_empty will omit records with zero data for all metrics for a given date/entity. If there is data for any metric for a given date/entity, all metrics for that date/entity are returned.
The omit_empty parameter allows developers to speed up calculations as empty entries can be removed before the calculation is made, it also allows developers to structure an app to avoid displaying empty entries in the UI.
Metrics and supported granularities
| Metric | Real time | HOUR | DAY | TOTAL | LIFETIME |
|---|---|---|---|---|---|
| android_installs | YES | YES. time must be of hour boundary, start_time and end_time within 7 days | YES. time must be of day boundary, start_time and end_time within 31 days | YES. time must be of day boundary, start_time and end_time must be both specified, or neither. In the latter case, it combines lifetime and realtime stats. | YES. no start_time, end_time can be specified. |
| attachment_avg_view_time_millis | |||||
| attachment_impressions | |||||
| attachment_quartile_1 | |||||
| attachment_quartile_2 | |||||
| attachment_quartile_3 | |||||
| attachment_total_view_time_millis | |||||
| attachment_view_completion | |||||
| avg_screen_time_millis | |||||
| avg_view_time_millis | |||||
| impressions | |||||
| ios_installs | |||||
| quartile_1 | |||||
| quartile_2 | |||||
| quartile_3 | |||||
| screen_time_millis | |||||
| spend | |||||
| swipe_up_percent | |||||
| swipes | |||||
| total_installs | |||||
| video_views | |||||
| video_views_time_based | |||||
| video_views_15s | |||||
| view_completion | |||||
| view_time_millis | |||||
| conversion_purchases | |||||
| conversion_purchases_value | |||||
| conversion_save | |||||
| conversion_start_checkout | |||||
| conversion_add_cart | |||||
| conversion_view_content | |||||
| conversion_add_billing | |||||
| conversion_signups | |||||
| conversion_searches | |||||
| conversion_level_completes | |||||
| conversion_app_opens | |||||
| conversion_page_views | |||||
| conversion_subscribe | |||||
| conversion_ad_click | |||||
| conversion_ad_view | |||||
| conversion_complete_tutorial | |||||
| conversion_invite | |||||
| conversion_login | |||||
| conversion_share | |||||
| conversion_reserve | |||||
| conversion_achievement_unlocked | |||||
| conversion_add_to_wishlist | |||||
| conversion_spend_credits | |||||
| conversion_rate | |||||
| conversion_start_trial | |||||
| conversion_list_view | |||||
| custom_event_1 | |||||
| custom_event_2 | |||||
| custom_event_3 | |||||
| custom_event_4 | |||||
| custom_event_5 | |||||
| attachment_frequency | YES | YES | YES | Not supported. Use LIFETIME | |
| attachment_uniques | |||||
| frequency | |||||
| uniques |
Example for All Metrics
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get('123').stats()
curl -H "Authorization: Bearer meowmeow" \
"https://adsapi.snapchat.com/v1/campaigns/2bbaa6e3-4ddb-4358-9efe-48334952f4aa/stats?breakdown=adsquad&fields=android_installs,avg_screen_time_millis,attachment_frequency,attachment_quartile_1,attachment_quartile_2,attachment_quartile_3,attachment_total_view_time_millis,attachment_uniques,attachment_view_completion,frequency,impressions,ios_installs,quartile_1,quartile_2,quartile_3,spend,swipe_up_percent,swipes,total_installs,uniques,view_completion,screen_time_millis&granularity=DAY&start_time=2016-10-24T07:00:00.000-00:00&end_time=2016-10-26T07:00:00.000-00:00"
{
"request_status": "SUCCESS",
"request_id": "5813ccf400ff07b016a837c09f0001737e616473617069736300016275696c642d65373832323966352d73746174732d322d7465737400010133",
"timeseries_stats": [
{
"sub_request_status": "SUCCESS",
"timeseries_stat": {
"id": "2bbaa6e3-4ddb-4358-9efe-48334952f4aa",
"type": "CAMPAIGN",
"start_time": "2016-10-24T07:00:00.000Z",
"end_time": "2016-10-26T07:00:00.000Z",
"breakdown_stats": {
"adsquad": [
{
"id": "134aeb99-6552-4f1d-b7a6-82b9813fd079",
"type": "AD_SQUAD",
"granularity": "DAY",
"start_time": "2016-10-24T07:00:00.000Z",
"end_time": "2016-10-26T07:00:00.000Z",
"timeseries": [
{
"start_time": "2016-10-24T07:00:00.000Z",
"end_time": "2016-10-25T07:00:00.000Z",
"stats": {
"impressions": 18294,
"swipes": 0,
"quartile_1": 7489,
"quartile_2": 2595,
"quartile_3": 1964,
"view_completion": 1635,
"attachment_quartile_1": 0,
"attachment_quartile_2": 0,
"attachment_quartile_3": 0,
"attachment_view_completion": 0,
"attachment_total_view_time_millis": 0,
"frequency": 1.0014,
"avg_screen_time_millis": 1832,
"swipe_up_percent": 0,
"attachment_frequency": 0,
"attachment_avg_view_time_millis": 0,
"uniques": 18268,
"attachment_uniques": 0,
"ios_installs": 0,
"android_installs": 0,
"total_installs": 0,
"spend": 144213617,
"screen_time_millis": 33876700
}
},
{
"start_time": "2016-10-25T07:00:00.000Z",
"end_time": "2016-10-26T07:00:00.000Z",
"stats": {
"impressions": 15377,
"swipes": 0,
"quartile_1": 6345,
"quartile_2": 2185,
"quartile_3": 1596,
"view_completion": 1324,
"attachment_quartile_1": 0,
"attachment_quartile_2": 0,
"attachment_quartile_3": 0,
"attachment_view_completion": 0,
"attachment_total_view_time_millis": 0,
"frequency": 1.0011,
"avg_screen_time_millis": 1828,
"swipe_up_percent": 0,
"attachment_frequency": 0,
"attachment_avg_view_time_millis": 0,
"uniques": 15360,
"attachment_uniques": 0,
"ios_installs": 0,
"android_installs": 0,
"total_installs": 0,
"spend": 120978178,
"screen_time_millis": 28547600
}
}
]
}
}
Get Ad Account Stats
curl "https://adsapi.snapchat.com/v1/adaccounts/22335ba6-7558-4100-9663-baca7adff5f2/stats?granularity=TOTAL&fields=spend" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b24d9c00ff0d85622341e7c60001737e616473617069736300016275676c642b34326313636139312d332d31312d390001010d",
"total_stats": [
{
"sub_request_status": "success",
"total_stat": {
"id": "22335ba6-7558-4100-9663-baca7adff5f2",
"type": "AD_ACCOUNT",
"granularity": "TOTAL",
"stats": {
"spend": 89196290
},
"finalized_data_end_time": "2019-08-29T03:00:00.000-07:00"
}
}
]
}
This endpoint retrieves the spend metric for the specified Ad Account, the spend metric is the only metric available for the ad account entity.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/stats
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad_account_id | Ad Account ID |
Get Campaign Stats
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get('123').stats()
curl "https://adsapi.snapchat.com/v1/campaigns/92e1c28a-a331-45b4-8c26-fd3e0eea8c39/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend" \
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b24d9c00ff0d85622341e7c60001737e616473617069736300016275696c642d34326333636139312d312d31312d390001010d",
"total_stats": [
{
"sub_request_status": "success",
"total_stat": {
"id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
}
]
}
This endpoint retrieves stats for the specified Campaign.
HTTP Request
GET https://adsapi.snapchat.com/v1/campaigns/{campaign-id}/stats
Parameters
| Parameter | Default | Description |
|---|---|---|
| campaign-id | Campaign ID |
Get Ad Squad Stats
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.adsquads.get('123').stats()
curl "https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b24e5200ff0225cdf221e6c90001737e616473617069736300016275696c642d34326333636139312d312d31312d3900010106",
"total_stats": [
{
"sub_request_status": "success",
"total_stat": {
"id": "23995202-bfbc-45a0-9702-dd6841af52fe",
"type": "AD_SQUAD",
"granularity": "TOTAL",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
}
]
}
This endpoint retrieves stats for the specified Ad Squad.
HTTP Request
GET https://adsapi.snapchat.com/v1/adsquads/{adsquad-id}/stats
Parameters
| Parameter | Default | Description |
|---|---|---|
| adsquad-id | Ad Squad ID |
Get Ad Stats
import snapchat_ads_api
api = snapchat_ads_api.authorize('meowmeowmeow')
api.ads.get('123').stats()
curl "https://adsapi.snapchat.com/v1/ads/e8d6217f-32ab-400f-9e54-39a86a7963e4/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "success",
"request_id": "57b24ec400ff0b0a2104182f430001737e616473617069736300016275696c642d34326333636139312d312d31312d390001010f",
"total_stats": [
{
"sub_request_status": "success",
"total_stat": {
"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
"type": "AD",
"granularity": "TOTAL",
"stats": {
"impressions": 0,
"swipes": 0,
"spend": 0,
"quartile_1": 0,
"quartile_2": 0,
"quartile_3": 0,
"view_completion": 0,
"screen_time_millis": 0
}
}
}
]
}
This endpoint retrieves stats for the specified Ad.
HTTP Request
GET https://adsapi.snapchat.com/v1/ads/{ad-id}/stats
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad-id | Ad ID |
Reporting Insights and Dimensions
Delivery Insights can help you understand who viewed, engaged, and took action on your ads. These insights across demographic, location, device, and interest categories can help inform optimization and increase overall campaign efficiency. Insights can be pulled for specific campaigns, ad squads, or ads; insights can also use breakdowns for multiple campaigns, ad squads, or ads at once.
Delivery Insights are estimated to protect user privacy. They are meant to provide directional guidance on audience performance.
Delivery Insights are only available from January 1st, 2020. DAY, TOTAL, and LIFETIME granularities are supported.
Dimensions
You can get reporting insights based on different geographic, demographic, interest-based, and device-based dimensions. You can only query one dimension at a time unless you are querying age & gender which may be combined.
Using the report_dimension query string parameter you can see Snapchat metrics based on a number of new dimensions
| Category | API Dimension (report_dimension) | Conditions |
|---|---|---|
| Geo | country | Metrics broken down by ISO country code |
| region | US-Only. Metrics broken down by two letter state abbreviation | |
| dma | US-Only. Metrics broken down by DMA numeric code | |
| Demographic | gender | Metrics broken down by gender; may be combined with age as gender,age |
| age | Metrics broken down by age buckets; may be combined with gender as age,gender | |
| User Interest | lifestyle_category | Snapchat User Lifestyle Interest |
| Device | os | Device Operating System |
| make | Device Make (e.g., Apple, Samsung) |
Metrics
You may pass these metrics as a comma separated list for the fields query parameter. Conversion metrics support attribution windows, swipe/view variants, and value metrics in local microcents.
| Metric | API field | Description |
|---|---|---|
| Paid Impressions | impressions | Impression Count |
| Swipe Ups | swipes | Swipe-Up Count |
| 25% Quartile | quartile_1 | Video Views to 25% |
| 50% Quartile | quartile_2 | Video Views to 50% |
| 75% Quartile | quartile_3 | Video Views to 75% |
| Completions | view_completion | Video Views to completion |
| Spend | spend | Amount Spent (micro-currency) |
| Video Views | video_views | The total number of impressions that meet the qualifying video view criteria of at least 2 seconds of consecutive watch time or a swipe up action on the Top Snap |
| 25% Attachment Quartile | attachment_quartile_1 | Long Form Video Views to 25% |
| 50% Attachment Quartile | attachment_quartile_2 | Long Form Video Views to 50% |
| 75% Attachment Quartile | attachment_quartile_3 | Long Form Video Views to 75% |
| Attachment Completions | attachment_view_completion | Long Form Video Views to completion |
| Attachment View Time | attachment_total_view_time_millis | Total Attachment View Time (milli-seconds) |
| Attachment Video Views | attachment_video_views | Long Form Video Attachment Views |
| Story Opens | story_opens | # of times users tapped on the ad tile in the feed to view the Story Ad |
| Story Completes | story_completes | # of times users viewed through to the last Snap of your Story Ad |
| Shares | shares | # of times lens/filter was shared in a Chat or Story |
| Saves | saves | # of times lens/filter was saved to Memories |
| Installs | total_installs | Total # of App Installs |
| Purchases | conversion_purchases | # of attributed “PURCHASE” conversion events |
| Purchase Value | conversion_purchases_value | Value of attributed “PURCHASE” conversion events (microcurrency in Ad Account’s currency) |
| Saves | conversion_save | # of attributed “SAVE” conversion events |
| Start Checkout | conversion_start_checkout | # of attributed “START_CHECKOUT” conversion events |
| Add To Cart | conversion_add_cart | # of attributed “ADD_CART” conversion events |
| View Content | conversion_view_content | # of attributed “VIEW_CONTENT” conversion events |
| Add Billing | conversion_add_billing | # of attributed “ADD_BILLING” conversion events |
| Sign Ups | conversion_sign_ups | # of attributed “SIGN_UP” conversion events |
| Searches | conversion_searches | # of attributed “SEARCH” conversion events |
| Level Completes | conversion_level_completes | # of attributed “LEVEL_COMPLETE” conversion events |
| App Opens | conversion_app_opens | # of attributed “APP_OPEN” conversion events |
| Page Views | conversion_page_views | # of attributed “PAGE_VIEW” conversion events |
Insights by GEO
curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/stats/?granularity=TOTAL&breakdown=campaign&fields=impressions,swipes,conversion_purchases&report_dimension=country&start_time=2020-01-25T00:00:00-08:00&end_time=2020-01-26T00:00:00-08:00&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e6bee5400ff0aaf11217b24900001737e616473617069736300016275696c642d31636430373832652d312d3333342d3000010128",
"total_stats": [
{
"sub_request_status": "SUCCESS",
"total_stat": {
"id": "22225ba6-7559-4000-9663-bace8adff5f2",
"type": "AD_ACCOUNT",
"granularity": "TOTAL",
"swipe_up_attribution_window": "28_DAY",
"view_attribution_window": "1_DAY",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-26T00:00:00.000-08:00",
"finalized_data_end_time": "2020-03-13T00:00:00.000-07:00",
"breakdown_stats": {
"campaign": [
{
"id": "88821981-14be-4315-9832-278b27004d68",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-26T00:00:00.000-08:00",
"dimension_stats": [
{
"impressions": 23433,
"swipes": 141,
"country": "au",
"conversion_purchases": 3
}
]
},
{
"id": "8079bbff-8a7b-4548-8556-d726461da248",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-26T00:00:00.000-08:00",
"dimension_stats": [
{
"impressions": 19970,
"swipes": 488,
"country": "us",
"conversion_purchases": 4
}
]
},
{
"id": "828f739c-7f32-4013-9a92-58c6495e9438",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-26T00:00:00.000-08:00",
"dimension_stats": [
{
"impressions": 46068,
"swipes": 74,
"country": "fr",
"conversion_purchases": 5
}
]
}
]
},
"split_results": []
}
}
]
}
This retrieves insights for country broken down to Campaign level using report_dimension=country.
HTTP Request
GET https://adsapi.snapchat.com/v1/adaccounts/{ad-account-id}/stats
Parameters
| Parameter | Default | Description |
|---|---|---|
| ad-account-id | Ad ID | |
| report_dimension | The desired Report Dimension |
Insights by DEMO
curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/stats/?granularity=TOTAL&breakdown=campaign&fields=impressions,swipes,conversion_purchases&report_dimension=gender,age&start_time=2020-01-25T00:00:00-08:00&end_time=2020-01-28T00:00:00-08:00&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY"
-H "Authorization: Bearer meowmeowmeow"
The above command returns JSON structured like this:
{
"request_status": "SUCCESS",
"request_id": "5e6bf19f00ff068ca7c50849650001737e616473617069736300016275696c642d31636430373832652d312d3333342d3000010121",
"total_stats": [
{
"sub_request_status": "SUCCESS",
"total_stat": {
"id": "22225ba6-7559-4000-9663-bace8adff5f2",
"type": "AD_ACCOUNT",
"granularity": "TOTAL",
"swipe_up_attribution_window": "28_DAY",
"view_attribution_window": "1_DAY",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-28T00:00:00.000-08:00",
"finalized_data_end_time": "2020-03-13T00:00:00.000-07:00",
"breakdown_stats": {
"campaign": [
{
"id": "88921981-14be-4315-9832-278b27004d68",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-28T00:00:00.000-08:00",
"dimension_stats": [
{
"impressions": 18719,
"swipes": 63,
"age_bucket": "18-20",
"gender": "male",
"conversion_purchases": 1
},
{
"impressions": 12184,
"swipes": 37,
"age_bucket": "21-24",
"gender": "male",
"conversion_purchases": 0
},
{
"impressions": 25197,
"swipes": 113,
"age_bucket": "25-34",
"gender": "male",
"conversion_purchases": 1
},
{
"impressions": 12363,
"swipes": 147,
"age_bucket": "35+",
"gender": "male",
"conversion_purchases": 1
}
]
},
{
"id": "82d35332-00e3-4414-a125-922053d2c358",
"type": "CAMPAIGN",
"granularity": "TOTAL",
"start_time": "2020-01-25T00:00:00.000-08:00",
"end_time": "2020-01-28T00:00:00.000-08:00",
"dimension_stats": [
{
"impressions"