NAV Navbar
Snapchat ghost

Marketing API

cURL python

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

New bid_strategy attribute replaces auto_bid and target_bid

Deprecation Schedule
Announcement Date: March 20th, 2020
Sunset Date: June 20th, 2020

Deprecation of placement in favour of placement_v2

Deprecation Schedule
Announcement Date: March 20th, 2020
Sunset Date: June 20th, 2020

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:

  1. One or more Funding Sources. A Funding Source references the Organization’s line of credit or a portion thereof.
  2. 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:

  1. One or more ad Campaigns (and all of its children).
  2. One or more Media objects. Media are the most atomic objects - a single video file is a Media object.
  3. 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.
  4. 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!

  1. Snap Inc. creates your Organization, Funding Source, and Ad Account.
  2. Create a Media object.
  3. Upload the video file to the Media object.
  4. Create a Creative using the Media object ID.
  5. Create a Campaign.
  6. Create an Ad Squad. Set the bid, objective, and targeting at this stage.
  7. Create an Ad referencing the Creative object ID.
  8. 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;

Parameter Required Description
limit O integer, min 50, max 1000

Pattern:

GET /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}?limit={value between 50 - 1000}

Example:

GET /v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/ads?limit=50

Entity Request Limits

Whilst the Create and Update endpoints support the creation/editing of several objects in a single POST request there is a limit to the number of entities that can be created/edited in a single request.

Entity type Create/Update limit per Request
Creative 10
Media 10
Organization 15
Ad Account 15
Segments 15
Campaign 30
Ad Squad 30
Ad 30

Create One or More Entities

The Create endpoints support bulk creation, meaning you can create several objects at the same time as long as they share the same parent. For example, you can create muliple Campaigns within a single Ad Account in a single POST request.

Pattern:

POST /v1/{PLURAL_PARENT_ENTITY_NAME}/{PARENT_ENTITY_ID}/{PLURAL_ENTITY_NAME}

Example:

POST /v1/adaccounts/ff869d1f-0923-4d28-8577-4c36291f0fca/campaigns

Update One or More Entities

The Update endpoints support bulk update, meaning you can update several objects at the same time as long as they share the same parent. For example, you can update muliple Campaigns within a single Ad Account in a single PUT request.

Pattern:

PUT /v1/{PLURAL_PARENT_ENTITY_NAME}/{PARENT_ENTITY_ID}/{PLURAL_ENTITY_NAME}

Example:

PUT /v1/adaccounts/ff869d1f-0923-4d28-8577-4c36291f0fca/campaigns

Delete a Single Entity

Pattern:

DELETE /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}

Example:

DELETE /v1/campaigns/0be21d8a-2720-4668-9576-0fa566a6ff55

Monetary Values

All Monetary Values are presented in micro-currency, wherein 1.00 in the Ad Account’s currency (USD, CAD, GBP, EUR, AUD) is equal to 1,000,000 micro-currency.

Examples

Currency Value Micro-Currency Value
$1.00 1000000
$0.50 500000
$50,000 50000000000
$123.45 123450000

Authentication

To authorize, use this code:

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: Bearer meowmeowmeow"

Make sure to replace meowmeowmeow with your access token.

Snapchat Marketing API uses access tokens to control access and authenticate requests.

The access token should be included in all API requests to the server in the Authorization header like so:

Authorization: Bearer meowmeowmeow

Obtain App Credentials

OAuth apps are set up in the ‘Business Details’ section in Snap Business Manager, you need to be an Organization Admin to see the app dashboard, when setting up an app you need to agree to the Snap Marketing API terms and the Snap Audience Match Terms.

When setting up an OAuth app you need to provide a name and a redirect_uri, the redirect_uri is where the user is redirected upon authentication.

Depending on your objectives you may want the redirect_uri to simply display the code value so that you can copy it and use it in an app built elsewhere to generate tokens, or you may choose to build the entry point for your entire app on the redirect_uri so that it may read the code value automatically upon user authentication.

Upon creation of an app you will be presented with client_id and client_secret, the secret is only ever displayed at the point of creation so you will need to keep track of this.

User Auth via Redirect

Direct the user’s browser to the Authorization URL. They will be presented with a login screen and confirmation prompt to grant access to their account.

GET https://accounts.snapchat.com/login/oauth2/authorize

Parameters

Parameter Default Description
client_id Client ID
redirect_uri URLEncoded Redirect URI (must match URI on OAuth App)
response_type Must be “code”
scope Must be “snapchat-marketing-api”
state Optional; Will be passed through in redirect; Used for verification of request authenticity

Receive the Redirected User

After the user approves or cancels the authorization, they will be redirected to your Redirect URI. If the user approved the request to access their account, there will be 2 query parameters passed along to your Redirect URI.

Parameters

Parameter Default Description
code One-time use code that can be exchanged for an Access Token and a Refresh Token
state Optional; Used for verification of request authenticity

Generate an Access Token

In order to access the API you must have an Access Token. To generate an Access Token you must first receive a Code from a successful user OAuth Web Redirect Flow described above. Once you have the Code you can exchange it for a short-lived Access Token and long-lived Refresh Token. The Access Token is valid for 1800 seconds = 30 minutes.

# With shell, you can just pass the correct header with each request
curl -X POST \
  -d "grant_type=authorization_code" \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}" \
  -d "code={code}" \
  -d "redirect_uri={redirect_uri}"
  https://accounts.snapchat.com/login/oauth2/access_token

The above command returns JSON structured like this:

{
  "expires_in": 1800,
  "token_type": "Bearer",
  "refresh_token": "32eb12f037712a6b60404d6d9c170ee9ae4d5b9936c73dd03c23fffff1213cb3",
  "access_token": "0.MGQCxyz123"
}

HTTP Request

POST https://accounts.snapchat.com/login/oauth2/access_token

Parameters

Parameter Default Description
client_id Client ID
client_secret Client Secret
code One-time Use Code from User Redirect or Refresh Token
grant_type “authorization_code”
redirect_uri URLEncoded Redirect URI. Required when grant_type=authorization_code. Must match redirect_uri from the previous /authorize call

Refresh the Access Token

Access Tokens are short-lived. When you receive a 401 token expired error, you should use your Refresh Token to generate a new Access Token and retry the request. Many standard OAuth2 libraries can handle this expiration-retry pattern for you.

# With shell, you can just pass the correct header with each request
curl -X POST \
  -d "refresh_token={refresh_token}" \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}"  \
  -d "grant_type=refresh_token"  \
  https://accounts.snapchat.com/login/oauth2/access_token

The above command returns JSON structured like this:

{
    "access_token": "0.MGQCxyz123",
    "token_type": "Bearer",
    "expires_in": 1800,
    "refresh_token": "32eb12f037712a6b60404d6d9c170ee9ae4d5b9936c73dd03c23fffff1213cb3",
    "scope": "snapchat-marketing-api"
}

HTTP Request

POST https://accounts.snapchat.com/login/oauth2/access_token

Parameters

Parameter Default Description
client_id Client ID
client_secret Client Secret
grant_type “refresh_token”
refresh_token The refresh token you received when generating your first access token

Full Web Flow Example

1. Open the authorize link in a browser: 
https://accounts.snapchat.com/login/oauth2/authorize?response_type=code&client_id={client_id}&redirect_uri={redirect_uri}&scope=snapchat-marketing-api&state=wmKkg0TWgppW8PTBZ20sldUmF7hwvU

2. Login & Authorize via UI

3. Locate "code" query parameter in the redirect

4. Exchange code for access token + refresh token
curl -X POST \
  -d "code={one_time_use_code}" \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}"  \
  -d "grant_type=authorization_code"  \
  -d "redirect_uri=redirect_uri"
  https://accounts.snapchat.com/login/oauth2/access_token

5. When the access token expires, generate a new one using the refresh token
curl -X POST \
  -d "refresh_token={refresh_token}" \
  -d "client_id={client_id}" \
  -d "client_secret={client_secret}"  \
  -d "grant_type=refresh_token"  \
  https://accounts.snapchat.com/login/oauth2/access_token



from pprint import pprint
from requests_oauthlib import OAuth2Session

client_id = ''
client_secret = ''
scope = ['snapchat-marketing-api']

redirect_url = 'https://www.getpostman.com/oauth2/callback'
authorize_url = 'https://accounts.snapchat.com/login/oauth2/authorize'
access_token_url = 'https://accounts.snapchat.com/login/oauth2/access_token'
protected_url = 'https://adsapi.snapchat.com/v1/me/organizations'

extra = {
    'client_id': client_id,
    'client_secret': client_secret,

}

oauth = OAuth2Session(client_id,
                      redirect_uri=redirect_url,
                      scope=scope)
authorization_url, state = oauth.authorization_url(authorize_url)
print 'Please go to %s and authorize access.' % authorization_url
authorization_response = raw_input('Enter the full callback URL: ')

token = oauth.fetch_token(access_token_url,
                          authorization_response=authorization_response,
                          client_secret=client_secret,
                          scope=scope)

print "\n\nGREAT NEWS EVERYBODY! You've got a token: "
pprint(oauth.token)
print 'Getting protected URL: {}'.format(protected_url)
resp = oauth.get(protected_url)
print resp.status_code
print resp.content

The above command returns JSON structured like this:

{
    "expires_in": 1800,
    "token_type": "Bearer",
    "refresh_token": "xyz",
    "access_token": "0.1234567890"
}

Access Token Expiration

Access Tokens are short-lived and expire after a number of seconds indicated by the expires_in property in the response, currently the expiry is 1800 seconds = 30 minutes.

When a request is attempted with an expired token, the response will be a 401 Not Authorized with additional headers.

< HTTP/1.1 401 Unauthorized
< Access-Control-Allow-Origin: *
< Access-Control-Allow-Headers: Content-Type, Authorization
< WWW-Authenticate: Bearer error="invalid_token", error_description="The access token expired"
< X-Cloud-Trace-Context: e0fdbe35c49ad238e624635b6a45813d;o=1
< Date: Mon, 15 Aug 2016 21:10:01 GMT
< Content-Type: text/html
< Server: Google Frontend
< Content-Length: 0

User

Get Authenicated User

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.users.me()
curl "https://adsapi.snapchat.com/v1/me"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "me": {
    "id": "2f5dd7e6-fcd1-4324-8455-1ea4d96caaaa",
    "updated_at": "2016-08-12T01:56:39.841Z",
    "created_at": "2016-08-12T01:56:39.842Z",
    "email": "honey.badger@hooli.com",
    "organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
    "display_name": "Honey Badger"
  },
  "request_id": "57ae093a00ff00ff43b8c63fda390001737e616473617069736300016275696c642d34363138393265642d312d31312d32000100"
}

This endpoint retrieves the authenticated user.

HTTP Request

GET https://adsapi.snapchat.com/v1/me

Organizations

An Organization represents an brand, partner or ad agency, creation happens via Snap Business Manager.

Attributes

Attribute Description Required Possible Values
name Organization name R

Create an Organization

The only way to set up an Organization is to sign up for a Business account with Snap Business Manager.

Get All Organizations

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.organizations.get()
curl "https://adsapi.snapchat.com/v1/me/organizations" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57affee300ff0d91229fabb9710001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010110",
  "organizations": [
    {
      "sub_request_status": "success",
      "organization": {
        "id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
        "updated_at": "2017-05-26T15:14:44.877Z",
        "created_at": "2017-05-26T15:14:44.877Z",
        "name": "My Organization",
        "address_line_1": "101 Stewart St",
        "locality": "Seattle",
        "administrative_district_level_1": "WA",
        "country": "US",
        "postal_code": "98134",
        "type": "ENTERPRISE"
      }
    },
    {
      "sub_request_status": "success",
      "organization": {
        "id": "507d7a57-94de-4239-8a74-e93c00ca53e6",
        "updated_at": "2016-08-01T15:14:44.877Z",
        "created_at": "2017-08-01T15:14:44.877Z",
        "name": "Hooli",
        "address_line_1": "1100 Silicon Vallety Rd",
        "locality": "San Francisco",
        "administrative_district_level_1": "CA",
        "country": "US",
        "postal_code": "94110",
        "type": "ENTERPRISE"
      }
    }
  ]
}

This endpoint retrieves all organizations.

HTTP Request

GET https://adsapi.snapchat.com/v1/me/organizations

Get All Organizations with Ad Accounts

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.organizations.get()
curl "https://adsapi.snapchat.com/v1/me/organizations?with_ad_accounts=true" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5b985a7300ff0b4b064df945b80001737e616473617069736300016275696c642d33346634346232622d312d3230302d320001011f",
    "organizations": [
        {
            "sub_request_status": "SUCCESS",
            "organization": {
                "id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
                "updated_at": "2018-09-04T16:27:01.066Z",
                "created_at": "2016-08-09T17:12:49.707Z",
                "name": "Hooli Inc",
                "country": "US",
                "postal_code": "90291",
                "locality": "Venice",
                "contact_name": "",
                "contact_email": "",
                "contact_phone": "",
                "tax_type": "NONE",
                "address_line_1": "64 Market St",
                "administrative_district_level_1": "CA",
                "accepted_term_version": "8",
                "is_agency": true,
                "configuration_settings": {
                    "notifications_enabled": true
                },
                "type": "ENTERPRISE",
                "state": "ACTIVE",
                "roles": [
                    "member"
                ],
                "ad_accounts": [
                    {
                        "id": "8b8e40af-fc64-455d-925b-ca80f7af6914",
                        "updated_at": "2018-03-07T23:39:20.469Z",
                        "created_at": "2018-03-27T23:42:43.513Z",
                        "name": "Hooli Originals",
                        "type": "PARTNER",
                        "status": "ACTIVE",
                        "currency": "USD",
                        "timezone": "America/Los_Angeles",
                        "roles": [
                            "reports"
                        ]
                    },
                    {
                        "id": "497979f0-ea17-4971-8288-054883f1caca",
                        "updated_at": "2017-01-04T22:58:38.179Z",
                        "created_at": "2018-09-07T14:41:36.002Z",
                        "name": "Pied piper Test Account",
                        "type": "PARTNER",
                        "status": "ACTIVE",
                        "currency": "USD",
                        "timezone": "America/Los_Angeles",
                        "roles": [
                            "admin"
                        ]
                    },
                    {
                        "id": "22ada972-f2aa-4d06-a45a-a7a80f53ae34",
                        "updated_at": "2017-07-28T02:32:03.914Z",
                        "created_at": "2017-12-08T21:56:57.305Z",
                        "name": "Initech Corp",
                        "type": "PARTNER",
                        "status": "ACTIVE",
                        "currency": "USD",
                        "timezone": "America/Los_Angeles",
                        "roles": [
                            "creative"
                        ]
                    }
                ],
                "my_display_name": "Honey Badger",
                "my_invited_email": "honey.badget@hooli.com",
                "my_member_id": "8454ada6-cec8-4e97-a0a7-c0b262c4137b"
            }
        }
    ]
}

This endpoint retrieves all organizations the user has access to and the ad accounts beneath each of those organizations. The roles attribute holds shows the role that the user holds within the Ad Account in question, Ad Account roles are explain in the Roles section.

HTTP Request

GET https://adsapi.snapchat.com/v1/me/organizations?with_ad_accounts=true

Get a Specific Organization

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.organizations.get('40d6719b-da09-410b-9185-0cc9c0dfed1d')
curl "https://adsapi.snapchat.com/v1/organizations/40d6719b-da09-410b-9185-0cc9c0dfed1d" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5928472c00ff04f7eaae709d770001737e7465616d6b6f363139000161646d616e616765722d61706",
  "organizations": [
    {
      "sub_request_status": "SUCCESS",
      "organization": {
        "id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
        "updated_at": "2017-05-26T15:14:44.877Z",
        "created_at": "2017-05-26T15:14:44.877Z",
        "name": "My Organization",
        "address_line_1": "101 Stewart St",
        "locality": "Seattle",
        "administrative_district_level_1": "WA",
        "country": "US",
        "postal_code": "98134",
        "type": "ENTERPRISE"
      }
    }
  ]
}

This endpoint retrieves a specific organization.

HTTP Request

GET https://adsapi.snapchat.com/v1/organizations/<ID>

URL Parameters

Parameter Description
ID The ID of the organization to retrieve

Funding Sources

An Funding Source is owned by an Organization and defines the financial instrument/terms responsible for the ad spend. Funding sources are assigned to an Ad Account in order to pay for the activity within that Ad Account.

Attributes

Attribute Description Possible Values Supported for type
id ID of the funding source ALL
created_at Date of creation ALL
updated_at Date of last update ALL
type Funding Source type LINE_OF_CREDIT, CREDIT_CARD, COUPON, PAYPAL ALL
status Status of the funding source ACTIVE, REDEEMED, SPENT, EXPIRED, DELETED ALL
budget_spent_micro Budget Spent (micro-currency) LINE_OF_CREDIT
currency Account currency USD, CAD, GBP, AUD, EUR LINE_OF_CREDIT, COUPON
total_budget_micro Total Budget (micro-currency) LINE_OF_CREDIT, CREDIT_CARD
budget_spent_micro Budget spent (micro-currency) LINE_OF_CREDIT, CREDIT_CARD
available_credit_micro Total available credit LINE_OF_CREDIT, COUPON
card_type Credit Card Type AMEX, DINERS_CLUB, DISCOVER, JCB, MAESTRO, MASTERCARD, VISA, UNKNOWN CREDIT_CARD
name Name of the Credit Card ALL
last_4 Last 4 digits of the Credit Card CREDIT_CARD
expiration_year Expiration year of the Credit Card CREDIT_CARD
expiration_month Expiration month of the Credit Card CREDIT_CARD
daily_spend_limit_micro Daily spend limit for Credit Card (micro-currency) CREDIT_CARD
daily_spend_limit_currency Currency for the daily_spend_limit_micro USD, CAD, GBP, AUD, EUR CREDIT_CARD
value_micro Value of the COUPON (micro-currency) COUPON
start_date Start date of the COUPON COUPON
end_date End date of the COUPON COUPON
email Email associated with Paypal PAYPAL

Create a Funding Source

Funding sources using credit cards and PayPal can be set up using Business Manager

The Partner Manager team creates all other types of Funding Sources on behalf of partners and advertisers. Please reach out to your partner manager for assistance.

Get All Funding Sources

curl "https://adsapi.snapchat.com/v1/organizations/{organization_id}/fundingsources" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "59236a2500ff05763ff95f2fcc0001737e7465616d6b6f363139000161646d616e616765722d6170693a6b6162726168616d0001011d",
  "fundingsources": [
    {
      "sub_request_status": "SUCCESS",
      "fundingsource": {
        "id": "1e224e75-3883-42cf-a5d9-ce505945d2d3",
        "updated_at": "2017-05-22T22:46:30.917Z",
        "created_at": "2017-05-22T22:46:30.917Z",
        "type": "CREDIT_CARD",
        "card_type": "DISCOVER",
        "name" : "My DISCOVER card",
        "last_4": "1100",
        "expiration_month": "12",
        "expiration_year": "2020",
        "daily_spend_limit_micro": 25000000,
        "daily_spend_currency": "USD"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "fundingsource": {
        "id": "9d111fbf-da5f-4526-9e7b-226f847b3d7e",
        "updated_at": "2017-05-22T22:46:30.920Z",
        "created_at": "2017-05-22T22:46:30.920Z",
        "type": "LINE_OF_CREDIT",
        "available_credit_micro": 2000000000,
        "currency": "USD",
        "total_budget_micro": 10000000000,
        "status": "ACTIVE",
        "credit_account_type": "MANAGED",
        "budget_spent_micro": 8000000000
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "fundingsource": {
        "id": "d24b4011-3560-47ea-86fa-0ed14c6b90d4",
        "updated_at": "2017-05-22T22:46:30.920Z",
        "created_at": "2017-05-22T22:46:30.920Z",
        "type": "COUPON",
        "available_credit_micro": 10000000000,
        "currency": "EUR",
        "value_micro": 10000000000,
        "status": "REDEEMED",
        "start_date": "2017-05-22T22:46:30.923Z",
        "end_date": "2017-05-22T22:46:30.923Z"
      }
    }
  ]
}

This endpoint retrieves all funding sources for the specified Organization.

HTTP Request

GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/fundingsources

Parameters

Parameter Default Description
organization_id Organization ID

Get a Specific Funding Source

curl "https://adsapi.snapchat.com/v1/fundingsources/e703eb9f-8eac-4eda-a9c7-deec3935222d" \
  -H "Authorization: Bearer  meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b000ffd800ff05551a197221f10001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010c",
  "fundingsources": [
    {
      "sub_request_status": "success",
      "fundingsource": {
        "id": "e703eb9f-8eac-4eda-a9c7-deec3935222d",
        "updated_at": "2016-08-11T22:03:54.337Z",
        "created_at": "2016-08-11T22:03:54.337Z",
        "name": "Hooli Test Ad Account Funding Source",
        "type": "LINE_OF_CREDIT",
        "organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
        "currency": "USD"
      }
    }
  ]
}

This endpoint retrieves a specific funding source.

HTTP Request

GET https://adsapi.snapchat.com/v1/fundingsources/{funding_source_id}

URL Parameters

Parameter Description
funding_source_id The ID of the funding source to retrieve

Billing Centers

Billing Centers allow Businesses to have multiple invoicing locations to choose from. A Billing Center is the contact that will be receiving invoices.

Billing Centers can only be created via Snap Business Manager.

Attributes

Attribute Description Required Possible Values
organization_id Organization ID R
name Name of the Billing Center R
email_address Email address R
address_line_1 Address line 1 R
locality Locality R
administrative_district_level_1 District R
country Country R
postal_code Post code R
alternative_email_addresses Array of email addresses O

Get all Billing Centers

curl "https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/billingcenters" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5eaa971a00ff05c3d6fabff7fb0001737e616473617069736300016275696c642d63386238336332372d312d3334372d310001011a",
    "paging": {},
    "billingcenters": [
        {
            "sub_request_status": "SUCCESS",
            "billingcenter": {
                "id": "8b8db2a8-2b48-42f0-858a-88901a782b27",
                "updated_at": "2017-10-17T12:25:50.866Z",
                "created_at": "2017-10-17T12:25:50.866Z",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "name": "Duck Billing Center",
                "email_address": "mr_duck@example.com",
                "address_line_1": "11 Duck Pond Avenue",
                "locality": "London",
                "administrative_district_level_1": "GB-LND",
                "country": "GB",
                "postal_code": "NW1 4RY"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "billingcenter": {
                "id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd",
                "updated_at": "2020-02-30T09:49:52.118Z",
                "created_at": "2020-02-30T09:49:52.118Z",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "name": "Kianjous Billing Center",
                "email_address": "honeybear_ltd@example.com",
                "address_line_1": "10 Honey Bear Road",
                "locality": "London",
                "administrative_district_level_1": "GB-LND",
                "country": "GB",
                "postal_code": "NW1 4RY",
                "alternative_email_addresses": [
                    "honeybear_burrow@example.com"
                ]
            }
        }
    ]
}

The following API request retrieves all Billing Centers for an Organization.

HTTP Request

GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/billingcenters

Parameters

Parameter Default Description
organization_id Organization ID

Get a specific Billing Center

curl "https://adsapi.snapchat.com/v1/billingcenters/6e0f4532-3702-4f0b-9889-9fe5d0614afd" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5eaa9e6000ff0570e6188bd1110001737e616473617069736300016275696c642d63386238336332372d312d3334372d3100010138",
    "billingcenters": [
        {
            "sub_request_status": "SUCCESS",
            "billingcenter": {
                "id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd",
                "updated_at": "2020-02-30T09:49:52.118Z",
                "created_at": "2020-02-30T09:49:52.118Z",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "name": "Kianjous Billing Center",
                "email_address": "honeybear_ltd@example.com",
                "address_line_1": "10 Honey Bear Road",
                "locality": "London",
                "administrative_district_level_1": "GB-LND",
                "country": "GB",
                "postal_code": "NW1 4RY",
                "alternative_email_addresses": [
                    "honeybear_burrow@example.com"
                ]
            }
        }
    ]
}

The following API request retrieves a specific Billing Center.

HTTP Request

GET https://adsapi.snapchat.com/v1/billingcenters/{billing_center_id}

Parameters

Parameter Default Description
billing_center_id Billing Center ID

Create a Billing Center

curl -X POST \
  -d '{"billingcenters":[{"organization_id":"8fdeefec-f502-4ca8-9a84-6411e0a51053","name":"Kianjous Billing Center","email_address":"honeybear_ltd@example.com","address_line_1":"10 Honey Bear Road","locality":"London","administrative_district_level_1":"GB-LND","country":"GB","postal_code":"NW1 4RY","alternative_email_addresses":["honeybear_burrow@example.com"]}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/billingcenters

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5eaa9f3f00ff0e03450355dbc60001737e616473617069736300016275696c642d63386238336332372d312d3334372d310001010b",
    "billingcenters": [
        {
            "sub_request_status": "SUCCESS",
            "billingcenter": {
                "id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd",
                "updated_at": "2020-02-30T09:49:52.118Z",
                "created_at": "2020-02-30T09:49:52.118Z",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "name": "Kianjous Billing Center",
                "email_address": "honeybear_ltd@example.com",
                "address_line_1": "10 Honey Bear Road",
                "locality": "London",
                "administrative_district_level_1": "GB-LND",
                "country": "GB",
                "postal_code": "NW1 4RY",
                "alternative_email_addresses": [
                    "honeybear_burrow@example.com"
                ]
            }
        }
    ]
}

The following API request creates a new Billing Center.

HTTP Request

GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/billingcenters

Parameters

Parameter Default Description
billing_center_id Billing Center ID

Update a Billing Center

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"billingcenters":[{"id":"6e0f4532-3702-4f0b-9889-9fe5d0614afd","organization_id":"1fdeefec-f502-4ca8-9a84-6411e0a51053","name":"Kianjous Billing Center","email_address":"honeybear_ltd@example.com","address_line_1":"10 Honey Bear Road","locality":"London","administrative_district_level_1":"GB-LND","country":"GB","postal_code":"NW1 4RY","alternative_email_addresses":["honeybear_burrow@example.com","mr_duck@example.com"]}]}'
  https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/billingcenters

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5eac190700ff04ae16ca53679d0001737e616473617069736300016275696c642d38653566343030352d312d3334382d3000010107",
    "billingcenters": [
        {
            "sub_request_status": "SUCCESS",
            "billingcenter": {
                "id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd",
                "updated_at": "2020-05-01T12:41:43.470Z",
                "created_at": "2020-04-30T09:49:52.118Z",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "name": "Kianjous Billing Center",
                "email_address": "honeybear_ltd@example.com",
                "address_line_1": "10 Honey Bear Road",
                "locality": "London",
                "administrative_district_level_1": "GB-LND",
                "country": "GB",
                "postal_code": "NW1 4RY",
                "alternative_email_addresses": [
                    "honeybear_burrow@example.com",
                    "mr_duck@example.com"
                ]
            }
        }
    ]
}

The following API request updates a Billing Center with new details.

Attributes that can be updated

Attribute Required
name R
email_address R
address_line_1 R
locality R
administrative_district_level_1 R
country R
postal_code R
alternative_email_addresses O

HTTP Request

PUT https://adsapi.snapchat.com/v1/organizations/{organization_id}/billingcenters

Parameters

Parameter Default Description
billing_center_id Billing Center ID

Invoices

Invoices can only be created by Snap, Invoices are allocated on an Ad Account basis and can be fetched by an member with one of the following roles, Organization Admin, Ad Account Admin, or Campaign Manager.

Attributes

Attribute Description Possible Values
org_id Organization ID
invoice_id Invoice ID
netsuite_file_id Snap Internal ID
ad_account_id Ad Account ID
customer.name Customer name
customer.netsuite_id Snap Internal ID
document_number Document number
line_last_modified Date
last_modified Date
amount_cent Invoice amount in cents
currency Currency of the invoice AUD, CAD, EUR, GBP, USD, SEK, DKK, NOK
billing_period Specifies the billing period
due_date Due date of the invoice
created_at Creation date of the invoice
invoice_status Indicates whether the invoice has been collected COLLECTED, SENT_FOR_COLLECTION
invoice_content Bytestream (Base64), this Bytestream can turned into a PDF

List invoices by Ad Account

curl "https://adsapi.snapchat.com/v1/adaccounts/88cdd2d0-b604-455a-925b-b8eb68823e48/invoices" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f0f19d700ff0306e63ea5ff00980001737e616473617069736300016275696c642d61646161313865312d312d3336372d3000010102",
    "invoices": [
        {
            "sub_request_status": "SUCCESS",
            "invoice": {
                "org_id": "8ba72a1b-0901-4b9e-951a-e39b9ad27aa3",
                "invoice_id": "861b7c55-7e35-4348-918f-3758db350b80",
                "netsuite_file_id": "5910692",
                "ad_account_id": "88cdd2d0-b604-455a-925b-b8eb68823e48",
                "customer": {
                    "name": "Badger Tunneling Inc.",
                    "netsuite_id": "8828020"
                },
                "document_number": "146810",
                "line_last_modified": "2020-05-14T08:20:00.000Z",
                "last_modified": "2020-05-14T08:20:00.000Z",
                "amount_cent": 1171496,
                "currency": "USD",
                "billing_period": "April 2020",
                "due_date": "2020-06-05T00:00:00.000Z",
                "created_at": "2020-05-02T06:45:00.000Z",
                "invoice_status": "COLLECTED"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "invoice": {
                "org_id": "8ba72a1b-0901-4b9e-951a-e39b9ad27aa3",
                "invoice_id": "8848a897-e1b7-4433-a9a1-78fbafb5d52b",
                "netsuite_file_id": "8036582",
                "ad_account_id": "88cdd2d0-b604-455a-925b-b8eb68823e48",
                "customer": {
                    "name": "Badger Tunneling Inc.",
                    "netsuite_id": "8828020"
                },
                "document_number": "151141",
                "line_last_modified": "2020-06-09T08:34:00.000Z",
                "last_modified": "2020-06-09T08:34:00.000Z",
                "amount_cent": 375222,
                "currency": "USD",
                "billing_period": "May 2020",
                "due_date": "2020-07-05T00:00:00.000Z",
                "created_at": "2020-06-02T07:05:00.000Z",
                "invoice_status": "COLLECTED"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "invoice": {
                "org_id": "8ba72a1b-0901-4b9e-951a-e39b9ad27aa3",
                "invoice_id": "8be7c07f-b1dc-4aca-9729-348bf05b67a6",
                "netsuite_file_id": "8170796",
                "ad_account_id": "88cdd2d0-b604-455a-925b-b8eb68823e48",
                "customer": {
                    "name": "Badger Tunneling Inc.",
                    "netsuite_id": "8828020"
                },
                "document_number": "154209",
                "line_last_modified": "2020-07-07T16:15:00.000Z",
                "last_modified": "2020-07-07T16:15:00.000Z",
                "amount_cent": 1329360,
                "currency": "USD",
                "billing_period": "June 2020",
                "due_date": "2020-08-06T00:00:00.000Z",
                "created_at": "2020-07-02T04:53:00.000Z",
                "invoice_status": "SENT_FOR_COLLECTION"
            }
        }
    ]
}

This endpoint will list all invoices for a given Ad Account.

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/invoices

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Get individual Invoice

curl "https://adsapi.snapchat.com/v1/adaccounts/04cdd2d0-b604-455a-925b-b8eb68823e48/invoices/2be7c07f-b1dc-4aca-9729-348bf05b67a6" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f107ce000ff0da20b969610630001737e616473617069736300016275696c642d61646161313865312d312d3336372d3000010131",
    "invoices": [
        {
            "sub_request_status": "SUCCESS",
            "invoice": {
                "org_id": "eba72a1b-0901-4b9e-951a-e39b9ad27aa3",
                "invoice_id": "2be7c07f-b1dc-4aca-9729-348bf05b67a6",
                "netsuite_file_id": "6216757",
                "ad_account_id": "04cdd2d0-b604-455a-925b-b8eb68823e48",
                "customer": {
                    "name": "Flo Health, Inc.",
                    "netsuite_id": "7828020"
                },
                "document_number": "154209",
                "line_last_modified": "2020-07-15T09:03:00.000Z",
                "last_modified": "2020-07-15T09:03:00.000Z",
                "amount_cent": 1329360,
                "currency": "USD",
                "billing_period": "June 2020",
                "due_date": "2020-08-06T00:00:00.000Z",
                "created_at": "2020-07-02T04:53:00.000Z",
                "invoice_status": "COLLECTED"
            }
        }
    ]
}

This endpoint retrieve an individual invoice for a given Ad Account

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/invoices/{invoice_id}

Parameters

Parameter Default Description
ad_account_id Ad Account ID
invoice_id Invoice ID
include_pdf false optional parameter for retrieving the invoice_content attribute

Example 1 - Invoice

Retrieving an invoice

curl "https://adsapi.snapchat.com/v1/adaccounts/9d874f18-8a86-422b-a4c0-67525472f339/invoices/93106732-4504-4220-83f6-035c30bf38a9" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f15b33d00ff04a2f415f889b70001737e616473617069736300016275696c642d65626530306366642d312d3336382d300001014c",
    "invoices": [
        {
            "sub_request_status": "SUCCESS",
            "invoice": {
                "org_id": "96412453-e008-4353-a8da-881ed5170e9c",
                "invoice_id": "93106732-4504-4220-83f6-035c30bf38a9",
                "netsuite_file_id": "9214559",
                "ad_account_id": "9d874f18-8a86-422b-a4c0-67525472f339",
                "customer": {
                    "name": "Hedgehogs interactive Ltd",
                    "netsuite_id": "90053849"
                },
                "document_number": "150239",
                "line_last_modified": "2020-07-14T23:43:00.000Z",
                "last_modified": "2020-07-14T23:43:00.000Z",
                "amount_cent": 132095,
                "currency": "USD",
                "billing_period": "May 2020",
                "due_date": "2020-07-05T00:00:00.000Z",
                "created_at": "2020-06-02T02:54:00.000Z",
                "invoice_status": "COLLECTED"
            }
        }
    ]
}

This example retrieves an individual invoice.

Example 2 - Invoice - invoice_content

Retrieving an invoice with invoice_content

curl "https://adsapi.snapchat.com/v1/adaccounts/9e08d5dd-023b-429e-904c-0924291dc478/invoices/9db4ab51-6402-4b20-b47b-a893267dfb3f?include_pdf=true" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f15b5cd00ff0781f49f7748b80001737e616473617069736300016275696c642d65626530306366642d312d3336382d3000010150",
    "invoices": [
        {
            "sub_request_status": "SUCCESS",
            "invoice": {
                "org_id": "97433ff4-1fb6-416f-b726-069624ac1de2",
                "invoice_id": "9db4ab51-6402-4b20-b47b-a893267dfb3f",
                "netsuite_file_id": "5489672",
                "ad_account_id": "9e08d5dd-023b-429e-904c-0924291dc478",
                "customer": {
                    "name": "Le Chipmunks Inc",
                    "netsuite_id": "1277123"
                },
                "document_number": "124357",
                "line_last_modified": "2020-02-21T02:11:00.000Z",
                "last_modified": "2020-02-21T02:11:00.000Z",
                "amount_cent": 953057,
                "currency": "EUR",
                "billing_period": "November 2019",
                "due_date": "2020-02-03T00:00:00.000Z",
                "created_at": "2019-12-02T15:41:00.000Z",
                "invoice_content": "JVBERi0xLjMKJd/++LIKMSAwIG9iago8PC ... emUgMzI+PgpzdGFydHhyZWYKMjY1ODQKJSVFT0YK",
                "invoice_status": "COLLECTED"
            }
        }
    ]
}

This example retrieves an individual invoice for with the parameter include_pdf which adds the attribute invoice_content on the invoice entity that is returned.

Ad Accounts

An Ad Account is owned by an Organization and contains Ad Campaigns. Ad Accounts have one or more Funding Sources (Credit card, Paypal, Lines of Credit etc).

Attributes

Attribute Description Required Possible Values
advertiser Name of the Advertiser R User input
currency Account currency R AUD, CAD, EUR, GBP, USD
funding_source_ids Array of Funding Source IDs R
billing_type Type of billing R IO, REVOLVING
name Account name R User input
organization_id Organization ID R
test Indicates Ad Account is a test ad account, test ad accounts can never serve live ads O true
timezone Account timezone, remember to take the time differences into account when you set up your application. All our timings are stored in UTC which means you are required to add/remove hours to make up a full 24 hours when using the DAY granularity in the API R Africa/Cairo, Africa/Johannesburg, America/Anchorage, America/Cancun, America/Chicago, America/Dawson, America/Dawson_Creek, America/Denver, America/Edmonton, America/Halifax, America/Hermosillo, America/Los_Angeles, America/Mazatlan, America/Mexico_City, America/Montevideo, America/New_York, America/Phoenix, America/Rainy_River, America/Regina, America/Tijuana, America/Toronto, America/Vancouver, Asia/Amman, Asia/Beirut, Asia/Dubai, Asia/Hong_Kong, Asia/Irkutsk, Asia/Jerusalem, Asia/Kamchatka, Asia/Krasnoyarsk, Asia/Magadan, Asia/Nicosia, Asia/Omsk, Asia/Qatar, Asia/Riyadh, Asia/Shanghai, Asia/Singapore, Asia/Vladivostok, Asia/Yakutsk, Asia/Yekaterinburg, Atlantic/Canary, Australia/Perth, Australia/Sydney, Europe/Amsterdam, Europe/Berlin, Europe/Brussels, Europe/Dublin, Europe/Helsinki, Europe/Istanbul, Europe/Kaliningrad, Europe/London, Europe/Luxembourg, Europe/Madrid, Europe/Malta, Europe/Moscow, Europe/Oslo, Europe/Paris, Europe/Rome, Europe/Samara, Europe/Stockholm, Europe/Vienna, Europe/Vilnius, Europe/Warsaw, Europe/Zurich, Pacific/Auckland, Pacific/Honolulu, UTC
type Account type R DIRECT, PARTNER
lifetime_spend_cap_micro Required if billing_type is set to IO, the lifetime spend cap of the account in micro currency O
advertiser_organization_id Organization ID of the Advertiser selected read-only
paying_advertiser_name Name of the paying advertiser/political entity, required if the Ad Account will contain political/advocacy ads O max 32 characters
regulations Required if the Ad Account will contain ads for Credit, Housing or Employment, this attribute is immutable once set to true O { “restricted_delivery_signals”: true }
agency_representing_client Account name R true/false
client_based_in_country Required if agency_representing_client is true and if Advertiser is based in France or targeting Ads to audiences in France O FR
client_paying_invoices Required if agency_representing_client is true and if Advertiser is based in France or targeting Ads to audiences in France O true/false
agency_client_metadata Client metadata is required if agency_representing_client is true and if the Advertiser is based in France or is targeting Ads to audiences in France O JSON object containing the attributes; name, email, address_line_1, city,administrative_district_level_1, country, zipcode, tax_id
delivery_status Delivery status Read-only See Delivery status

Create an Ad Account

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{"adaccounts": [{"name": "Example Ad Account","type": "PARTNER","status": "ACTIVE","organization_id": "7fdeefec-f502-4ca8-9a84-6411e0a51058","funding_source_ids": ["6ca1687a-f2b4-437d-8554-a85403a714c5"],"currency": "USD","billing_type": "IO","billing_center_id": "9b8db2a8-2b48-42f0-858a-88901a782b27","lifetime_spend_cap_micro": "200000000000","timezone": "America\/Los_Angeles","advertiser": "Example Advertiser Inc"}]}' \
  https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/adaccounts

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5e7b42c900ff0e76f111031c2c0001737e616473617069736300016275696c642d62313763613636652d312d3333372d3200010122",
    "adaccounts": [
        {
            "sub_request_status": "SUCCESS",
            "adaccount": {
                "id": "7c6d2e91-3a7c-4230-b048-f724bf217a82",
                "updated_at": "2020-03-25T11:38:50.273Z",
                "created_at": "2020-03-25T11:38:50.273Z",
                "name": "Example Ad Account",
                "type": "PARTNER",
                "status": "ACTIVE",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
                "funding_source_ids": [
                    "6ca1687a-f2b4-437d-8554-a85403a714c5"
                ],
                "currency": "USD",
                "timezone": "America/Los_Angeles",
                "advertiser": "Example Advertiser Inc",
                "advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
                "billing_center_id": "9b8db2a8-2b48-42f0-858a-88901a782b27",
                "billing_type": "IO",
                "lifetime_spend_cap_micro": 200000000000,
                "agency_representing_client": false,
                "client_paying_invoices": false
            }
        }
    ]
}

This endpoint creates an Ad Account within the specified Organization. When setting up new Ad Accounts it’s important to take the below factors into account, not following these points may cause the Ad Account to be suspended.

HTTP Request

GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/adaccounts

Parameters

Parameter Default Description
organization_id Organization ID

Get All Ad Accounts

curl "https://adsapi.snapchat.com/v1/organizations/{organization_id}/adaccounts" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b0015e00ff07d5c0c38928ad0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010107",
  "adaccounts": [
    {
      "sub_request_status": "success",
      "adaccount": {
        "id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "updated_at": "2016-08-11T22:03:58.869Z",
        "created_at": "2016-08-11T22:03:58.869Z",
        "name": "Hooli Test Ad Account",
        "type": "PARTNER",
        "status": "ACTIVE",
        "organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
        "funding_source_ids": [
          "e703eb9f-8eac-4eda-a9c7-deec3935222d"
        ],
        "currency": "USD",
        "timezone": "America/Los_Angeles",
        "advertiser": "Hooli"
      }
    },
    {
      "sub_request_status": "success",
      "adaccount": {
        "id": "81cf9302-764c-429a-8561-e3bc329cf987",
        "updated_at": "2016-08-11T22:03:58.869Z",
        "created_at": "2016-08-11T22:03:58.869Z",
        "name": "Awesome Ad Account",
        "type": "DIRECT",
        "status": "ACTIVE",
        "organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
        "funding_source_ids": [
          "7abfb9c6-0258-4eee-9898-03a8c099695d"
        ],
        "currency": "USD",
        "timezone": "America/Los_Angeles",
        "advertiser": "Hooli"
      }
    }
  ]
}

This endpoint retrieves all ad accounts for the specified Organization.

HTTP Request

GET https://adsapi.snapchat.com/v1/organizations/{organization-id}/adaccounts

Parameters

Parameter Default Description
organization_id Organization ID

Get a Specific Ad Account

curl "https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b0021900ff06bbfeb44f77240001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010e",
  "adaccounts": [
    {
      "sub_request_status": "success",
      "adaccount": {
        "id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "updated_at": "2016-08-11T22:03:58.869Z",
        "created_at": "2016-08-11T22:03:58.869Z",
        "name": "Hooli Test Ad Account",
        "type": "PARTNER",
        "status": "ACTIVE",
        "organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
        "funding_source_ids": [
          "e703eb9f-8eac-4eda-a9c7-deec3935222d"
        ],
        "currency": "USD",
        "timezone": "America/Los_Angeles",
        "advertiser": "Hooli"
      }
    }
  ]
}

This endpoint retrieves a specific Ad Account.

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}

URL Parameters

Parameter Description
ad_account_id Ad Account ID of the ad account to retrieve

Update Ad Account

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"adaccounts": [{"type": "PARTNER","advertiser": "Example Advertiser Inc","advertiser_organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053","billing_center_id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd","billing_type": "IO","currency": "USD","id": "7c6d2e91-3a7c-4230-b048-f724bf217a82","lifetime_spend_cap_micro": 200000000000,"name": "Example Ad Account","organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053","funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],"status": "ACTIVE","timezone": "America/Los_Angeles","agency_representing_client": false,"client_paying_invoices": false}]}'
  https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/adaccounts

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5eac3e0c00ff07836d9acd3b2a0001737e616473617069736300016275696c642d38653566343030352d312d3334382d3000010137",
    "adaccounts": [
        {
            "sub_request_status": "SUCCESS",
            "adaccount": {
                "id": "7c6d2e91-3a7c-4230-b048-f724bf217a82",
                "updated_at": "2020-05-01T15:19:41.536Z",
                "created_at": "2020-03-25T11:38:50.273Z",
                "name": "Example Ad Account",
                "type": "PARTNER",
                "status": "ACTIVE",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "funding_source_ids": [
                    "5ca1687a-f2b4-437d-8554-a85403a714c5"
                ],
                "currency": "USD",
                "timezone": "America/Los_Angeles",
                "advertiser": "Example Advertiser Inc",
                "advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "billing_center_id": "6e0f4532-3702-4f0b-9889-9fe5d0614afd",
                "billing_type": "IO",
                "lifetime_spend_cap_micro": 200000000000,
                "agency_representing_client": false,
                "client_paying_invoices": false
            }
        }
    ]
}

This endpoint updates a specific Ad Account.

Attributes that can be updated

Attribute Required
name R
advertiser R
billing_center_id R
lifetime_spend_cap_micro R
regulations.restricted_delivery_signals R
agency_representing_client R
paying_advertiser_name O
client_paying_invoices O
client_based_in_country O
agency_client_metadata O

HTTP Request

PUT https://adsapi.snapchat.com/v1/organizations/{organization_id}/adaccounts

URL Parameters

Parameter Description
organization_id Organization ID of the Organization to which the Ad Account belongs

Update an Ad Account’s Lifetime Spend Cap

curl -X PUT \
  -H 'Authorization: Bearer meowmeowmeow' \
  -H 'Content-Type: application/json' \
  -d '{"adaccounts": [{"id":"123b9ca6-92f2-49c3-a3ed-0ea58afb467e","name":"Hooli Ad Account","type":"PARTNER","status":"ACTIVE","organization_id":"40c6719b-da09-410b-9185-0cc9c0dfed1d","funding_source_ids":["cdc67eba-a774-4954-9b94-9502bbdac1bc"],"currency":"USD","timezone":"America/Los_Angeles","brand_name":"Hooli","lifetime_spend_cap_micro":1500000000
}]}' \
  https://adsapi.snapchat.com/v1/organizations/40c6719b-da09-410b-9185-0cc9c0dfed1d/adaccounts

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b0021900ff06bbfeb44f77240001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010e",
  "adaccounts": [
    {
      "sub_request_status": "success",
      "adaccount": {
        "id": "123b9ca6-92f2-49c3-a3ed-0ea58afb467e",
        "updated_at": "2016-08-11T22:03:58.869Z",
        "created_at": "2016-08-11T22:03:58.869Z",
        "name": "Hooli Ad Account",
        "type": "PARTNER",
        "status": "ACTIVE",
        "organization_id": "40c6719b-da09-410b-9185-0cc9c0dfed1d",
        "funding_source_ids": [
          "e703eb9f-8eac-4eda-a9c7-deec3935222d"
        ],
        "currency": "USD",
        "timezone": "America/Los_Angeles",
        "brand_name":"Hooli",
        "lifetime_spend_cap_micro":1500000000
      }
    }
  ]
}

This endpoint updates the Lifetime Spend Limit of a specific ad account, this can only be updated for Ad Accounts where the billing_type is set to IO. Please note that once the Lifetime Spend Limit is set for a specific ad account, it can only be increased or decreased but not removed.

Assign Funding Source

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.

Ad Account creation - Example 4

Ad Account - Setting up a test Ad Account

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{"adaccounts": [{"name":"The Dalmatian Test Account","type":"PARTNER","status":"ACTIVE","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058","currency": "EUR","timezone": "Europe\/London","advertiser":"Dalmatian Retail",  "billing_type":"REVOLVING","billing_center_id":"7b8db2a8-2b48-42f0-858a-88901a782b27","agency_representing_client":false,  "client_paying_invoices": false,"test":true}]}' \
  https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/adaccounts

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f68d35200ff0864c8d10ae0dd0001737e616473617069736300016275696c642d35373264613164312d312d3338362d300001013d",
    "adaccounts": [
        {
            "sub_request_status": "SUCCESS",
            "adaccount": {
                "id": "a54ccc44-12fa-4952-b813-95f5dcfc27e7",
                "updated_at": "2020-09-21T16:22:43.094Z",
                "created_at": "2020-09-21T16:22:43.094Z",
                "name": "The Dalmatian Test Account",
                "type": "PARTNER",
                "status": "ACTIVE",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
                "currency": "EUR",
                "timezone": "Europe/London",
                "advertiser": "Dalmatian Retail",
                "advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
                "billing_center_id": "7b8db2a8-2b48-42f0-858a-88901a782b27",
                "test": true,
                "billing_type": "REVOLVING",
                "agency_representing_client": false,
                "client_paying_invoices": false
            }
        }
    ]
}

This request creates an Ad Account with the test parameter set to true, the resulting Ad Account never will be able to serve ads. The intention of setting up such an Ad Account is to be able to execute write requests without risking that ads will go live.

Members

A Member represents a Snapchat account user who is a member of an Organization, a Member needs to be assigned a Role within both the Organization and individual Ad Accounts in order to access entities.

Attributes

Attribute Description Required Possible Values
display_name Name of the user R
organization_id Organization ID R
member_status Name of the Advertiser R INVITED, MEMBER
email email address of the user R

Get all Members of an Organization

curl "https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/members" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ea05c4800ff08ac5ff42a0f740001737e616473617069736300016275696c642d64313063316333662d312d3334352d3000010102",
    "members": [
        {
            "sub_request_status": "SUCCESS",
            "member": {
                "id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
                "updated_at": "2017-10-17T12:25:50.815Z",
                "created_at": "2017-10-17T12:25:50.815Z",
                "email": "honeybear@example.com",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "display_name": "Honey Bear",
                "member_status": "MEMBER"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "member": {
                "id": "b124e762-9720-4f89-bdd2-7fe06e71d7cc",
                "updated_at": "2020-03-05T11:29:31.562Z",
                "created_at": "2018-09-28T19:05:09.787Z",
                "email": "jack_the_bear@example.com",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "display_name": "Jack Polarbear",
                "member_status": "MEMBER"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "member": {
                "id": "d051973d-32b2-496b-b44a-345986bce17d",
                "updated_at": "2020-04-22T14:56:33.164Z",
                "created_at": "2020-04-22T14:45:04.452Z",
                "email": "guinea_pig@example.com",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "display_name": "Esmeralda the Guinea Pig",
                "member_status": "MEMBER"
            }
        }
    ]
}

The following API request returns the information of all Members of an Organization, this includes their display name, email address and member status. Members who have not yet accepted their invite will have the status INVITED, members that have accepted the invite will have the status MEMBER.

HTTP Request

GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/members

Parameters

Parameter Default Description
organization_id Organization ID

Get a specific Member

curl "https://adsapi.snapchat.com/v1/members/d051973d-32b2-496b-b44a-345986bce17d" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ea05dcf00ff05a0584dcd2c0f0001737e616473617069736300016275696c642d64313063316333662d312d3334352d300001015b",
    "members": [
        {
            "sub_request_status": "SUCCESS",
            "member": {
                "id": "d051973d-32b2-496b-b44a-345986bce17d",
                "updated_at": "2020-04-22T14:56:33.164Z",
                "created_at": "2020-02-22T14:45:04.452Z",
                "email": "honeybear@example.com",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "display_name": "Honey Bear",
                "member_status": "MEMBER"
            }
        }
    ]
}

The following API request returns the information of a specific Member.

HTTP Request

GET https://adsapi.snapchat.com/v1/members/{member_id}

Parameters

Parameter Default Description
member_id Member ID

Create Member

curl -X POST \
  -d '{"members": [{"email": "honeybear@example.com","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","display_name": "Honey Bear"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/members

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ea0587000ff0360f26d1e8c1d0001737e616473617069736300016275696c642d64313063316333662d312d3334352d3000010157",
    "members": [
        {
            "sub_request_status": "SUCCESS",
            "member": {
                "id": "d051973d-32b2-496b-b44a-345986bce17d",
                "updated_at": "2020-04-22T14:45:04.452Z",
                "created_at": "2020-04-22T14:45:04.452Z",
                "email": "honeybear@example.com",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "display_name": "Honey Bear",
                "member_status": "INVITED"
            }
        }
    ]
}

The following API request creates a member within the chosen Organization, this will trigger an email invite to the user in question. When the user accepts the invite the member_status attribute will update from INVITED to MEMBER. Member creation should always be coupled with a Role creation within the Organization.

HTTP Request

POST https://adsapi.snapchat.com/v1/organizations/{organization_id}/members

Parameters

Parameter Default Description
organization_id Organization ID

Delete Member

curl -X DELETE "https://adsapi.snapchat.com/v1/members/d051973d-32b2-496b-b44a-345986bce17d" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status":"SUCCESS",
    "request_id":"5ea6f3f900ff01fa13ebea326c0001737e616473617069736300016275696c642d39326335343566322d312d3334362d3000010107",
    "members":[]
}

The following API request deletes a member from the Organization.

HTTP Request

DELETE https://adsapi.snapchat.com/v1/{{member_id}}

Parameters

Parameter Default Description
member_id Member ID

Roles

Roles exist at two levels, Organization level and Ad Account level.

Organization Roles

Attributes

Attribute Description Required Possible Values
member_id Member ID R
organization_id Organization ID R
type Organization role type R member, admin

A Member must be assigned one of the two Organization role types, member or admin.

Name Description
admin Admin access to everything in the Organization including creating, updating, deleting entities, adding new Members, assigning Roles
member Required for all Members who do not have the admin role, also a prerequisite for Ad Account Roles

Ad Account Roles

Attributes

Attribute Description Required Possible Values
member_id Member ID R
ad_account_id Member ID R
type Ad Account role type R admin, creative, general, reports, audience

In order to be assigned an Ad Account role the Member in question first needs the Organization role type member.

Name Description
admin Admin access to everything in the Ad Account
creative Has full control of Creative and Media entities, and read access to all other entities.
general Has full control of sub-Ad Account level entities (Campaigns, Ad Squads, Ads)
reports Has read-only access to the Ad Account for reporting purposes.
audience Has full control of Audience entities

Get Roles for Member

curl "https://adsapi.snapchat.com/v1/members/d051973d-32b2-496b-b44a-345986bce17d/roles?limit=100" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ea9654400ff07724b540651010001737e616473617069736300016275696c642d36373239363666352d312d3334372d3000010115",
    "paging": {},
    "roles": [
        {
            "sub_request_status": "SUCCESS",
            "role": {
                "id": "53155cfb-fc21-4d5f-a3dc-2ab7d8c7db03",
                "updated_at": "2020-02-04T12:32:22.365Z",
                "created_at": "2020-02-04T12:32:22.281Z",
                "container_kind": "AdAccounts",
                "container_id": "8fb3b893-7978-43d5-81fe-fe0613972092",
                "member_id": "d051973d-32b2-496b-b44a-345986bce17d",
                "ad_account_id": "8fb3b893-7978-43d5-81fe-fe0613972092",
                "type": "reports"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "role": {
                "id": "9e19db05-340d-4cdf-8de9-09022a2842cf",
                "updated_at": "2019-02-06T23:26:11.401Z",
                "created_at": "2018-10-17T11:48:58.601Z",
                "container_kind": "AdAccounts",
                "container_id": "82225ba6-7559-4000-9663-bace8adff5f2",
                "member_id": "d051973d-32b2-496b-b44a-345986bce17d",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
                "type": "admin"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "role": {
                "id": "ab0e7b9b-e0c0-441e-b26b-90ebd13c564a",
                "updated_at": "2019-02-07T00:52:25.576Z",
                "created_at": "2018-10-17T11:48:24.559Z",
                "container_kind": "Organizations",
                "container_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "member_id": "d051973d-32b2-496b-b44a-345986bce17d",
                "organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053",
                "type": "member"
            }
        }
    ]
}

The following API request returns all Roles assigned to a Member, this includes Roles within both Organizations and Ad Accounts.

HTTP Request

GET https://adsapi.snapchat.com/v1/members/{member_id}/roles

Parameters

Parameter Default Description
something_id Organization ID
limit integer, min 50, max 1000

Get all Roles in Organization

curl "https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/roles?limit=100" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ea9636000ff0d8046762797040001737e616473617069736300016275696c642d36373239363666352d312d3334372d300001010c",
    "paging": {},
    "roles": [
        {
            "sub_request_status": "SUCCESS",
            "role": {
                "id": "1001050f-325e-486f-902f-e7eea192755f",
                "updated_at": "2019-12-05T14:30:20.480Z",
                "created_at": "2019-12-05T14:30:20.480Z",
                "container_kind": "Organizations",
                "container_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053",
                "member_id": "63ef6f6d-09f4-4eb7-aa52-c83bcc35608c",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "type": "admin"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "role": {
                "id": "10d8b407-40f3-406d-8d04-2d5c59ff55fd",
                "updated_at": "2020-03-05T11:29:31.964Z",
                "created_at": "2020-03-05T11:29:31.964Z",
                "container_kind": "Organizations",
                "container_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053",
                "member_id": "b124e762-9720-4f89-bdd2-7fe06e71d7cc",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "type": "member"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "role": {
                "id": "20feac40-828c-46e2-a57b-60b5e0274ce4",
                "updated_at": "2020-03-25T17:54:39.170Z",
                "created_at": "2020-03-25T17:54:39.170Z",
                "container_kind": "Organizations",
                "container_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053",
                "member_id": "9db3e9a8-b7d4-4bb9-922f-72ea22d10aa6",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "type": "member"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "role": {
                "id": "57fa3d11-7330-461e-aca0-0d010d5b4932",
                "updated_at": "2019-02-06T07:42:30.365Z",
                "created_at": "2017-10-17T12:25:50.821Z",
                "container_kind": "Organizations",
                "container_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053",
                "member_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "type": "admin"
            }
        }
    ]
}

The following API request returns all Roles assigned within an Organization.

HTTP Request

GET https://adsapi.snapchat.com/v1/organizations/{organization_id}/roles

Parameters

Parameter Default Description
organization_id Organization ID
limit integer, min 50, max 1000

Create Organization Role

curl -X POST \
  -d '{"roles": [{"member_id": "d051973d-32b2-496b-b44a-345986bce17d","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","type": "member"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/organizations/1fdeefec-f502-4ca8-9a84-6411e0a51053/roles

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ea8334500ff06d6157db3e3d40001737e616473617069736300016275696c642d36373239363666352d312d3334372d3000010137",
    "roles": [
        {
            "sub_request_status": "SUCCESS",
            "role": {
                "id": "9a121178-73f0-4089-8f80-a60e5445e8ea",
                "updated_at": "2020-04-28T13:44:37.586Z",
                "created_at": "2020-04-28T13:44:37.586Z",
                "container_kind": "Organizations",
                "container_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "member_id": "d051973d-32b2-496b-b44a-345986bce17d",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "type": "member"
            }
        }
    ]
}

The following API request creates an Organization Role for a Member, this should follow any Member invitation to the Organization.

HTTP Request

POST https://adsapi.snapchat.com/v1/organizations/{organization_id}/roles

Parameters

Parameter Default Description
organization_id Organization ID

Get all Roles in Ad Account

curl "https://adsapi.snapchat.com/v1/82225ba6-7559-4000-9663-bace8adff5f2/roles?limit=1000" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ea85f5100ff0e03a2de2a46760001737e616473617069736300016275696c642d36373239363666352d312d3334372d3000010106",
    "paging": {},
    "roles": [
        {
            "sub_request_status": "SUCCESS",
            "role": {
                "id": "4c73255a-903a-423c-a98d-862bba405ec0",
                "updated_at": "2019-05-22T13:04:14.694Z",
                "created_at": "2019-05-22T13:04:14.694Z",
                "container_kind": "AdAccounts",
                "container_id": "82225ba6-7559-4000-9663-bace8adff5f2",
                "member_id": "9227efda-b0d4-497e-82b9-0125780892ec",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
                "type": "creative"
            }
        },

        {
            "sub_request_status": "SUCCESS",
            "role": {
                "id": "e293289e-14d8-432a-9edb-2943b75da2ec",
                "updated_at": "2019-02-07T18:08:18.706Z",
                "created_at": "2018-10-18T19:41:56.727Z",
                "container_kind": "AdAccounts",
                "container_id": "82225ba6-7559-4000-9663-bace8adff5f2",
                "member_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
                "type": "admin"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "role": {
                "id": "f7cd2f3c-de7e-4b4f-b8f4-44f2b428bca9",
                "updated_at": "2020-03-25T17:55:01.620Z",
                "created_at": "2020-03-25T17:55:01.344Z",
                "container_kind": "AdAccounts",
                "container_id": "82225ba6-7559-4000-9663-bace8adff5f2",
                "member_id": "9db3e9a8-b7d4-4bb9-922f-72ea22d10aa6",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
                "type": "general"
            }
        }
    ]
}

The following API gets a list of all Roles that have been created within an Ad Account.

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/roles

Parameters

Parameter Default Description
ad_account_id Ad Account ID
limit integer, min 50, max 1000

Create Ad Account Role

curl -X POST \
  -d '{"roles": [{"member_id": "d051973d-32b2-496b-b44a-345986bce17d","ad_account_id": "8c545687-a599-4faa-a704-4b097c6da5fe","type": "creative"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8c545687-a599-4faa-a704-4b097c6da5fe/roles

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ea8335700ff09599711db33160001737e616473617069736300016275696c642d36373239363666352d312d3334372d3000010135",
    "roles": [
        {
            "sub_request_status": "SUCCESS",
            "role": {
                "id": "5191aec7-b771-4c56-9963-126b14dbe2e3",
                "updated_at": "2020-02-28T13:44:55.746Z",
                "created_at": "2020-02-28T13:44:55.746Z",
                "container_kind": "AdAccounts",
                "container_id": "8c545687-a599-4faa-a704-4b097c6da5fe",
                "member_id": "d051973d-32b2-496b-b44a-345986bce17d",
                "ad_account_id": "8c545687-a599-4faa-a704-4b097c6da5fe",
                "type": "creative"
            }
        }
    ]
}

The following API request creates an Ad Account role for the Member. Note that a prerequisite for an Ad Account role is for the Member to already have a member role in the Organization under which the Ad Account exists.

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/roles

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Delete Role

curl -X DELETE "https://adsapi.snapchat.com/v1/roles/5191aec7-b771-4c56-9963-126b14dbe2e3" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ea8338a00ff0ded779b7f217a0001737e616473617069736300016275696c642d36373239363666352d312d3334372d3000010130",
    "roles": []
}

The following API request removes a Role from an Organisation or Ad Account. If you are deleting the Member’s Organization Role, leaving the Member without any roles, you should also delete the Member from the Organization.

HTTP Request

DELETE https://adsapi.snapchat.com/v1/roles/{role_id}

Parameters

Parameter Default Description
role_id Role ID

Campaigns

A campaign has a business objective and organizes Ad Squads. You can define a goal and view stats for this campaign to see whether your goal has been reached. The reports and stats combines all the ad squads within this campaign.

Attributes

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
daily_budget_micro Daily Spend Cap (micro-currency) O
end_time End time O
name Campaign name R
start_time Start time R
status Campaign status R ACTIVE, PAUSED
lifetime_spend_cap_micro Lifetime spend cap for the campaign (microcurrency) O
measurement_spec The apps to be tracked for this campaign R - Required for tracking installs for campaigns containing these ad types: APP_INSTALL, DEEP_LINK, STORY (which swipes up to APP_INSTALL, DEEP_LINK) LENS_APP_INSTALL, LENS_DEEP_LINK {“ios_app_id”:“1234”, “android_app_url”:“com.snapchat.android”}
objective Objective of the Campaign O Default: BRAND_AWARENESS
buy_model** Buy Model O AUCTION(default), RESERVED
regulations++ Required for Campaigns that run Ads for Credit, Housing, Employment (CHE) O { “restricted_delivery_signals”: true }
regulations+- The candidate / ballot field is optional, but may be required in certain states O { “candidate_ballot_information”:“Voting rights for dogs” }
delivery_status Delivery status Read-only See Delivery status

** Coming soon. See Reach And Frequency

++ The regulations attribute alongside restricted_delivery_signals is required for Campaigns running Ads promoting Credit, Housing, Employment (CHE), this attribute has to be activated at Ad Account level first or it cannot be used at Campaign level; https://businesshelp.snapchat.com/en-US/a/create-ad-account

+- The regulations attribute alongside the candidate_ballot_information field is optional, but may be required in certain states The paying_advertiser attribute has to be activated at Ad Account level first or the candidate/ballot field cannot be used at Campaign level; https://businesshelp.snapchat.com/en-US/a/create-ad-account

To enable app install and post-install attribution on ads, the ‘measurement_spec’ field must be populated with the corresponding iOS and Android app IDs on campaign creation.

lifetime_spend_cap_micro can be increased and removed. Reducing the limit is allowed as long as the new limit is 1.1 times the amount already spent. daily_budget_micro set at the campaign level & the new lifetime_spend_cap_micro are evaluated independently. Delivery stops when either the Ad Account spend cap or the Campaign Lifetime spend cap is reached.

Create a Campaign

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/8adc3db7-8148-4fbf-999c-8d2266369d74/campaigns" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b003c700ff0f2e66c37f96c20001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010103",
  "campaigns": [
    {
      "sub_request_status": "success",
      "campaign": {
        "id": "06302efa-4c0f-4e36-b880-a395a36cef64",
        "updated_at": "2016-08-12T20:28:58.738Z",
        "created_at": "2016-08-12T20:28:58.738Z",
        "name": "Campaign One",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "daily_budget_micro": 200000000,
        "status": "ACTIVE",
        "start_time": "2016-08-10T17:12:49.707Z",
        "end_time": "2016-08-13T17:12:49.707Z"
      }
    },
    {
      "sub_request_status": "success",
      "campaign": {
        "id": "0fc8e179-6f3b-46e7-be8e-ca53fd404ece",
        "updated_at": "2016-08-12T21:06:18.343Z",
        "created_at": "2016-08-12T21:06:18.343Z",
        "name": "Campaign Deux",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "daily_budget_micro": 500000000,
        "status": "ACTIVE",
        "start_time": "2016-08-10T17:12:49.707Z",
        "end_time": "2016-08-13T17:12:49.707Z"
      }
    },

    [[[ snip ]]]

    {
      "sub_request_status": "success",
      "campaign": {
        "id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
        "updated_at": "2016-08-14T05:36:46.441Z",
        "created_at": "2016-08-14T05:33:33.876Z",
        "name": "Cool Campaign",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "status": "PAUSED",
        "start_time": "2016-08-11T22:03:58.869Z",
        "end_time": "2016-08-22T05:03:58.869Z"
      }
    },
    {
      "sub_request_status": "success",
      "campaign": {
        "id": "fedf8e04-0176-4ce3-a1ca-148204aee62c",
        "updated_at": "2016-08-12T02:18:33.412Z",
        "created_at": "2016-08-12T02:18:33.412Z",
        "name": "Crazy Campaign",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "start_time": "2016-08-11T22:03:58.869Z",
        "status": "PAUSED"
      }
    }
  ]
}

This endpoint retrieves all campaigns within a specified ad account.

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/campaigns

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Get a Specific Campaign

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 desired ROAS used with the MIN_ROAS BidStrategy R if BidStrategy = MIN_ROAS Minimum value 10000 , Maximum value 100000000
pixel_id Pixel to be associated with the Ad Squad O
measurement_provider_names approved measurement provider O MOAT_SS, DOUBLEVERIFY
reach_and_frequency_status** Status of the reach and frequency booking R Must be set to PENDING which automatically updates to ACTIVE or FAILED after booking
delivery_constraint Type of delivery R DAILY_BUDGET (when using daily_budget_micro), LIFETIME_BUDGET (when using lifetime_budget_micro), REACH_AND_FREQUENCY**
reach_and_frequency_status** Status of the reach and frequency booking R Must be set to PENDING which automatically updates to ACTIVE or FAILED after booking
reach_goal** Reach goal as specified in the Forecasting request R Must match the value in the forecasting request
impression_goal** Reach goal as specified in the Forecasting request R Must match the value in the forecasting request
pacing_type Type of pacing O STANDARD (default), ACCELERATED
delivery_status Delivery status Read-only See Delivery status

** See Reach And Frequency

Bid Strategy

Example request setting bid_strategy and bid_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, roas_value_micro value can be set between 10000 and a maximum of 100000000.
TARGET_COST Achieves the most volume while aiming to keep your average cost per action below your target cost use bid_micro to set bid

** The MIN_ROAS bid strategy requires 50 PURCHASE conversions within 7 days, the price parameter needs to be passed with the PURCHASE event and there needs to be at least 3 unique price values.

Optimization Goals allowed per Bid Strategy.

bid_strategy Optimization goals
AUTO_BID APP_INSTALLS, APP_PURCHASE, IMPRESSIONS, PIXEL_PURCHASE, STORY_OPENS, SWIPES, USES, VIDEO_VIEWS, VIDEO_VIEWS_15_SEC
LOWEST_COST_WITH_MAX_BID No restrictions
MIN_ROAS APP_PURCHASE
TARGET_COST APP_INSTALLS, WEB_VIEW, SWIPES, USES, VIDEO_VIEWS_15_SEC, PIXEL_PURCHASE, PIXEL_SIGNUP, PIXEL_PAGE_VIEW, PIXEL_ADD_TO_CART, APP_PURCHASE, APP_SIGNUP, APP_ADD_TO_CART, APP_REENGAGE_PURCHASE, APP_REENGAGE_OPEN, STORY_OPENS

MIN_ROAS examples

The Minimum ROAS (MIN_ROAS) bid strategy allows advertisers to define their desired ROAS in relation to the currency they are using within that Ad Account entity.

MIN_ROAS assumes the advertiser has implemented the in-app event APP_PURCHASE with the price parameter via their MMP. The roas_value_micro is used to define the expected ROAS and is defined in micro currency

Examples using “bid_strategy”:“MIN_ROAS”;

Placement V2

On the 20th of March 2020 we announced the deprecation of the placement attribute in favour of placement_v2, please ensure that you have switched to using placement_v2 by the 20th of June 2020. This also means that content targeting via included_content_types and excluded_content_types moves from the Ad Squad level attributes to the attributes inclusion and exclusion which are defined within placement_v2.

Your App will not be able to set or amend the placement attribute via Creation or Update requests for any Ad Squads past the 20th June 2020. Any AdSquads that have only the placement attribute set will continue to serve based on that setting post 20th June 2020

The below table outlines the relationship between placement and placement_v2.

placement placement_v2 - snapchat_positions
SNAP_ADS INTERSTITIAL_USER, INTERSTITIAL_CONTENT, INSTREAM
USER_STORIES INTERSTITIAL_USER
CONTENT INSTREAM
DISCOVER_FEED FEED
CAMERA CAMERA
- GAMES

Placement V2 Specification

Attribute Description Required Possible Values
config Configuration for placement R AUTOMATIC, CUSTOM
platforms The platform to place the ads O SNAPCHAT
snapchat_positions List of possible placement positions INTERSTITIAL_USER, INTERSTITIAL_CONTENT, INSTREAM, FEED, GAMES, CAMERA
inclusion Details about the content types to be included O {“content_types”: [List of possible content types]} Ad Squad must be of type SNAP_ADS. snapchat_positions must include INSTREAM. Inclusion and exclusion content types must be mutually exclusive NEWS, ENTERTAINMENT, SCIENCE_TECHNOLOGY, BEAUTY_FASHION, MENS_LIFESTYLE, WOMENS_LIFESTYLE, GAMING, GENERAL_LIFESTYLE, FOOD, SPORTS, YOUNG_BOLD
exclusion Details about the content types to be included O {“content_types”: [List of possible content types]}. Ad Squad must be of type SNAP_ADS. snapchat_positions must include INSTREAM. Inclusion and exclusion content types must be mutually exclusive NEWS, ENTERTAINMENT, SCIENCE_TECHNOLOGY, BEAUTY_FASHION, MENS_LIFESTYLE, WOMENS_LIFESTYLE, GAMING, GENERAL_LIFESTYLE, FOOD, SPORTS, YOUNG_BOLD

Placement v2 gives advertisers more options and control over the location and context of where ads are placed, and includes all the advanced placement options that Snapchat has to offer. The inclusion and exclusion attributes within placement_v2 replaces the previously used included_content_types and included_content_types attributes which were defined at Ad Squad level.

config

Value Description
AUTOMATIC Snapchat will choose the optimal placement for your ad across all of Snapchat and the Audience Extension. All the other properties in placement_v2 cannot be provided
CUSTOM Advertiser will chose all the settings for the placement. platforms must contain a value and snapchat_positions must not be empty

snapchat_positions

Value Description
INTERSTITIAL_USER Ads run between friend stories. Ad Squad type must be SNAP_ADS
INTERSTITIAL_CONTENT Ads run before and after stories in publisher and our stories. Ad Squad type must be SNAP_ADS
INSTREAM Ads run inside i.e. in between stories in publisher and our stories. Ad Squad type must be SNAP_ADS
FEED “Tile-based” ads. Currently, only in Discover feed. Ad Squad type must be SNAP_ADS. Ad type must be STORY
CAMERA Ads run in Filter or Lens carousel. Ad Squad type should either be LENS or FILTER
GAMES Ads run as Commercials within Snap Games. Ad Squad type must be SNAP_ADS
AUDIENCE_EXTENSION Ads run in the Snapchat Audience Network, this feature is currently in closed Beta

Example

{
 "config": "CUSTOM",
 "platforms": [
 "SNAPCHAT",
 ],
 "snapchat_positions": [
 "INTERSTITIAL_USER",
 "INSTREAM"
 ],
 "inclusion": {
 "content_types": [
 "BEAUTY"
 ]
}

placement_v2 config Examples for different types of Ad Squads based on Ad type

Example 1

Snap Ads running with Automatic placement

"placement_v2": {
  "config": "AUTOMATIC"
},

Example 2

Snap Ads running between User stories only

"placement_v2": {
  "config": "CUSTOM",
  "platforms": [
    "SNAPCHAT"
  ],
  "snapchat_positions": [
    "INTERSTITIAL_USER"
  ]
},

Example 3

Snap Ads running between User stories and Curated content

"placement_v2": {
  "config": "CUSTOM",
  "platforms": [
    "SNAPCHAT"
  ],
  "snapchat_positions": [
    "INTERSTITIAL_CONTENT",
    "INTERSTITIAL_USER"
  ]
},

Example 4

Snap Ads running inside of curated content

"placement_v2": {
  "config": "CUSTOM",
  "platforms": [
    "SNAPCHAT"
  ],
  "snapchat_positions": [
    "INSTREAM"
  ]
},

Example 5

Snap Ads running as commercials via premium content bundle

"placement_v2":{
  "config":"CUSTOM",
  "platforms":[
    "SNAPCHAT"
  ],
  "snapchat_positions":[
    "INSTREAM"
  ],
  "inclusion":{
  "premium_content_bundle_ids":[
    "c7e251af-3606-4f03-91f1-98456161655d"
  ]
},

Example 6

Snap Ads running as commercials via premium content bundle and Snap Games

"placement_v2":{
  "config":"CUSTOM",
  "platforms":[
    "SNAPCHAT"
  ],
  "snapchat_positions":[
    "INSTREAM",
    "GAMES"
  ],
  "inclusion":{
  "premium_content_bundle_ids":[
    "c7e251af-3606-4f03-91f1-98456161655d"
  ]
},

Example 7

Story Ad running in the Discover feed

"placement_v2": {
  "config": "CUSTOM",
  "platforms": [
    "SNAPCHAT"
  ],
  "snapchat_positions": [
    "FEED"
  ]
},

Example 8

Lens/Filter Ad placed in the Camera

"placement_v2": {
  "config": "CUSTOM",
  "platforms": [
    "SNAPCHAT"
  ],
  "snapchat_positions": [
    "CAMERA"
  ]
},

Pacing Types

Validations

If pacing_type is set to ACCELERATED for accelerated delivery the following validations apply:

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:

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.

  1. Ad Squads that use ad scheduling must have a lifetime_budget_micro set instead of a daily_budget_micro
  2. The schedule set in ad_scheduling_config cannot conflict with the flight dates of the Ad Squad
  3. Ad Squads should have a minimum interval of 1 hour across any day they select to run on
  4. 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.
  5. Ad scheduling is mutable
  6. 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*
delivery_status Delivery status Read-only See Delivery status

Ad Type <-> Creative Type Mapping

Ad Type Allowed Creative Type
APP_INSTALL APP_INSTALL
LONGFORM_VIDEO LONGFORM_VIDEO
SNAP_AD SNAP_AD (aka top snap only)
REMOTE_WEBPAGE WEB_VIEW
DEEP_LINK DEEP_LINK
STORY COMPOSITE
AD_TO_LENS AD_TO_LENS
AD_TO_CALL AD_TO_CALL
AD_TO_MESSAGE AD_TO_MESSAGE
FILTER FILTER
LENS LENS
LENS_REMOTE_WEBPAGE LENS_WEB_VIEW
LENS_APP_INSTALL LENS_APP_INSTALL
LENS_DEEP_LINK LENS_DEEP_LINK
LENS_LONGFORM_VIDEO LENS_LONGFORM_VIDEO
COLLECTION COLLECTION

Create an Ad

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

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 a Campaign

curl "https://adsapi.snapchat.com/v1/campaigns/77b217e4-7a2c-455b-9fd6-02a55c924177/ads" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f8453bc00ff0d27cde61b08060001737e616473617069736300016275696c642d32626566663136392d312d3339322d3000010102",
    "paging": {},
    "ads": [
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "0bfdb79e-38cc-470f-8593-789b51b83c97",
                "updated_at": "2018-09-12T18:11:00.831Z",
                "created_at": "2018-09-12T18:02:25.767Z",
                "name": "Fur Coat Shine",
                "ad_squad_id": "7fc34710-1c46-417e-bfc6-c4d5696aac4f",
                "creative_id": "7ef92e04-e99f-4e22-9496-5cc82b129c77",
                "status": "ACTIVE",
                "type": "APP_INSTALL",
                "render_type": "STATIC",
                "review_status": "APPROVED",
                "approval_type": "FULL",
                "delivery_status": [
                    "VALID"
                ]
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "54d00642-58bb-4db4-8a04-84ffd56258f7",
                "updated_at": "2018-08-31T16:34:37.673Z",
                "created_at": "2018-08-31T15:36:57.096Z",
                "name": "Fur coat conditioner",
                "ad_squad_id": "71ca9842-4628-4660-9ba3-3be2e7d15778",
                "creative_id": "348e9545-5706-4ff6-8701-2971db6e0017",
                "status": "ACTIVE",
                "type": "APP_INSTALL",
                "render_type": "STATIC",
                "review_status": "APPROVED",
                "approval_type": "FULL",
                "delivery_status": [
                    "VALID"
                ]
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "d1e3c618-b4a0-46ec-8982-b3b357c35507",
                "updated_at": "2018-08-31T15:48:52.200Z",
                "created_at": "2018-08-31T13:43:41.986Z",
                "name": "Claw polish",
                "ad_squad_id": "71ca9842-4628-4660-9ba3-3be2e7d15778",
                "creative_id": "e261479b-4f2b-443f-8fde-583816fb0167",
                "status": "ACTIVE",
                "type": "APP_INSTALL",
                "render_type": "STATIC",
                "review_status": "APPROVED",
                "approval_type": "FULL",
                "delivery_status": [
                    "VALID"
                ]
            }
        }
    ]
}

This endpoint retrieves all Ads under a specified Campaign.

HTTP Request

GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/ads

Parameters

Parameter Default Description
campaign_id Campaign ID

Get All Ads under an Ad Account

curl "https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/ads" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b01b3400ff0608a82948df6b0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
  "ads": [
    {
      "sub_request_status": "success",
      "ad": {
        "id": "2ded6d53-0805-4ff8-b984-54a7eb5c8918",
        "updated_at": "2016-08-14T07:18:05.699Z",
        "created_at": "2016-08-14T07:18:05.699Z",
        "name": "Ad Two",
        "ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
        "creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
        "status": "PAUSED",
        "type": "SNAP_AD"
      }
    },
    {
      "sub_request_status": "success",
      "ad": {
        "id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
        "updated_at": "2016-08-14T07:14:45.174Z",
        "created_at": "2016-08-14T07:07:50.241Z",
        "name": "Ad One",
        "ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
        "creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
        "status": "ACTIVE",
        "type": "SNAP_AD"
      }
    }
  ]
}

This endpoint retrieves all Ads under a specified Ad account.

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/ads

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Get a Specific Ad

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
on_swipe_tracking_urls DEPRECATED, Use attribute third_party_on_swipe_tracking_urls -
third_party_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
sn.moatads.com DEPRECATED, Use AdSquad level tracking activation

How to get tags

Notes

URL Macros

There are several dynamic placeholder macros that can be used within the URL that are replaced on-the-fly:

Macro Description
~.~SERVER_ORG_ID~.~ Organization ID
~.~SERVER_AD_ACCOUNT_ID~.~ Ad Account ID
~.~SERVER_CAMPAIGN_ID~.~ Campaign ID
~.~SERVER_AD_SQUAD_ID~.~ Ad Squad ID
~.~SERVER_CREATIVE_ID~.~ Creative ID
~.~SERVER_AD_ID~.~ Ad ID
~.~SERVER_MOAT_PRODUCT_TYPE~.~ Ad Product Type
~.~TIMESTAMP~.~ Timestamp

Media

Media is a single video that can be used to construct Creative. Media objects are owned by an Ad Account and can be used by multiple Creatives simultaneously.

Attributes

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
download_link URL to Media File READ-ONLY
media_status Media Status READ-ONLY PENDING_UPLOAD, READY
name Media name R
type Media Type R VIDEO, IMAGE, LENS_PACKAGE
lens_package_metadata Metadata for lens media created by Lens Studio READ-ONLY

Create Media

curl -X POST  \
  -d '{"media": [{"name":"Media A - Video", "type":"VIDEO","ad_account_id":"{ad_account_id}"}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/media

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b00d1900ff08a0dae50ab27a0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010b",
  "media": [
    {
      "sub_request_status": "success",
      "media": {
        "id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "updated_at": "2016-08-14T06:18:01.855Z",
        "created_at": "2016-08-14T06:18:01.855Z",
        "name": "Media A - Video",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "VIDEO",
        "media_status": "PENDING_UPLOAD"
      }
    }
  ]
}

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/media

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Upload Media - Video

Name Description Dimensions File size File type Length seconds
Top Snap Used as Top Snap video in Snap Ads, Top Snap specs min 1080 x 1920 px , aspect ratio 9:16 32MB max size , up to 1 GB allowed using chunked upload mp4, mov min 3 seconds, max 180 seconds
Long form video Used for Long form video attachment, Long Form video attachment specs min width 1080 px 32MB max size , up to 1 GB allowed using chunked upload mp4, mov min 15 seconds
curl -X POST -H 'content-type: multipart/form-data' -F 'file=@"/files/MOV_1808.mov";filename="MOV_1808.mov"' \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/media/a7bee653-1865-41cf-8cee-8ab85a205837/upload

The above command returns JSON structured like this:

{
  "result": {
    "id": "a7bee653-1865-41cf-8cee-8ab85a205837",
    "updated_at": "2016-08-14T06:24:28.378Z",
    "created_at": "2016-08-14T06:23:37.086Z",
    "name": "Media A - Video",
    "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
    "type": "VIDEO",
    "media_status": "READY",
    "file_name": "sample.mov"
  },
  "request_status": "success",
  "request_id": "57b00e9a00ff0ccb4293400c840001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010103"
}

This endpoint receives the actual video data for the media. Snap Inc. hosts all media on behalf of the advertiser.

HTTP Request

POST https://adsapi.snapchat.com/v1/media/{media_id}/upload

Parameters

Parameter Default Description
media_id Media ID

Upload Media - Image

Media of the type IMAGE can be used in various different types of Creatives.

Name Description Dimensions File size File type
Top Snap Image Used as Top Snap in Snap Ads, IMAGE type top snaps are converted into 5 sec videos and rendered on the client as videos, Top Snap specs min 1080 x 1920 px 5 MB max size PNG, JPG
App Icon Used for App Install and Deep Link creatives, image shouldn’t have any borders or padding, App Install attachment specs , Deep Link attachment specs aspect ratio 1:1 (square), min 200 x 200 px, max 2000 x 2000 px - PNG
Preview Image Used as Thumbnail in Story Ad Creatives, Story Ad specs aspect ratio 3:5, min 360 x 600 px 2 MB max size PNG
Logo Image Used as Logo overlaid on Thumbnail in Story Ad Creatives, Story Ad specs 993 x 284 px 2 MB max size PNG
Audience Filter Used as Filter, at least 50% of the image must be transparent, Filter specs 1080 x 2340 px 300kb or less PNG

Supported Optimization goals for ads using IMAGE type media are: IMPRESSIONS, SWIPES, APP_INSTALLS

curl -X POST -H 'content-type: multipart/form-data' -F 'file=@"/files/app_icon.png";filename="app_icon.png"' \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/media/8adc3db7-8148-4fbf-999c-8d2266369d75/upload

The above command returns JSON structured like this:

{
  "result": {
    "id": "77062ed3-4abf-49a8-ac3f-8157cf14cb41",
    "updated_at": "2017-04-14T19:39:05.969Z",
    "created_at": "2017-04-14T19:19:59.708Z",
    "name": "IMAGE media",
    "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d75",
    "type": "IMAGE",
    "media_status": "READY",
    "file_name": "app_icon.png",
    "download_link": "https://storage.googleapis.com/ad-manager-creatives-production/77062ed3-4abf-49a8-ac3f-8157cf14cb41/7d935b22-eb12-41b8-9e34-713b64f2e3b3.png"
  },
  "request_status": "SUCCESS",
  "request_id": "58f1255800ff0d03cc7c0c03380001737e616473617069736300016275696c642d64373565633561632d312d35382d3100010"
}

HTTP Request

POST https://adsapi.snapchat.com/v1/media/{media_id}/upload

Parameters

Parameter Default Description
media_id Media ID

Upload Large Media (Chunked)

This endpoint receives the actual video data for the media. Snapchat hosts all media on behalf of the advertiser.

Files larger than 32MB need to be uploaded in chunks.

  1. Split the large file
  2. Initialize a chunked upload request
  3. Get the “add_path”, “finalize_path” and “upload_id” from the response, these will be unique to your upload
  4. Upload all parts of the file using the “add_path” , you will need to prepend it with https://adsapi.snapchat.com
  5. Finalize the chunked upload request using the “finalize_path”, you will need to prepend it with https://adsapi.snapchat.com

Request and Parameters for INIT

POST https://adsapi.snapchat.com/v1/media/{media_id}/multipart-upload-v2?action=INIT

Parameter Description
action INIT (query param)
file_name File Name
file_size Total file size in bytes (cannot exceed 1GB)
number_of_parts Number of parts to expect

Request and Parameters for ADD

POST https://adsapi.snapchat.com + add_path

Parameter Description
file File Part
part_number File part number, used during re-assembly of file
upload_id Chunked Upload ID from INIT

Request and Parameters for FINALIZE

POST https://adsapi.snapchat.com + finalize_path

Parameter Description
upload_id Chunked Upload ID from INIT

1. Split the large file

Example: split -b 2m lfv.mov split_lfv.

2. Initialize a chunked upload request

curl -X POST -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: multipart/form-data" \
  -F "file_name=lfv.mov" \
  -F "file_size=4887527" \
  -F "number_of_parts=3" \
  "https://adsapi.snapchat.com/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=INIT"

3. Extract upload_id, add_path and finalize_path from response:

  {
    "request_status":"SUCCESS",
    "request_id":"57e56c0b00ff0e1b43229b96350001737e616473617069736300016275696c642d62646338336131372d312d31352d3100010109",
    "upload_id":"cffc3975-f2b3-40d2-bf81-f0e7d97b9af5",
    "add_path":"/us/v1/media/7bd44f53-5de7-41c4-90c7-50633e5dbb7e/multipart-upload-v2?action=ADD",
    "finalize_path":"/v1/media/7bd44f53-5de7-41c4-90c7-50633e5dbb7e/multipart-upload-v2?action=FINALIZE"
  }

4. Upload all parts using the add_path prepended with https://adsapi.snapchat.com:

curl -X POST -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: multipart/form-data" \
  -F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
  -F "file=@split_lfv.aa" \
  -F "part_number=1" \
  "https://adsapi.snapchat.com/us/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=ADD"

curl -X POST -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: multipart/form-data" \
  -F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
  -F "file=@split_lfv.ab" \
  -F "part_number=2" \
  "https://adsapi.snapchat.com/us/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=ADD"

curl -X POST -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: multipart/form-data" \
  -F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
  -F "file=@split_lfv.ac" \
  -F "part_number=3" \
  "https://adsapi.snapchat.com/us/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=ADD"


5. Finalize the chunked upload request using finalize_path prepended with https://adsapi.snapchat.com

curl -X POST -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: multipart/form-data" \
  -F "upload_id=9fc6e22f-6735-4eda-96be-657d8c66e10f" \
  "https://adsapi.snapchat.com/v1/media/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/multipart-upload-v2?action=FINALIZE"

The above command returns JSON structured like this:

{
  "result": {
    "id": "7536bbc5-0074-4dc4-b654-5ba9cd9f9441",
    "updated_at": "2016-09-23T17:59:23.826Z",
    "created_at": "2016-09-23T17:51:07.799Z",
    "name": "Media Chunked - Video",
    "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
    "type": "VIDEO",
    "media_status": "READY",
    "file_name": "lfv.mov",
    "download_link": "https://storage.googleapis.com/ad-manager-creatives-production-us/7536bbc5-0074-4dc4-b654-5ba9cd9f9441/b195bd7c-aa7b-44c4-83a5-2c12e77a8784.mov"
  },
  "request_status": "SUCCESS",
  "request_id": "57e56d7a00ff0b82bd232ea3d40001737e616473617069736300016275696c642d62646338336131372d312d31352d3100010134"
}

Get All Media

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get()
curl "https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/media" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b00ee800ff0a7e553a9389710001737e616473617069736300016275696c642d35396264653638322d312d31312d37000100",
  "media": [
    {
      "sub_request_status": "success",
      "media": {
        "id": "7f65f9ff-63d8-41e7-991a-06b95a1ffbde",
        "updated_at": "2016-08-12T20:39:57.029Z",
        "created_at": "2016-08-12T20:39:57.029Z",
        "name": "Media 2",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "VIDEO",
        "media_status": "PENDING_UPLOAD"
      }
    },
    {
      "sub_request_status": "success",
      "media": {
        "id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "updated_at": "2016-08-14T06:24:28.378Z",
        "created_at": "2016-08-14T06:23:37.086Z",
        "name": "Media A - Video",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "VIDEO",
        "media_status": "READY",
        "file_name": "sample.mov"
      }
    },
    {
      "sub_request_status": "success",
      "media": {
        "id": "ab32d7e5-1f80-4e1a-a76b-3c543d2b28e4",
        "updated_at": "2016-08-12T17:38:01.918Z",
        "created_at": "2016-08-12T17:36:59.740Z",
        "name": "App Icon",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "IMAGE",
        "media_status": "READY",
        "file_name": "Mobile Strike.png"
      }
    }
  ]
}

This endpoint retrieves all media entities associated with an ad account.

HTTP Request

GET https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/media

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Get a Specific Media

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get(2)
curl "https://adsapi.snapchat.com/v1/media/a7bee653-1865-41cf-8cee-8ab85a205837" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b00f5f00ff0bd6909e4148c30001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010102",
  "media": [
    {
      "sub_request_status": "success",
      "media": {
        "id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "updated_at": "2016-08-14T06:24:28.378Z",
        "created_at": "2016-08-14T06:23:37.086Z",
        "name": "Media A - Video",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "VIDEO",
        "media_status": "READY",
        "file_name": "sample.mov"
      }
    }
  ]
}

This endpoint retrieves a specific media entity.

HTTP Request

GET https://adsapi.snapchat.com/v1/media/{media_id}

URL Parameters

Parameter Description
ID The ID of the media to retrieve

Get Preview for a Specific Media

curl "https://adsapi.snapchat.com/v1/media/8e781365-ce4c-4336-8c53-f6a1f7c50af1/preview" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5aa8450b00ff00ff741e879aff00580001737e816473617069736300016275696x642d37633033663563332d312d3134392d310001015e",
    "expires_at": "2018-03-14T21:39:23.303Z",
    "link": "https://adsapisc.appspot.com/media/video_preview?media_id=8e781365-ce4c-4336-8c53-f6a1f7c50af1&expires_at=1521063563303&signature=MGQCMA1DRI6uBax3GSq93E8hp5b3P2Ebg0lIlPa8iGML9rs1B9WFmPeHH6ttvx_rmDG5AgIwY0pjIvEEpwOXM8o3h9Hst60DjRN9Mw7am7OmkdrBGfoI4IiHBflv0XpK87Tnb_BE"
}

This endpoint retrieves the preview for a specific media, this request only works on Media which is of the type VIDEO/IMAGE.

HTTP Request

GET https://adsapi.snapchat.com/v1/media/{media_id}/preview

URL Parameters

Parameter Description
ID The ID of the media to retrieve, can only be of type VIDEO/IMAGE

Get Thumbnail for a Specific Media

curl "https://adsapi.snapchat.com/v1/media/095a4a6d-01a0-4f6a-8901-41ea38c7a540/thumbnail" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5b99772a00ff06928d3e31e94b0001737e616473617069736300016275696c642d33346634346232622d312d3230302d3200010154",
    "expires_at": "2018-09-13T20:29:30.555Z",
    "link": "https://adsapisc.appspot.com/media/video_thumbnail?media_id=095a4a6d-01b0-4f6c-8901-41ee38c7b540&expires_at=1536870570555&signature=MGQCMBQ_NfJM0yZCrdyLiEon4Lkbei0zFJF2HpLiHa2NvSLV2JyOVhLqHfQgqbDWUuzaCQIwHzPj_ZFtPNk688SoFiKWUIFEKKBMhSm8t4moy9xlfgnoSv-8LMQ1omM_P8QCj7O9"
}

This endpoint retrieves a thumbnail for media of the type VIDEO Thumbnails cannnot be fetched for other Media types (IMAGE, LENS_PACKAGE).

HTTP Request

GET https://adsapi.snapchat.com/v1/media/{media_id}/thumbnail

URL Parameters

Parameter Description
ID The ID of the media (type VIDEO) to retrieve a thumbnail from

Creatives

A Creative is the combination of one or more pieces of media. Creative is owned by an Ad Account and can be used by multiple Ads simultaneously.

See dedicated sections for examples on how to set up and launch FILTER and LENS creatives.

Attributes

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
brand_name Brand Name R 25 characters max
call_to_action Call to Action O BLANK, INSTALL_NOW, WATCH, VIEW_MORE
headline Headline (displayed under brand name) R 34 characters max
shareable Allow Users to Share with Friends O true (default), false
name Creative name R
top_snap_media_id Top Snap Media ID R
top_snap_crop_position Top Snap Crop Position O OPTIMIZED (default), MIDDLE, TOP, BOTTOM
type Creative Type R SNAP_AD, APP_INSTALL, LONGFORM_VIDEO, WEB_VIEW, DEEP_LINK, AD_TO_LENS, AD_TO_CALL, AD_TO_MESSAGE, PREVIEW, COMPOSITE, FILTER, LENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_LONGFORM_VIDEO, COLLECTION
forced_view_eligibility Indicates whether Creative can be used as a Commercial O FULL_DURATION, SIX_SECONDS, NONE
preview_creative_id ID of the preview creative R (For Story Ads)
playback_type Specifies whether the creatives within the composite auto-advance or loop O AUTO_ADVANCING (default), LOOPING
ad_product Type of Ad Product Required only for R&F creatives SNAP_AD (default), LENS, FILTER

** LENS type will be available soon with Reach and Frequency buying. Please check Reach and Frequency guide for more details.

Creative Types and attachments

Creative Types

Name Creative type Description
Snap Ad SNAP_AD A Snap Ad comprised of a Top Snap only, latest Video/Image specs
Snap Ad with attachment APP_INSTALL, LONGFORM_VIDEO, WEB_VIEW, DEEP_LINK, AD_TO_LENS, AD_TO_CALL, AD_TO_MESSAGE See below for list of all attachments
Story Ad COMPOSITE Story Ad Creatives require a PREVIEW creative
Collection Ad COLLECTION
Lens LENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_LONGFORM_VIDEO See section on Lens creatives for specs and references
Filter FILTER See section on Filter creatives for specs and references

A basic Snap Ad is comprised of a top snap only. Snap Ads can be enhanced by using one of the following attachments:

Creative Type to Call To Actions Mapping

Creative type Call To Actions
APP_INSTALL BOOK_NOW, DONATE, DOWNLOAD, GET_NOW, INSTALL_NOW, ORDER_NOW, PLAY, SHOP_NOW, SIGN_UP, TRY, USE_APP, WATCH
LENS_APP_INSTALL BOOK_NOW, DONATE, DOWNLOAD, GET_NOW, INSTALL_NOW, ORDER_NOW, PLAY, SHOP_NOW, SIGN_UP, TRY, USE_APP, WATCH
DEEP_LINK DONATE, PLAY, SHOP_NOW, SIGN_UP, USE_APP, MORE, OPEN_APP, TRY, WATCH
LENS_DEEP_LINK DONATE, PLAY, SHOP_NOW, SIGN_UP, USE_APP, MORE, OPEN_APP, TRY, WATCH
LONGFORM_VIDEO WATCH, WATCH_EPISODE
LENS_LONGFORM_VIDEO DEEP_LINK, DONATE, WATCH, WATCH_EPISODE
WEB_VIEW APPLY_NOW, MORE, ORDER_NOW, PLAY, READ, SHOP_NOW, SHOW, SIGN_UP, VIEW, SHOW, WATCH, DONATE, DOWNLOAD, APPLY_NOW, ORDER_NOW, RESPOND, BUY_TICKETS, SHOWTIMES, BOOK_NOW, GET_NOW, LISTEN, TRY
LENS_WEB_VIEW APPLY_NOW, MORE, ORDER_NOW, PLAY, READ, SHOP_NOW, SHOW, SIGN_UP, VIEW, SHOW, WATCH, DONATE, DOWNLOAD, APPLY_NOW, ORDER_NOW, RESPOND, BUY_TICKETS, SHOWTIMES, BOOK_NOW, GET_NOW, LISTEN, TRY
AD_TO_LENS PLAY, TRY, SHOP_NOW
AD_TO_MESSAGE MESSAGE_NOW
AD_TO_CALL CALL_NOW
AD_TO_PLACE SEE_PLACE

Attachments

Name Creative type Description
Long Form video attachment LONGFORM_VIDEO Creative requires longform_video_properties
Web View attachment WEB_VIEW Creative requires web_view_properties
App Install attachment APP_INSTALL Creative requires app_install_properties
Deep Link attachment DEEP_LINK Creative requires deep_link_properties
Lens attachment AD_TO_LENS Creative requires ad_to_lens_properties
Call attachment AD_TO_CALL Creative requires ad_to_call_properties
Text attachment AD_TO_MESSAGE Creative requires ad_to_message_properties

Create a Snap Ad

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
brand_name Brand Name R 25 characters max
headline Headline (displayed under brand name) R 34 characters max
shareable Allow Users to Share with Friends O true (default), false
name Creative name R
top_snap_media_id Top Snap Media ID R
top_snap_crop_position Top Snap Crop Position O OPTIMIZED (default), MIDDLE, TOP, BOTTOM
type Creative Type R SNAP_AD
forced_view_eligibility Indicates whether Creative can be used as a Commercial, see Commercials section for instructions on how to determine and set this value O FULL_DURATION, SIX_SECONDS, NONE
curl -X POST  \
  -d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837", "name": "Creative Creative", "type": "SNAP_AD", "brand_name": "Maxiumum Brand", "headline": "Healthy Living", "shareable": true}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b0136f00ff085e3d63d358a20001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010108",
  "creatives": [
    {
      "sub_request_status": "success",
      "creative": {
        "id": "c1e6e929-acec-466f-b023-852b8cacc18f",
        "updated_at": "2016-08-14T06:45:04.300Z",
        "created_at": "2016-08-14T06:45:04.300Z",
        "name": "Creative Creative",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "SNAP_AD",
        "packaging_status": "PENDING",
        "review_status": "PENDING_REVIEW",
        "shareable": true,
        "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "top_snap_crop_position": "MIDDLE"
      }
    }
  ]
}

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Create a Snap Ad with Long form Video attachment

The Long Form video attachment opens up a video on swipe up, this video should be a minimum of 15 seconds long and can be up to 1 GB in size.

Attributes

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
brand_name Brand Name R 25 characters max
call_to_action Call to Action O WATCH, WATCH_EPISODE
headline Headline (displayed under brand name) R 34 characters max
shareable Allow Users to Share with Friends O true (default), false
name Creative name R
top_snap_media_id Top Snap Media ID R
top_snap_crop_position Top Snap Crop Position O OPTIMIZED (default), MIDDLE, TOP, BOTTOM
type Creative Type R LONGFORM_VIDEO
forced_view_eligibility Indicates whether Creative can be used as a Commercial, see Commercials section for instructions on how to determine and set this value O FULL_DURATION, SIX_SECONDS, NONE

Additional Attributes

The following attributes should be added to the basic creative under the property longform_video_properties.

Attribute Description Required Possible Values
video_media_id Long form video media ID R

This endpoint creates a Creative within an Ad Account.

curl -X POST \
  -d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837", "name": "Creative LFV", "type": "LONGFORM_VIDEO", "shareable": true, "call_to_action": "WATCH", "longform_video_properties": {"video_media_id": "911dd85e-1de4-4460-a8ed-2d595226da01"}}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b015bb00ff098ecdd8a6be5c0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010c",
  "creatives": [
    {
      "sub_request_status": "success",
      "creative": {
        "id": "313e8415-6294-47d6-b064-5a0d9f21d224",
        "updated_at": "2016-08-14T06:54:52.107Z",
        "created_at": "2016-08-14T06:54:52.107Z",
        "name": "Creative LFV 2",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "LONGFORM_VIDEO",
        "packaging_status": "PENDING",
        "review_status": "PENDING_REVIEW",
        "shareable": true,
        "call_to_action": "WATCH",
        "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "top_snap_crop_position": "MIDDLE",
        "longform_video_properties": {
          "video_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837"
        }
      }
    }
  ]
}

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/creatives

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Create a Snap Ad with App Install attachment

App Install attachments allow users to swipe up and download the advertised app.

Attributes

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
brand_name Brand Name R 25 characters max
call_to_action Call to Action O BOOK_NOW, 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

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

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

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 MESSAGE_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_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 CALL_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_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, phone number or mobile identifier.

This endpoint will add users to the specified Snap Audience Match Segment using either a single key/identifier per user. We do not accept multiple type of schemas in one request, you need to pass only one schema type with the request, but this needs to happen via a LIST

Identifiers should be grouped in batches of a maximum of 100,000 identifiers/request.

Attributes

Attribute Description Required Possible Values
id Segment ID R
schema List of one type of Schema R EMAIL_SHA256, MOBILE_AD_ID_SHA256, PHONE_SHA256
data List of hashed identifiers R max 100,000 identifiers/request

HTTP Request

POST https://adsapi.snapchat.com/v1/segments/{segment_id}/users

Parameters

Parameter Default Description
segment_id Segment ID

Normalizing & Hashing

Each raw identifier (plain text email or mobile identifier) must be normalized before being hashed.

Normalizing Identifiers

Phone normalization example Before normalization After normalization Action
US phone number example 001-234-567-8910 12345678910 00 of country code and ‘-’ characters removed
UK phone number example +44 844 412 4653 448444124653 Initial 0 of number, whitespaces and ‘+’ character removed

Hashing Identifiers

Hash raw identifiers with lowercase hex SHA256 format.

Adding Users (Single-Key)

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{"users":[{"id": "5132209967071232", "schema":["EMAIL_SHA256"],"data":[["c3a75685a45a565954512a7f006b691b5e06c0efe6ac28bd5c09e84bbe022b55"],["5b5fbfe6a42915ca4d0f11620e76abd1a4ac621bcca95395ce3b6b11ec01bef6"]]}]}' \
   "https://adsapi.snapchat.com/v1/segments/{segment_id}/users"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "57c4d34700ff0d538b8ba40ed90001737e7465616d6b6f363139000173616d2d68616f6d696e672d757365722d746573740001010c",
  "users": [
    {
      "sub_request_status": "SUCCESS",
      "user": {
        "number_uploaded_users": 2
      }
    }
  ]
}

This example uses a single key/identifier per user.

Removing Users

Users can also be removed from the segment at any time. The API supports matching via email, phone number or mobile identifier. You can send a maximum of 100,000 identifiers / request.

This endpoint will remove users from the specified Snap Audience Match segment using a single key/identifier per user. We do not accept multiple type of schemas in one request, you need to pass only one schema type with the request , but this needs to happen via a LIST.

Identifiers should be grouped in batches of a maximum of 100,000 identifiers/request.

Attributes

Attribute Description Required Possible Values
id Segment ID R
schema List of one type of Schema R EMAIL_SHA256, MOBILE_AD_ID_SHA256, PHONE_SHA256
data List of hashed identifiers R max 100,000 identifiers/request

HTTP Request

DELETE https://adsapi.snapchat.com/v1/segments/{segment_id}/users

Parameters

Parameter Default Description
segment_id Segment ID

Removing Users (Single-Key)

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
curl -X DELETE \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{"users":[{"id": "5132209967071232", "schema":["EMAIL_SHA256"],"data":[["c3a75685a45a565954512a7f006b691b5e06c0efe6ac28bd5c09e84bbe022b55"],["5b5fbfe6a42915ca4d0f11620e76abd1a4ac621bcca95395ce3b6b11ec01bef6"]]}]}' \
   "https://adsapi.snapchat.com/v1/segments/{segment_id}/users"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "57c4d34700ff0d538b8ba40ed90001737e7465616d6b6f363139000173616d2d68616f6d696e672d757365722d746573740001010c",
  "users": [
    {
      "sub_request_status": "SUCCESS",
      "user": {
        "number_uploaded_users": 2
      }
    }
  ]
}

This example uses a single key/identifier per user.

Remove All Users from a Segment

This endpoint allows you to remove all the users from a specified Snap Audience Match segment

HTTP Request

DELETE https://adsapi.snapchat.com/v1/segments/{segment_id}/all_users

Parameters

Parameter Default Description
segment_id Segment ID

Remove All Users

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
curl -X DELETE \
  -H "Authorization: Bearer meowmeowmeow" \
   "https://adsapi.snapchat.com/v1/segments/{segment_id}/all_users"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "58af318900ff0cb66aa3a103dd0001737e616473617069736300016275696c642d61666139346564352d312d34342d3000010109",
  "segments": [
    {
      "sub_request_status": "SUCCESS",
      "segment": {
        "id":"5769345128988888",
        "updated_at":"2017-02-23T19:01:30.080Z",
        "created_at":"2017-02-23T18:34:48.900Z",
        "name":"super duper sam",
        "ad_account_id":"8adc3db7-8148-4fbf-999c-8d1111111d11",
        "description":"all the sams in the world",
        "status":"ACTIVE",
        "source_type":"FIRST_PARTY",
        "retention_in_days":180,
        "approximate_number_users":0
      }
    }
  ]
}

Delete an Audience Segment

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
curl -X DELETE \
  -H "Authorization: Bearer meowmeowmeow" \
   "https://adsapi.snapchat.com/v1/segments/{segment_id}"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5b994e4900ff02dce52463d1020001737e616473617069736300016275696c642d33346634346232622d312d3230302d32000100",
    "segments": []
}

This endpoint will delete the Audience Segment with the corresponding segment id.

HTTP Request

DELETE https://adsapi.snapchat.com/v1/segments/{segment_id}

Parameters

Parameter Default Description
segment_id Segment ID

SAM - Lookalikes

A Lookalike segment can be created from a first-party seed Snap Audience Match Segment. The segment can be used to target or exclude a specific group of users that “behave like” the seed audience segment.

If the original seed Segment has new identfiers added to it, the Lookalike segment will also be updated with new users.

Attributes

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
creation_spec Lookalike Creation Spec dictionary R (see below)
description Audience Segment Description O
name Audience Segment name R
retention_in_days # of days to retain audience members R (Max 180)
source_type Data source type R LOOKALIKE

Creation Spec Details

Attribute Description Required Possible Values
seed_segment_id Seed Audience Segment ID R
type The type of Lookalike to be created O BALANCE (default), SIMILARITY, REACH
countries List of ISO-2 Country Code R [“UK”, “US”] OR [“US”] etc
country [Deprecated] ISO-2 Country Code R

Create an Lookalike Segment

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()
curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{"segments": [{"name": "lookalikes of all the sams in the world", "description": "similar to all the sams in the world", "source_type": "LOOKALIKE", "retention_in_days": 180, "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "creation_spec":{"seed_segment_id": "5677923948298240", "country": "US", "type": "REACH"}}]}' \
   "https://adsapi.snapchat.com/v1/adaccounts/{ad_acount_id}/segments"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "57e18036000733c0f1abd670",
  "segments": [
    {
      "sub_request_status": "SUCCESS",
      "segment": {
        "id": "5652536396611584",
        "updated_at": "2016-09-20T11:30:15.448-07:00",
        "created_at": "2016-09-20T11:30:15.429-07:00",
        "name": "lookalikes of all the sams in the world",
        "ad_account_id": "d47d2516-4f1f-46f0-a63c-31a46804c3aa",
        "description": "similar to all the sams in the world",
        "status": "ACTIVE",
        "source_type": "LOOKALIKE",
        "retention_in_days": 180,
        "approximate_number_users": 0,
        "creation_spec": {
          "seed_segment_id": "5677923948298240",
          "country": "US"
          "type": "REACH"
        }
      }
    }
  ]
}

This endpoint will create a Snap Audience Match Lookalike Segment within a specified ad account.

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/segments

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Example Targeting Specs

Targeting Spec Examples for an Ad Squad

Example 1

United States, Male+Female, All Age Ranges

You can target both Male and Female by leaving out GENDER from the targeting spec.

{
  "geos": [{
    "country_code": "us"
  }]
}

Example 2

United States, Male, Age Groups 21-34

{
  "geos": [{
    "country_code": "us"
  }],
  "demographics": [{
    "age_groups": [
      "21-24",
      "25-34"
    ],
    "gender": "MALE"
  }]
}

Example 3

Canada, Female, 13-20, iOS

{
  "demographics": [{
    "min_age": 13,
    "max_age": 20,
    "gender": "FEMALE"
  }],
  "geos": [{
    "country_code": "ca"
  }],
  "devices": [{
    "os_type": "iOS"
  }]
}

Example 4

UK, Male+Female, Age 25, WIFI Only

{
  "demographics": [{
    "min_age": 25,
    "max_age": 25
  }],
  "geos": [{
    "country_code": "uk"
  }],
  "devices": [{
    "connection_type": "WIFI"
  }]
}

Example 5

United States - All States Except Arizona or Texas, M+F, All Ages

{
  "geos": [{
    "country_code": "us"
  }, {
    "country_code": "us",
    "region_id": ["3", "44"],
    "operation": "EXCLUDE"
  }]
}

Example 6

United States, Female, 18-34, “Fashion & Style Gurus” OR “Film & TV Fans”

{
  "demographics": [{
    "gender": "FEMALE",
    "age_groups": [
      "18-20",
      "21-24",
      "25-34"
    ]
  }],
  "interests": [{
    "category_id": ["SLC_7", "SLC_8"]
  }],
  "geos": [{
    "country_code": "us"
  }]
}

Example 7

United States, All genders/ages, “Comedy Fans”

{
  "interests": [{
    "category_id": ["SLC_36"]
  }],
  "geos": [{
    "country_code": "us"
  }]
}

Example 8

United States, Male, 18-20, member of SAM segment ID “12345”

{
  "demographics": [{
    "gender": "MALE",
    "age_groups": [
      "18-20"
    ]
  }],
  "geos": [{
    "country_code": "us"
  }],
  "segments": [{
    "segment_id": ["12345"]
  }]
}

Example 9

United States, Male, 18-20, NOT a member of SAM segment ID “98765”

{
  "demographics": [{
    "gender": "MALE",
    "age_groups": [
      "18-20"
    ]
  }],
  "geos": [{
    "country_code": "us"
  }],
  "segments": [{
    "segment_id": ["98765"],
    "operation": "EXCLUDE"
  }]
}

Example 10

United States, AT&T

{
  "geos": [{
    "country_code": "us"
  }],
  "devices": [{
    "carrier_id": ["US_ATT"]
  }]
}

Example 11

United States, 21-24, (College Graduates OR Married People), Apparel Shoppers

{
  "regulated_content": "false",
  "demographics": [{
    "age_groups": [
      "21-24"
    ],
    "advanced_demographics": [
      "DLXD_100",
      "DLXD_300"
    ]
  }],
  "geos": [{
    "country_code": "us"
  }],
  "interests": [{
    "category_id": ["DLXS_1"]
  }]
}

Example 12

United States, metros New York or Los Angeles only

{
  "geos": [{
    "country_code": "us", 
    "metro_id": ["501", "803"]
  }]
}

Example 13

USA, Female, Spanish speaking, 13-17, iOS version 10.3.2

{
  "demographics": [{
    "age_groups": [
      "13-17"
    ],
    "gender": "FEMALE",
    "languages": ["es"]
  }],
  "geos": [{
    "country_code": "us"
  }],
  "devices": [{
    "os_type": "iOS",
    "os_version_min": "9.0",
    "os_version_max": "10.3.2"
  }]
}

Example 14

Zipcode Targeting

{
  "geos": [{
    "country_code": "us", 
    "postal_code": ["90291", "90026"]
  }]
}

Example 15

Device Make: All iPhone 7 plus and iPhone 6s Plus users

{
  "devices": [{
    "marketing_name": ["Apple/iPhone 7 Plus/", "Apple/iPhone 6s Plus/"]
  }]
}

Example 16

Location Categories: Targeting Sports Arenas, Fitness Centers

{
  "locations": [
    {
      "location_type": [
        "LOI_15004", // Sports Stadiums and Arenas
        "LOI_15002"  // Gyms and Fitness Centers
      ],
      ,
      "proximity_unit": "MILES", // Proximity in miles
      "proximity": 1
    }
  ]
}

Example 17

Location Point Radius: Targeting 500 meter radius around Nordstrom locations in Seattle/Bellevue

{
  "locations": [
    {
      "circles": [
        {
          "latitude": 47.612447,
          "longitude":  -122.336751,
          "radius": 500
        },
        {
          "latitude": 47.617102, 
          "longitude": -122.203961,
          "radius": 50,
          "unit": "KILOMETERS"
        }
      ],
      "operation": "INCLUDE"
    }
  ]
}

Example 18

Multi-country targeting: Targeting the US and Canada

{
  "geos": [
            {
              "country_code": "us",
              "operation": "INCLUDE"
            },
            {
              "country_code": "ca",
              "operation": "INCLUDE"
            }
          ]
}

Example 19

Snap Lifestyle Category inclusion of SLC_1, SLC_124 and exclusion of SLC_2

{
  "interests": [
                {
                  "category_id": [
                          "SLC_1",
                          "SLC_124"
                    ],
                    "operation": "INCLUDE"
                  },
                  {
                    "category_id": [
                        "SLC_2"
                    ],
                  "operation": "EXCLUDE"
                }
              ]
}

Audience Insights

Get Audience Insights

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/targeting_insights

Parameters

Parameter Default Description
ad_account_id The Ad Account ID to be used

Attributes

Attribute Description Required Possible Values
base_spec Valid targeting spec R Any valid spec described here
targeting_spec Valid targeting spec R Any valid spec described here

Query Parameters

Parameter Description Required Possible Values
dimension_category The category to filter the output results O Can be one of: demo/geo/device/interest

Example

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get()
curl -X POST \
  -d '{"base_spec": {"interests": [{"category_id": ["SLC_36"]}],"geos": [{"country_code": "us"}]},"targeting_spec": {"interests": [{"category_id": ["SLC_37"]}],"geos": [{"country_code": "us"}]}}'\
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/139ee7a0-8225-4076-9048-4cb7d7b3a926/targeting_insights?dimension_category=demo

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5b21985200ff0b57ca241c591c0001737e616473617069736300016275696c642d35336630363134382d312d3137352d3100010137",
    "targeting_insights": {
        "target_audience": {
            "audience_size_minimum": "10500000",
            "audience_size_maximum": "10800000"
        },
        "reference_audience": {
            "audience_size_minimum": "1110000",
            "audience_size_maximum": "1125000"
        },
        "categories": {
            "demographics": {
                "distribution": {
                    "age_groups": {
                        "key": "",
                        "insight": [
                            {
                                "value": "",
                                "count": 0,
                                "id": "35+",
                                "name": "35+",
                                "target_audience_percent": 10.3,
                                "reference_audience_percent": 11.9,
                                "target_index_to_reference": 0.9,
                                "metadata": {}
                            },
                            {
                                "value": "",
                                "count": 0,
                                "id": "18-20",
                                "name": "18-20",
                                "target_audience_percent": 21.2,
                                "reference_audience_percent": 16.9,
                                "target_index_to_reference": 1.3,
                                "metadata": {}
                            },
                            {
                                "value": "",
                                "count": 0,
                                "id": "21-24",
                                "name": "21-24",
                                "target_audience_percent": 17,
                                "reference_audience_percent": 20,
                                "target_index_to_reference": 0.8,
                                "metadata": {}
                            },
                            {
                                "value": "",
                                "count": 0,
                                "id": "13-17",
                                "name": "13-17",
                                "target_audience_percent": 30.6,
                                "reference_audience_percent": 18.9,
                                "target_index_to_reference": 1.6,
                                "metadata": {}
                            },
                            {
                                "value": "",
                                "count": 0,
                                "id": "25-34",
                                "name": "25-34",
                                "target_audience_percent": 20.9,
                                "reference_audience_percent": 32.3,
                                "target_index_to_reference": 0.6,
                                "metadata": {}
                            },
                            {
                                "value": "",
                                "count": 0,
                                "id": "UNKNOWN",
                                "name": "unknown",
                                "target_audience_percent": 0,
                                "reference_audience_percent": 0,
                                "target_index_to_reference": 0,
                                "metadata": {}
                            }
                        ]
                    },
                    "gender": {
                        "key": "",
                        "insight": [
                            {
                                "value": "",
                                "count": 0,
                                "id": "MALE",
                                "name": "male",
                                "target_audience_percent": 46.4,
                                "reference_audience_percent": 55,
                                "target_index_to_reference": 0.8,
                                "metadata": {}
                            },
                            {
                                "value": "",
                                "count": 0,
                                "id": "GENDER_UNKNOWN",
                                "name": "gender_unknown",
                                "target_audience_percent": 0.2,
                                "reference_audience_percent": 0,
                                "target_index_to_reference": 0,
                                "metadata": {}
                            },
                            {
                                "value": "",
                                "count": 0,
                                "id": "FEMALE",
                                "name": "female",
                                "target_audience_percent": 53.4,
                                "reference_audience_percent": 45,
                                "target_index_to_reference": 1.2,
                                "metadata": {}
                            }
                        ]
                    },
                    "languages": {
                        "key": "",
                        "insight": [
                            {
                                "value": "",
                                "count": 0,
                                "id": "AR",
                                "name": "ar",
                                "target_audience_percent": 0.1,
                                "reference_audience_percent": 0.2,
                                "target_index_to_reference": 0.7,
                                "metadata": {}
                            },
                            {
                                "value": "",
                                "count": 0,
                                "id": "FR",
                                "name": "fr",
                                "target_audience_percent": 0.2,
                                "reference_audience_percent": 0.1,
                                "target_index_to_reference": 1.4,
                                "metadata": {}
                            },
                            {
                                "value": "",
                                "count": 0,
                                "id": "ES",
                                "name": "es",
                                "target_audience_percent": 3.3,
                                "reference_audience_percent": 4.7,
                                "target_index_to_reference": 0.7,
                                "metadata": {}
                            },
                            {
                                "value": "",
                                "count": 0,
                                "id": "EN",
                                "name": "en",
                                "target_audience_percent": 99.1,
                                "reference_audience_percent": 98.6,
                                "target_index_to_reference": 1,
                                "metadata": {}
                            }
                        ]
                    },
                    "advanced_demographics": {
                        "key": "",
                        "insight": [
                            {
                                "value": "",
                                "count": 0,
                                "id": "EXPD_307",
                                "name": "Household Income ($150,000-$174,999)",
                                "target_audience_percent": 2.9,
                                "reference_audience_percent": 3.4,
                                "target_index_to_reference": 0.9,
                                "metadata": {}
                            },
                            {
                                "value": "",
                                "count": 0,
                                "id": "DLXD_202",
                                "name": "HHI: 50k-75k",
                                "target_audience_percent": 17.7,
                                "reference_audience_percent": 18.7,
                                "target_index_to_reference": 0.9,
                                "metadata": {}
                            },
                            [[[snip]]]
                            {
                                "value": "",
                                "count": 0,
                                "id": "FEMALE_UNKNOWN",
                                "name": "female_unknown",
                                "target_audience_percent": 0,
                                "reference_audience_percent": 0,
                                "target_index_to_reference": 0,
                                "metadata": {
                                    "gender": "FEMALE",
                                    "age_groups": "unknown"
                                }
                            }
                        ]
                    }
                }
            }
        }
    }
}

Audience Size

The Audience Size API returns an estimated range of potential reach for a given targeting spec.

By Ad Squad Spec

 curl -X POST \
   -H "Content-Type: application/json" \
   -d '{"name": "App Install, United States, All Genders, 13-24", "status": "ACTIVE", "type": "SNAP_ADS", "targeting": {"geos": [{"country_code": "us"}],"demographics": [{"age_groups": ["13-17","18-20","21-24"]}]}, "placement": "CONTENT", "bid_micro": 6000000, "auto_bid": false, "daily_budget_micro": 50000000, "delivery_constraint": "DAILY_BUDGET", "optimization_goal": "APP_INSTALLS", "included_content_types": ["SCIENCE_TECHNOLOGY"]}' \
   -H "Authorization: Bearer meowmeowmeow" \
   https://adsapi.snapchat.com/v1/adaccounts/d8c1e7e9-f119-4ed3-b77e-33b7eae13411/audience_size_v2

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5848847200ff049b9c18549b500001737e616473617069736300016275696c642d39323764616530622d312d32372d3300010124",
  "audience_size": {
    "audience_size_minimum": 15400000,
    "audience_size_maximum": 21025000
  }
}

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/{ad_account_id}/audience_size_v2

URL Parameters

Parameter Description
ad_account_id Ad Account ID

By Ad Squad ID

curl -X GET  
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adsquads/c7b98952-4c6e-4f95-8cd1-cf0f17a77988/audience_size_v2

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "58474ee700ff017f0381aeb1a90001737e616473617069736300016275696c642d32356261313161372d312d32372d3100010120",
  "audience_size": {
    "ad_squad_id": "c7b98952-4c6e-4f95-8cd1-cf0f17a77988",
    "audience_size_minimum": 16450000,
    "audience_size_maximum": 19925000
  }
}

This endpoint retrieves the estimated audience size for a specific ad squad.

HTTP Request

GET https://adsapi.snapchat.com/v1/adsquads/{ad_squad_id}/audience_size_v2

URL Parameters

Parameter Description
ad_squad_id Ad squad ID

By Targeting Spec

 curl -X POST \
   -H "Content-Type: application/json" \
   -d '{"geos":[{"country_code": "us"}], "demographics": [{"age_groups": ["21-24"]}]}' \
   -H "Authorization: Bearer meowmeowmeow" \
   https://adsapi.snapchat.com/v1/adaccounts/d8c1e7e9-f119-4ed3-b77e-33b7eae13411/audience_size

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5848847200ff049b9c18549b500001737e616473617069736300016275696c642d39323764616530622d312d32372d3300010124",
  "audience_size": {
    "audience_size_minimum": 12400000,
    "audience_size_maximum": 15025000
  }
}

This endpoint retrieves the estimated audience size for a specific targeting spec, whether or not the targeting is in use by an ad squad.

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/<ID>/audience_size

URL Parameters

Parameter Description
ID The ID of the ad account

Bid Estimate

The Bid Estimate API returns a bid estimate min and max for a given Ad Squad or Targeting Spec.

By Ad Squad

curl -X GET  
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adsquads/c5995202-bfbc-45a0-9702-dd6841af52fe/bid_estimate

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57affee300ff0d91229fabb9710001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010110",
  "bid_estimate": {
    "ad_squad_id":"c5995202-bfbc-45a0-9702-dd6841af52fe",
    "optimization_goal": "IMPRESSIONS",
    "bid_estimate_minimum":8000000,
    "bid_estimate_maximum":9000000
  }
}

This endpoint retrieves the bid estimate for a specific ad squad.

HTTP Request

GET https://adsapi.snapchat.com/v1/adsquads/<ID>/bid_estimate

URL Parameters

Parameter Description
ID The ID of the ad squad

By Targeting Spec

curl -X POST \
   -H 'Content-Type: application/json' \
   -d '{"optimization_goal": "IMPRESSIONS", "targeting": {"geos": [{"country_code": "us"}],"demographics": [{"age_groups": ["21-24"],"gender": "MALE"}]}}' \
   -H 'Authorization: Bearer meowmewmeow' \
   https://adsapi.snapchat.com/v1/adaccounts/8abc3db7-8148-4fbf-999c-8d2266369d75/bid_estimate

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57affee300ff0d91229fabb9710001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010110",
  "bid_estimate": {
    "optimization_goal": "IMPRESSIONS",
    "bid_estimate_minimum":8000000,
    "bid_estimate_maximum":9000000
  }
}

This endpoint retrieves the bid estimate for a specific targeting spec, whether or not the targeting is in use by an ad squad.

HTTP Request

POST https://adsapi.snapchat.com/v1/adaccounts/<ID>/bid_estimate

URL Parameters

Parameter Description
ID The ID of the ad account

Attributes

Attribute Description Required Note
optimization_goal Optimization Goal R Available for all valid optimization goals
targeting A valid Targeting Spec R

Delivery Status

The delivery status provides details of an entity’s status given delivery within the Snap ad platform.

Attributes

Entity Status Description
Common PENDING Default
VALID Entity is valid for delivery
INVALID_NOT_ACTIVE Entity status isn’t active
INVALID_NOT_EFFECTIVE_ACTIVE Entity has a valid state and is active, but a parent entity has something wrong with it and is preventing this entity becoming active
INVALID_START_TIME Start time is after the present time
INVALID_END_TIME End time is before the present time
INVALID_EFFECTIVE_START_TIME Effective start time is after the present time
INVALID_EFFECTIVE_END_TIME Effective end time is before now
Ad Account TEST_AD_ACCOUNT Ad account is test account
INVALID_REMAINING_AD_ACCOUNT_BUDGET Remaining ad account budget is less or equal to 0
INVALID_AD_ACCOUNT_LIFETIME_SPEND_CAP Ad account has invalid lifetime spend cap
INVALID_OVER_BUDGET_AD_ACCOUNT_FINALIZED_LIFETIME_SPEND Ad account finalized lifetime spend exceeds lifetime spend cap
INVALID_OVER_BUDGET_AD_ACCOUNT_REALTIME_LIFETIME_SPEND Ad account realtime lifetime spend exceeds lifetime spend cap
Campaign INVALID_CAMPAIGN_LIFETIME_SPEND_CAP Campaign has invalid lifetime spend cap
INVALID_OVER_BUDGET_CAMPAIGN_FINALIZED_LIFETIME_SPEND Campaign finalized lifetime spend exceeds lifetime spend cap
INVALID_OVER_BUDGET_CAMPAIGN_REALTIME_LIFETIME_SPEND Campaign realtime lifetime spend exceeds lifetime spend cap
INVALID_OVER_BUDGET_CAMPAIGN_DAILY_SPEND Campaign daily spend exceeds daily spend cap
NO_VALID_AD_SQUAD Campaign has no valid ad squad
INVALID_RF_FOR_RESERVED_BUY Reach frequency is invalid for reserved buy
INVALID_UNKNOWN_FORECAST_ERROR Unknown error from forecast
Ad Squad INVALID_TARGETING_REACH_STATUS AdSquad targeting reach status is invalid
INVALID_PENDING_TARGETING_REACH_STATUS AdSquad targeting reach status is pending
INVALID_AD_SQUAD_HAS_NO_ACTIVE_ADS AdSquad doesn’t have any active ad
INVALID_AD_SQUAD_WIREOBJECT Failed to convert ad squad entity to wire object
INVALID_INTERNAL_PLACEMENT AdSquad has invalid internal placement v2 and non-empty ads
INVALID_AD_SQUAD_HAS_UNSUPPORTED_AD_TYPE AdSquad has unsupported ad type
INVALID_UNSUPPORTED_AD_SQUAD_TYPE AdSquad has an unsupported type
INVALID_AD_SQUAD_LIFETIME_SPEND_CAP Ad squad has invalid lifetime spend cap
INVALID_OVER_BUDGET_AD_SQUAD_FINALIZED_LIFETIME_SPEND Ad squad finalized lifetime spend exceeds lifetime spend cap
INVALID_OVER_BUDGET_AD_SQUAD_REALTIME_LIFETIME_SPEND Ad squad realtime lifetime spend exceeds lifetime spend cap
INVALID_AD_SQUAD_DAILY_SPEND_CAP Ad squad has invalid daily spend cap
INVALID_OVER_BUDGET_AD_SQUAD_DAILY_SPEND Ad squad daily spend exceeds daily spend cap
Ad NOT_APPROVED_AD Ad has non-approved review status
INVALID_NOT_APPROVED_REVIEW_STATUS The Ad has failed Ad review
INVALID_PENDING_REVIEW_STATUS Ad review is still pending
INVALID_DYNAMIC_CONTENT_MARKUP Creative has invalid dynamic content markup
INVALID_UNSUPPORTED_AD_TYPE Ad type isn’t supported

Measurement

Measurement endpoints provides stats data that is updated approximately every 15 minutes.

All stats requests can be made with TOTAL, DAY, or HOUR granularity.

Request/Response Pattern

Stats endpoints have a consistent request and response pattern.

Request Pattern

Pattern:

GET /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}/stats

Example:

GET /v1/campaigns/ff869d1f-0923-4d28-8577-4c36291f0fca/stats

Response Pattern - TOTAL Granularity

Response pattern for TOTAL Granularity requests

{
  "request_status": "success",
  "request_id": "57ad1ad600076e58fa35e192",
  "total_stats": [
    {
      "sub_request_status": "success",
      "total_stat": {
        "id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
        "type": "CAMPAIGN",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 0,
          "swipes": 0,
          "spend": 0,
          "quartile_1": 0,
          "quartile_2": 0,
          "quartile_3": 0,
          "view_completion": 0,
          "screen_time_millis": 0
        }
      }
    }
  ]
}

Response Pattern - DAY Granularity

Response pattern for DAY Granularity requests

{
  "request_status": "success",
  "request_id": "57ad240f000756e8d435a6cd",
  "timeseries_stats": [
    {
      "sub_request_status": "success",
      "timeseries_stat": {
        "id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
        "type": "CAMPAIGN",
        "granularity": "DAY",
        "start_time": "2016-08-05T22:00:00.000-07:00",
        "end_time": "2016-08-07T22:00:00.000-07:00",
        "timeseries": [
          {
            "start_time": "2016-08-05T22:00:00.000-07:00",
            "end_time": "2016-08-06T22:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          },
          {
            "start_time": "2016-08-06T22:00:00.000-07:00",
            "end_time": "2016-08-07T22:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          }
        ]
      }
    }
  ]
}

Response Pattern - HOUR Granularity

Response pattern for HOUR Granularity requests

{
  "request_status": "success",
  "request_id": "57ad245a000e3c88bc33ea4e",
  "timeseries_stats": [
    {
      "sub_request_status": "success",
      "timeseries_stat": {
        "id": "7057e31f-b908-4bc7-85dd-88169f53e08d",
        "type": "CAMPAIGN",
        "granularity": "HOUR",
        "start_time": "2016-08-05T18:00:00.000-07:00",
        "end_time": "2016-08-06T18:00:00.000-07:00",
        "timeseries": [
          {
            "start_time": "2016-08-05T18:00:00.000-07:00",
            "end_time": "2016-08-05T19:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          },
          {
            "start_time": "2016-08-05T19:00:00.000-07:00",
            "end_time": "2016-08-05T20:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          },



[[[ snip ]]]



          {
            "start_time": "2016-08-06T16:00:00.000-07:00",
            "end_time": "2016-08-06T17:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          },
          {
            "start_time": "2016-08-06T17:00:00.000-07:00",
            "end_time": "2016-08-06T18:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          }
        ]
      }
    }
  ]
}

Request Parameters

Attribute Description Required Possible Values
breakdown Object-level breakdown O ad, adsquad [Only available on Campaign Stats endpoint], campaign [Only available on Ad Account Stats endpoint]
fields Metrics requested (comma-separated) O (see table below; default: impressions,spend)
end_time End Time (ISO 8601) R*
start_time Start Time (ISO 8601) R*
granularity Metrics granularity R TOTAL, DAY, HOUR, LIFETIME
test Return Sample (fake) Stats O false (default), true
dimension Insight-level breakdown O GEO, DEMO, INTEREST, DEVICE
pivot The pivot to be used for insights breakdown O country, region, dma, gender, age_bucket, interest_category_id, interest_category_name, operating_system, make, model
action_report_time Specifies the time f conversion reporting O conversion (default), impression**
swipe_up_attribution_window Attribution window for swipe ups O 1_DAY, 7_DAY, 28_DAY (default)
view_attribution_window Attribution window for views O 1_HOUR, 3_HOUR, 6_HOUR, 1_DAY (default), 7_DAY, 28_DAY
position_stats Position metric breakdown for Snap Ads within a Story Ad O true
omit_empty Omits records with zero data for all metrics for a given date/entity. If there is data for any metric for a given date/entity, all metrics for that date/entity are returned O false (default), true
conversion_source_types Conversion source breakout by platform O web, app, offline**, total
platform_stats Breaks down metrics by Snapchat Client/Audience network O true, false
limit The limit parameter specifies how many entities should be returned per page O integer, max 200

** offline conversion data source ( conversion_source_types=offline ) and impression based conversions ( action_report_time=impression ) are available from 1 May 2020 onwards.

Response Parameters

Attribute Description
finalized_data_end_time This defines the time up until when reporting metrics are finalized. You can query for all metrics before this time including uniques and reach and they will have the final numbers. For any time after the finalized_data_end_time the metrics are still undergoing de-duplication and finalization and may change accordingly.
paging If you are using pagination the paging attribute will contain a next_link attribute which holds the API call to fetch the next page.

Pagination

For calls that fetch stats for many entities we recommend that you use pagination. The limit parameter specifies how many entities should be returned per page. The maximum pagination limit is 200.

The returned result will contain a paging attribute, this in turn holds a next_link attribute which holds the API call to fetch the next page. Paginated calls are rdered by time of creation, non-paginated calls are unsorted.

Core Metrics

The following metrics are available for all Snap Ads.

Field Name Description
impressions Impression Count
swipes Swipe-Up Count
view_time_millis Use screen_time_millis instead. Total Time Spent on top Snap Ad (milliseconds)
screen_time_millis Total Time Spent on top Snap Ad (milliseconds)
quartile_1 Video Views to 25%
quartile_2 Video Views to 50%
quartile_3 Video Views to 75%
view_completion Video Views to completion
spend Amount Spent (micro-currency)
video_views The total number of impressions that meet the qualifying video view criteria of at least 2 seconds of consecutive watch time or a swipe up action on the Top Snap

Additional Metrics

The following metrics are available for specific Snap Ads with Attachments and/or at TOTAL granularity. Italicized metrics are available in the real-time stats pipeline. Non-italicized are available in real-time for the granularities DAY and HOUR, for LIFETIME granularity the data is only accessible as finalized data, available after 48-72 hours.

Field Name Snap Ad Types Description
android_installs APP_INSTALL # of Android App Installs
attachment_avg_view_time_millis Any Attachment Average Attachment View Time (milli-seconds)
attachment_frequency Any Attachment Average # of Attachment Views per User Reached
attachment_quartile_1 LONGFORM_VIDEO Long Form Video Views to 25%
attachment_quartile_2 LONGFORM_VIDEO Long Form Video Views to 50%
attachment_quartile_3 LONGFORM_VIDEO Long Form Video Views to 75%
attachment_total_view_time_millis Any Attachment Total Attachment View Time (milli-seconds)
attachment_uniques Any Attachment # of unique attachment impressions
attachment_view_completion LONGFORM_VIDEO Long Form Video Views to completion
attachment_video_views LONGFORM_VIDEO Long Form Video Attachment Views, viewed for at least 10 consecutive seconds or reached 97% of the Long Form Video duration
avg_view_time_millis Any Use avg_screen_time_millis instead. Average Top Snap view time per User Reached
avg_screen_time_millis Any Average Top Snap view time across all impressions
frequency Any Average # of Impressions per User Reached
ios_installs APP_INSTALL # of iOS App Installs
swipe_up_percent Any Attachment % of Impressions that Swiped-Up
total_installs APP_INSTALL Total # of App Installs
uniques Any # of unique impressions
video_views_time_based Any The total number of impressions that meet the qualifying video view criteria of at least 2 seconds, not including swipe ups
video_views_15s Any The total number of impressions that meet the qualifying video view criteria of at least 15 seconds, or 97% completion if it’s shorter than 15 seconds, or a swipe up action on the ad
story_opens STORY # of times users tapped on the ad tile in the feed to view the Story Ad
story_completes STORY # of times users viewed through to the last Snap of your Story Ad
position_impressions STORY # the impression number for this story ad position
position_uniques STORY # the unique viewer numbers for this story ad position
position_frequency STORY # the frequency for this story ad position
position_screen_time_millis STORY # the total view time in milliseconds for this story ad position
position_swipe_up_percent STORY # the swipe up rate for this story ad position
avg_position_screen_time_millis STORY # the average view time for this story ad position
shares LENS, AD_TO_LENS, FILTER # of times lens/filter was shared in a Chat or Story
saves LENS, AD_TO_LENS, FILTER # of times lens/filter was saved to Memories

Conversion Reporting

The action_report_time parameter specifies the timing to use when requesting conversion reporting. Passing the value conversion will return conversions based on the time the user triggered the conversion event, passing the value impression will return conversions based on the time the ad impression took place.

Reporting for conversions based on ad impression (action_report_time=impression), are available from 1st May 2020 onwards.

Conversion Event Stats

The following conversion event metrics are available for ads that have been setup to track conversions through Snap Pixel.

Fields Granularity Description
conversion_purchases Any # of attributed “PURCHASE” conversion events
conversion_purchases_value Any Value of attributed “PURCHASE” conversion events (microcurrency in Ad Account’s currency)
conversion_save Any # of attributed “SAVE” conversion events
conversion_start_checkout Any # of attributed “START_CHECKOUT” conversion events
conversion_add_cart Any # of attributed “ADD_CART” conversion events
conversion_view_content Any # of attributed “VIEW_CONTENT” conversion events
conversion_add_billing Any # of attributed “ADD_BILLING” conversion events
conversion_sign_ups Any # of attributed “SIGN_UP” conversion events
conversion_searches Any # of attributed “SEARCH” conversion events
conversion_level_completes Any # of attributed “LEVEL_COMPLETE” conversion events
conversion_app_opens Any # of attributed “APP_OPEN” conversion events
conversion_page_views Any # of attributed “PAGE_VIEW” conversion events
conversion_subscribe Any # of attributed “SUBSCRIBE” conversion events
conversion_ad_click Any # of attributed “AD_CLICK” conversion events
conversion_ad_view Any # of attributed “AD_VIEW” conversion events
conversion_complete_tutorial Any # of attributed “COMPLETE_TUTORIAL” conversion events
conversion_invite Any # of attributed “INVITE” conversion events
conversion_login Any # of attributed “LOGIN” conversion events
conversion_share Any # of attributed “SHARE” conversion events
conversion_reserve Any # of attributed “RESERVE” conversion events
conversion_achievement_unlocked Any # of attributed “ACHIEVEMENT_UNLOCKED” conversion events
conversion_add_to_wishlist Any # of attributed “ADD_TO_WISHLIST” conversion events
conversion_spend_credits Any # of attributed “SPENT_CREDITS” conversion events
conversion_rate Any # of attributed “RATE” conversion events
conversion_start_trial Any # of attributed “START_TRIAL” conversion events
conversion_list_view Any # of attributed “LIST_VIEW” conversion events
conversion_visit Any # of attributed “VISIT” conversion events
custom_event_1 Any # of attributed “CUSTOM_EVENT_1” conversion events
custom_event_2 Any # of attributed “CUSTOM_EVENT_2” conversion events
custom_event_3 Any # of attributed “CUSTOM_EVENT_3” conversion events
custom_event_4 Any # of attributed “CUSTOM_EVENT_4” conversion events
custom_event_5 Any # of attributed “CUSTOM_EVENT_5” conversion events

Conversion breakout

The parameter conversion_source_types provides a breakout of conversions based on where the conversions occurred.

Parameter Description
total All conversion events
web Events reported via the Snap Pixel SDK
app Events reported within an App
offline Events reported from an offline source (in-store)

Conversion breakout example

curl "https://adsapi.snapchat.com/v1/adsquads/0b7e62aa-a8bc-48f6-a410-c65eee9cc9a7/stats?fields=conversion_purchases,impressions,spend,swipe_up_percent,swipes,view_completion&conversion_source_types=total,web,app"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5de004c100ff03ea1eeb1050430001737e616473617069736300016275696c642d61663733336133322d312d3330372d3000010103",
    "total_stats": [
        {
            "sub_request_status": "SUCCESS",
            "total_stat": {
                "id": "0b7e62aa-a8bc-48f6-a410-c65eee9cc9a7",
                "type": "AD_SQUAD",
                "granularity": "TOTAL",
                "stats": {
                    "impressions": 2337371,
                    "swipes": 14745,
                    "view_completion": 69506,
                    "swipe_up_percent": 0.0063,
                    "spend": 3449137066,
                    "conversion_purchases": 1141,
                    "conversion_purchases_web": 659,
                    "conversion_purchases_app": 482
                },
                "finalized_data_end_time": "2019-11-28T02:00:00.000-08:00"
            }
        }
    ]
}

This parameter breaks down conversions based on where the conversion occurred.

Omitting empty records example

curl "https://adsapi.snapchat.com/v1/campaigns/9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37/stats?granularity=DAY&start_time=2019-11-12T00%3A00%3A00-08%3A00&end_time=2019-11-16T00%3A00%3A00-08%3A00&&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&fields=conversion_purchases,impressions,swipes,spend&conversion_source_types=web,app,total"
  -H "Authorization: Bearer meowmeowmeow"

An example not using omit_empty, this returns several day entries with no metrics.

{
    "request_status": "SUCCESS",
    "request_id": "5de0f99900ff02f49ea1540d1c0001737e616473617069736300016275696c642d61663733336133322d312d3330372d300001013c",
    "timeseries_stats": [
        {
            "sub_request_status": "SUCCESS",
            "timeseries_stat": {
                "id": "9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37",
                "type": "CAMPAIGN",
                "granularity": "DAY",
                "swipe_up_attribution_window": "28_DAY",
                "view_attribution_window": "7_DAY",
                "start_time": "2019-11-12T00:00:00.000-08:00",
                "end_time": "2019-11-16T00:00:00.000-08:00",
                "finalized_data_end_time": "2019-11-28T00:00:00.000-08:00",
                "timeseries": [
                    {
                        "start_time": "2019-11-12T00:00:00.000-08:00",
                        "end_time": "2019-11-13T00:00:00.000-08:00",
                        "stats": {
                            "impressions": 0,
                            "swipes": 0,
                            "spend": 0,
                            "conversion_purchases": 0,
                            "conversion_purchases_web": 0,
                            "conversion_purchases_app": 0
                        }
                    },
                    {
                        "start_time": "2019-11-13T00:00:00.000-08:00",
                        "end_time": "2019-11-14T00:00:00.000-08:00",
                        "stats": {
                            "impressions": 0,
                            "swipes": 0,
                            "spend": 0,
                            "conversion_purchases": 0,
                            "conversion_purchases_web": 0,
                            "conversion_purchases_app": 0
                        }
                    },
                    {
                        "start_time": "2019-11-14T00:00:00.000-08:00",
                        "end_time": "2019-11-15T00:00:00.000-08:00",
                        "stats": {
                            "impressions": 599725,
                            "swipes": 3790,
                            "spend": 594736665,
                            "conversion_purchases": 62,
                            "conversion_purchases_web": 42,
                            "conversion_purchases_app": 20
                        }
                    },
                    {
                        "start_time": "2019-11-15T00:00:00.000-08:00",
                        "end_time": "2019-11-16T00:00:00.000-08:00",
                        "stats": {
                            "impressions": 670692,
                            "swipes": 4189,
                            "spend": 716170632,
                            "conversion_purchases": 125,
                            "conversion_purchases_web": 82,
                            "conversion_purchases_app": 43
                        }
                    }
                ]
            }
        }
    ]
}
curl "https://adsapi.snapchat.com/v1/campaigns/9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37/stats?granularity=DAY&start_time=2019-11-12T00%3A00%3A00-08%3A00&end_time=2019-11-16T00%3A00%3A00-08%3A00&&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&fields=conversion_purchases,impressions,swipes,spend&conversion_source_types=web,app,total&omit_empty=true"
  -H "Authorization: Bearer meowmeowmeow"

An example using omit_empty, this returns only day entries with metrics:

{
    "request_status": "SUCCESS",
    "request_id": "5de0fa4900ff0942bb5374cb8f0001737e616473617069736300016275696c642d61663733336133322d312d3330372d300001014d",
    "timeseries_stats": [
        {
            "sub_request_status": "SUCCESS",
            "timeseries_stat": {
                "id": "9f13330f-7b85-4fc3-b9c3-cf8be7fa4d37",
                "type": "CAMPAIGN",
                "granularity": "DAY",
                "swipe_up_attribution_window": "28_DAY",
                "view_attribution_window": "7_DAY",
                "start_time": "2019-11-12T00:00:00.000-08:00",
                "end_time": "2019-11-16T00:00:00.000-08:00",
                "finalized_data_end_time": "2019-11-28T00:00:00.000-08:00",
                "timeseries": [
                    {
                        "start_time": "2019-11-14T00:00:00.000-08:00",
                        "end_time": "2019-11-15T00:00:00.000-08:00",
                        "stats": {
                            "impressions": 599725,
                            "swipes": 3790,
                            "spend": 594736665,
                            "conversion_purchases": 62,
                            "conversion_purchases_web": 42,
                            "conversion_purchases_app": 20
                        }
                    },
                    {
                        "start_time": "2019-11-15T00:00:00.000-08:00",
                        "end_time": "2019-11-16T00:00:00.000-08:00",
                        "stats": {
                            "impressions": 670692,
                            "swipes": 4189,
                            "spend": 716170632,
                            "conversion_purchases": 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_quar