Introduction

Welcome to the Snapchat Marketing API!

We have code samples in Curl and Python (coming soon)! You can view code examples in the dark area to the right, and you can switch the programming language of the examples with the tabs in the top right.

Upcoming Breaking Changes

April 2020

curl "https://adsapi.snapchat.com/v1/adsquads/079abe5b-8aa3-4009-9932-66e0b0a2c75c?return_placement_v2=true" \
  -H "Authorization: Bearer  meowmeowmeow"

Example, this Ad Squad using multi-country targeting is targeting the US and Canada:

{
    "request_status": "SUCCESS",
    "request_id": "5e821b1100ff00ff5566930ea67e0001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d61643137333166302d312d3333382d3000010145",
    "adsquads": [
        {
            "sub_request_status": "SUCCESS",
            "adsquad": {
                "id": "079abe5b-8aa3-4009-9932-66e0b0a2c75c",
                "updated_at": "2020-03-10T20:34:09.826Z",
                "created_at": "2020-03-10T20:33:58.614Z",
                "name": "Multi country Ad Squad Example",
                "status": "ACTIVE",
                "campaign_id": "f5b84e48-dc8b-4ddb-bf9b-edf07fadd6c6",
                "type": "SNAP_ADS",
                "targeting": {
                    "regulated_content": false,
                    "demographics": [
                        {
                            "languages": [
                                "en"
                            ]
                        }
                    ],
                    "geos": [
                        {
                            "country_code": "us",
                            "operation": "INCLUDE"
                        },
                        {
                            "country_code": "ca",
                            "operation": "INCLUDE"
                        }
                    ],
                    "enable_targeting_expansion": true
                },
                "targeting_reach_status": "VALID",
                "placement_v2": {
                    "config": "AUTOMATIC"
                },
                "billing_event": "IMPRESSION",
                "bid_micro": 1000000,
                "auto_bid": false,
                "target_bid": true,
                "bid_strategy": "TARGET_COST",
                "daily_budget_micro": 50000000,
                "start_time": "2019-12-17T01:38:19.961Z",
                "optimization_goal": "APP_INSTALLS",
                "conversion_window": "SWIPE_28DAY_VIEW_1DAY",
                "delivery_constraint": "DAILY_BUDGET"
            }
        }
    ]
}

Multi-country targeting

Multi-country targeting is available through the API starting April 1st! This will enable advertisers to set up Ad Squads targeting any combination of countries across the world.

Multi-country targeting will help extend reach and optimize ads globally to the best audience. While setting up multi-country Ad Squads has its advantages, we do not guarentee evenly distributed delivery. If you want to test audiences between countries, then we advise that you set up separate Ad Squads.

This will launch broadly in Ads Manager in late April, and you will start to see more Ad Squads with multiple geos objects within their targeting_spec as this rolls out. Each country needs to be placed in a geos entry, a targeting spec that uses multi-country targeting needs to also include a demographics entry that incorporates a single languages entry.

If your app is updating the targeting_spec of the AdSquad entity you should take multi-country targeting into consideration to allow multi-country.

March 2020

We are introducing breaking changes to our API. The deprecation date will be 90 days after the announcement date, with final end of life for legacy APIs and fields two weeks after the sunset date.

Deprecation of Insight parameters dimension and pivots

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

• The parameters dimension and pivots as described in the following section will be deprecated.
• The new parameter report_dimension offers the same functionality with the added benefit of supporting DAY, TOTAL and LIFETIME granularity.
• Delivery Insights via report_dimension are only available from January 1st, 2020.
• After the deprecation you will still be able to use dimension and pivots to retrieve data finalized prior to the 20th June 2020.

New bid_strategy attribute replaces auto_bid and target_bid

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

• The new bid_strategy attribute replaces the attributesauto_bid and target_bid
• bid_strategy is an enumeration that holds the bid method for the Ad Squad
• Apps should be adjusted to use only bid_strategy on Creation and Update requests, the attributes auto_bid/target_bid should not be sent in requests
• During the 90 day transition period bid_strategy will co-exist with auto_bid and target_bid
• See section on bid_strategy

Deprecation of placement in favour of placement_v2

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

• All Ad Squads are required to use placement_v2
• The attributes at included_content_types and excluded_content_types at AdSquad level will be deprecated in favour of the attributes inclusion and exclusion defined in placement_v2
• During the 90 day transition period placement will co-exist with placement_v2
• See section on placement_v2 for full information on how to implement

Overview

The highest level object is an Organization. Each Organization is tied to a specific Brand, Advertiser, or Partner. An Organization has an over-arching line of credit established with Snap Inc.

An Organization owns:

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;

• Get all Ads under an Ad Account
• Get all Ad Squads under an Ad Account
• Get all Creatives under an Ad Account
• Get all Media under an Ad Account
• Get all Campaigns under an Ad Account
• Get all Ad Accounts under an Organization
• Get all Audience Segments under an Ad Account
• Get Zipcode targeting options
• Get change logs request

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

Pattern:

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

Example:

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

Entity Request Limits

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

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

Create One or More Entities

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

Pattern:

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

Example:

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

Update One or More Entities

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

Pattern:

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

Example:

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

Delete a Single Entity

Pattern:

DELETE /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}

Example:

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

Monetary Values

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

Examples

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

Authentication

To authorize, use this code:

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')

# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
  -H "Authorization: Bearer meowmeowmeow"

Make sure to replace meowmeowmeow with your access token.

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

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

Authorization: Bearer meowmeowmeow

Obtain App Credentials

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

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

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

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

User Auth via Redirect

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

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

Parameters

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

Receive the Redirected User

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

Parameters

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

Generate an Access Token

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

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

The above command returns JSON structured like this:

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

HTTP Request

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

Parameters

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

Refresh the Access Token

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

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

The above command returns JSON structured like this:

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

HTTP Request

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

Parameters

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

Full Web Flow Example

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

2. Login & Authorize via UI

3. Locate "code" query parameter in the redirect

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

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

from pprint import pprint
from requests_oauthlib import OAuth2Session

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

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

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

}

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

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

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

The above command returns JSON structured like this:

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

Access Token Expiration

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

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

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

User

Get Authenicated User

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.users.me()

curl "https://adsapi.snapchat.com/v1/me"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

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

This endpoint retrieves the authenticated user.

HTTP Request

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

Organizations

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

Attributes

Attribute	Description	Required	Possible Values
name	Organization name	R

Create an Organization

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

Get All Organizations

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.organizations.get()

curl "https://adsapi.snapchat.com/v1/me/organizations" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

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

This endpoint retrieves all organizations.

HTTP Request

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

Get All Organizations with Ad Accounts

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.organizations.get()

curl "https://adsapi.snapchat.com/v1/me/organizations?with_ad_accounts=true" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

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

This endpoint retrieves all organizations the logged in user has access to and the ad accounts beneath each of those organizations.

HTTP Request

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

Get a Specific Organization

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.organizations.get('40d6719b-da09-410b-9185-0cc9c0dfed1d')

curl "https://adsapi.snapchat.com/v1/organizations/40d6719b-da09-410b-9185-0cc9c0dfed1d" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

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

This endpoint retrieves a specific organization.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the organization to retrieve

Funding Sources

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

Attributes

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

Create a Funding Source

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

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

Get All Funding Sources

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

The above command returns JSON structured like this:

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

This endpoint retrieves all funding sources for the specified Organization.

HTTP Request

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

Parameters

Parameter	Default	Description
organization_id		Organization ID

Get a Specific Funding Source

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

The above command returns JSON structured like this:

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

This endpoint retrieves a specific funding source.

HTTP Request

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

URL Parameters

Parameter	Description
funding_source_id	The ID of the funding source to retrieve

Billing Centers

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

Billing Centers can only be created via Snap Business Manager.

Attributes

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

Get all Billing Centers

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

Parameters

Parameter	Default	Description
organization_id		Organization ID

Get a specific Billing Center

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

The above command returns JSON structured like this:

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

The following API request retrieves a specific Billing Center.

HTTP Request

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

Parameters

Parameter	Default	Description
billing_center_id		Billing Center ID

Create a Billing Center

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

The above command returns JSON structured like this:

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

The following API request creates a new Billing Center.

HTTP Request

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

Parameters

Parameter	Default	Description
billing_center_id		Billing Center ID

Update a Billing Center

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

The above command returns JSON structured like this:

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

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

Attributes that can be updated

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

HTTP Request

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

Parameters

Parameter	Default	Description
billing_center_id		Billing Center ID

Invoices

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

Attributes

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

List invoices by Ad Account

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Get individual Invoice

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

The above command returns JSON structured like this:

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

This endpoint retrieve an individual invoice for a given Ad Account

HTTP Request

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

Parameters

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

Example 1 - Invoice

Retrieving an invoice

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

The above command returns JSON structured like this:

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

This example retrieves an individual invoice.

Example 2 - Invoice - invoice_content

Retrieving an invoice with invoice_content

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

The above command returns JSON structured like this:

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

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

Ad Accounts

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

Attributes

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

Create an Ad Account

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

The above command returns JSON structured like this:

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

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

• If the ad account will be used for housing, credit or employment advertising it needs to have the attribute regulations.restricted_delivery_signals set to true

• If the ad account will be used for political advertising the attribute paying_advertiser_name needs to be filled out with the political organization or advocacy group who is paying for the ad (32 character limit)

• If the Ad Account is owned by an agency buying ads on behalf of an advertiser the attribute agency_representing_client needs to be set to true

• If the Ad Account is owned by an agency buying ads on behalf of an advertiser, and the Advertiser is based in France, or will target ads to an audience in France, the following settings will apply:

  • The attribute agency_representing_client needs to be set to true
  • The attribute client_paying_invoices needs to be set to true if the agency is paying the invoices, or false if the advertiser they represent is paying the invoices
  • The attribute client_based_in_country needs to be set to fr
  • The attribute agency_client_metadata needs to be set using the attributes name, email, address_line_1 , city, administrative_district_level_1, country, zipcode and tax_id
    

HTTP Request

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

Parameters

Parameter	Default	Description
organization_id		Organization ID

Get All Ad Accounts

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

The above command returns JSON structured like this:

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

This endpoint retrieves all ad accounts for the specified Organization.

HTTP Request

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

Parameters

Parameter	Default	Description
organization_id		Organization ID

Get a Specific Ad Account

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

The above command returns JSON structured like this:

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

This endpoint retrieves a specific Ad Account.

HTTP Request

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

URL Parameters

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

Update Ad Account

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

The above command returns JSON structured like this:

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

This endpoint updates a specific Ad Account.

Attributes that can be updated

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

HTTP Request

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

URL Parameters

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

Update an Ad Account’s Lifetime Spend Cap

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

The above command returns JSON structured like this:

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

This endpoint updates the Lifetime Spend Limit of a specific ad account, this can only be updated for Ad Accounts where the billing_type is set to IO.

Assign Funding Source

curl -X PUT \
  -H 'Authorization: Bearer meowmeowmeow' \
  -H 'Content-Type: application/json' \
  -d '{"type":"CREDIT_CARD","exclusive":true}' \
  https://adsapi.snapchat.com/v1/adaccounts/d6923e88-bfd0-4f39-ac80-8154f21e8e5f/assign_payment_methods/8ca1687a-f2b4-437d-8554-a85403a714c5

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5eaacb7a00ff0418e163f94fe50001737e616473617069736300016275696c642d63386238336332372d312d3334372d310001014b",
    "fundingsource": {
        "id": "8ca1687a-f2b4-437d-8554-a85403a714c5",
        "updated_at": "2017-10-17T12:28:44.440Z",
        "created_at": "2017-10-17T12:28:44.440Z",
        "type": "CREDIT_CARD",
        "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
        "name": "H Bear",
        "card_type": "VISA",
        "last_4": "5555",
        "daily_spend_limit_micro": 15000000000,
        "daily_spend_limit_currency": "USD",
        "expiration_month": "03",
        "expiration_year": "2023",
        "status": "ACTIVE"
    }
}

The following API request assigns a Funding Source to an Ad Account.

HTTP Request

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

URL Parameters

Parameter	Description
ad_account_id	The ID of the Ad Account that will have the funding source assigned
funding_source_id	The ID of the funding source to be assigned

Ad Account creation - Example 1

Ad Account - Used for Political advertising

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{"adaccounts": [{"name": "Votes for Dogs Account","type": "PARTNER","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],"currency": "GBP","timezone": "Europe/London","advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27","billing_type": "REVOLVING","agency_representing_client": false,"client_paying_invoices": false,"paying_advertiser_name": "The Pugs & Poodle Alliance","regulations": {"restricted_delivery_signals": false}}]}' \
  https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/adaccounts

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5eac0cdb00ff06d4845e8997c40001737e616473617069736300016275696c642d38653566343030352d312d3334382d300001015f",
    "adaccounts": [
        {
            "sub_request_status": "SUCCESS",
            "adaccount": {
                "id": "2b0efb26-973b-4085-aef1-bd0bef429b91",
                "updated_at": "2020-05-01T11:49:48.045Z",
                "created_at": "2020-05-01T11:49:48.045Z",
                "name": "Votes for Dogs Account",
                "type": "PARTNER",
                "status": "PENDING",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "funding_source_ids": [
                    "5ca1687a-f2b4-437d-8554-a85403a714c5"
                ],
                "currency": "GBP",
                "timezone": "Europe/London",
                "paying_advertiser_name": "The Pugs & Poodle Alliance",
                "advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27",
                "billing_type": "REVOLVING",
                "agency_representing_client": false,
                "client_paying_invoices": false,
                "regulations": {
                    "restricted_delivery_signals": false
                }
            }
        }
    ]
}

This request creates an Ad account that will be used for Political or Advocacy Ads, it contains the attribute paying_advertiser_name.

Ad Account creation - Example 2

Ad Account - Used for Credit, Housing, Employment Ads

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{"adaccounts": [{"name": "Account for Credit Housing Employment Ads","type": "PARTNER","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],"currency": "EUR","timezone": "Europe/Paris","advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27","billing_type": "REVOLVING","agency_representing_client": false,"client_paying_invoices": false,"regulations": {"restricted_delivery_signals": true}}]}' \
  https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51053/adaccounts

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5eac0e1600ff0abfa792ff005a320001737e616473617069736300016275696c642d38653566343030352d312d3334382d3000010153",
    "adaccounts": [
        {
            "sub_request_status": "SUCCESS",
            "adaccount": {
                "id": "f249cfe1-973f-4a04-899a-c1f65b9070a0",
                "updated_at": "2020-05-01T11:55:03.343Z",
                "created_at": "2020-05-01T11:55:03.343Z",
                "name": "Account for Credit Housing Employment Ads",
                "type": "PARTNER",
                "status": "PENDING",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "funding_source_ids": [
                    "5ca1687a-f2b4-437d-8554-a85403a714c5"
                ],
                "currency": "EUR",
                "timezone": "Europe/Paris",
                "advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27",
                "billing_type": "REVOLVING",
                "agency_representing_client": false,
                "client_paying_invoices": false,
                "regulations": {
                    "restricted_delivery_signals": true
                }
            }
        }
    ]
}

This request creates an Ad account that can be used for housing, credit and employment ads, the restricted_delivery_signals within the regulations attribute has been set to true.

Ad Account creation - Example 3

Ad Account - Agency representing client, client based in France or targeting France

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{ "adaccounts": [{"name": "délicieux aliments pour chiens","type": "PARTNER","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053","funding_source_ids": ["5ca1687a-f2b4-437d-8554-a85403a714c5"],"currency": "EUR","timezone": "Europe/Paris","advertiser_organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51053","billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27","billing_type": "REVOLVING","agency_representing_client": true,"client_based_in_country": "FR","client_paying_invoices": false,"agency_client_metadata": {"name": "Madamemoiselle Poodle","email": "poodle_client@example.com","address_line_1": "101 Boulevard la Fayette","city": "Paris","administrative_district_level_1": "FR-O","country": "FR","zipcode": "62100","tax_id": "FR12345678900"},"regulations": {"restricted_delivery_signals": false}}]}' \
  https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/adaccounts

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5eab157200ff07dcbf0737d8790001737e616473617069736300016275696c642d63386238336332372d312d3334372d3100010128",
    "adaccounts": [
        {
            "sub_request_status": "SUCCESS",
            "adaccount": {
                "id": "cdfc6dbd-9ac6-416a-b386-d473dd6e6d64",
                "updated_at": "2020-04-30T18:14:11.150Z",
                "created_at": "2020-04-30T18:14:11.150Z",
                "name": "Délicieux aliments pour chiens",
                "type": "PARTNER",
                "status": "PENDING",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "funding_source_ids": [
                    "5ca1687a-f2b4-437d-8554-a85403a714c5"
                ],
                "currency": "EUR",
                "timezone": "Europe/Paris",
                "advertiser_organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
                "billing_center_id": "8b8db2a8-2b48-42f0-858a-88901a782b27",
                "billing_type": "REVOLVING",
                "agency_representing_client": true,
                "client_based_in_country": "FR",
                "client_paying_invoices": false,
                "agency_client_metadata": {
                    "name": "Madamemoiselle Poodle",
                    "email": "poodle_client@example.com",
                    "address_line_1": "101 Boulevard la Fayette",
                    "city": "Paris",
                    "administrative_district_level_1": "FR-O",
                    "country": "FR",
                    "zipcode": "62100",
                    "tax_id": "FR12345678900"
                },
                "regulations": {
                    "restricted_delivery_signals": false
                }
            }
        }
    ]
}

This request creates an Ad Account that is owned by an Agency representing a client, where the Advertiser is paying the invoices and where the Advertiser is based in France, or where the Ad Account will target ads to audience in France.

• agency_representing_client has been set to true
• client_based_in_country has been set to FR
• client_paying_invoices has been set to false as the Advertiser is paying the invoices (note that this should be set to true if the Agency pays the invoices)
• agency_client_metadata has been filled out with the address of the Advertiser and their French Tax ID

Ad Account creation - Example 4

Ad Account - Setting up a test Ad Account

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

The above command returns JSON structured like this:

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

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

Members

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

Attributes

Attribute	Description	Required	Possible Values
display_name	Name of the user	R
organization_id	Organization ID	R
member_status	Name of the Advertiser	R	INVITED, MEMBER
email	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 minimum ROAS for the MIN_ROAS BidStrategy	R if BidStrategy = MIN_ROAS	Minimum desired ROAS
pixel_id	Pixel to be associated with the Ad Squad	O
measurement_provider_names	approved measurement provider	O	MOAT_SS, DOUBLEVERIFY
reach_and_frequency_status**	Status of the reach and frequency booking	R	Must be set to PENDING which automatically updates to ACTIVE or FAILED after booking
delivery_constraint	Type of delivery	R	DAILY_BUDGET (when using daily_budget_micro), LIFETIME_BUDGET (when using lifetime_budget_micro), REACH_AND_FREQUENCY**
reach_and_frequency_status**	Status of the reach and frequency booking	R	Must be set to PENDING which automatically updates to ACTIVE or FAILED after booking
reach_goal**	Reach goal as specified in the Forecasting request	R	Must match the value in the forecasting request
impression_goal**	Reach goal as specified in the Forecasting request	R	Must match the value in the forecasting request
pacing_type	Type of pacing	O	STANDARD (default), ACCELERATED
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 should be between 0.1 and 100
TARGET_COST	Achieves the most volume while aiming to keep your average cost per action below your target cost	use bid_micro to set bid

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

Optimization Goals allowed per Bid Strategy.

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

MIN_ROAS examples

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

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

Examples using “bid_strategy”:“MIN_ROAS”;

• A roas_value_micro 1000000 in an Ad Account using the currency USD, optimizes to deliver $1 for every $1 in spend.
• A roas_value_micro 500000 in an Ad Account using the currency GBP, optimizes to deliver £0.50 for every £1 in spend.
• A roas_value_micro 1500000 in an Ad Account using the currency EUR, optimizes to deliver €1.50 for every €1 in spend.

Placement V2

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

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

The below table outlines the relationship between placement and placement_v2.

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

Placement V2 Specification

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

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

config

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

snapchat_positions

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

Example

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

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

Example 1

Snap Ads running with Automatic placement

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

Example 2

Snap Ads running between User stories only

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

Example 3

Snap Ads running between User stories and Curated content

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

Example 4

Snap Ads running inside of curated content

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

Example 5

Snap Ads running as commercials via premium content bundle

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

Example 6

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

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

Example 7

Story Ad running in the Discover feed

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

Example 8

Lens/Filter Ad placed in the Camera

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

Pacing Types

Validations

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

• bid_strategy must be set to ‘LOWEST_COST_WITH_MAX_BID’
• bid_micro must be set
• optimization_goal must be one of IMPRESSIONS, USES, SWIPES, VIDEO_VIEWS, VIDEO_VIEWS_15_SEC or STORY_OPENS

pacing_type is immutable and can be changed given the correct validations are in place.

Squad Optimization Goals

Goal-Based Bidding (GBB) allows a squad to be optimized toward a specific outcome.

Optimization Goal changes how the squad’s bid_micro is interpreted.

Note: No matter what Optimization Goal is selected, the Billing Event will still be IMPRESSION. This may change in the future.

Optimization Goal	Bid Interpretation	Details
IMPRESSIONS	Cost Per 1000 Impressions (CPM)	bid_micro will not be exceeded
SWIPES	Target Cost Per Swipe	bid_micro is treated as a goal, not a maximum, and can be exceeded
APP_INSTALLS	Target Cost Per Install	bid_micro is treated as a goal, not a maximum, and can be exceeded
VIDEO_VIEWS	Target Cost per 2 second Video View	bid_micro is treated as a goal, not a maximum, and can be exceeded
VIDEO_VIEWS_15_SEC	Target Cost per 15 second Video View	bid_micro is treated as a goal, not a maximum, and can be exceeded
USES	Cost Per Use (of filter)	bid_micro is treated as a goal, not a maximum, and can be exceeded
STORY_OPENS	Target Cost Per Story Open for Story Ads	bid_micro is treated as a goal, not a maximum, and can be exceeded
PIXEL_PAGE_VIEW	Target Cost Per PAGE_VIEW on web	bid_micro is treated as a goal, not a maximum, and can be exceeded
PIXEL_ADD_TO_CART	Target Cost Per ADD_TO_CART on web	bid_micro is treated as a goal, not a maximum, and can be exceeded
PIXEL_PURCHASE	Target Cost Per PURCHASE on web	bid_micro is treated as a goal, not a maximum, and can be exceeded
PIXEL_SIGNUP	Target Cost Per SIGNUP on web	bid_micro is treated as a goal, not a maximum, and can be exceeded
APP_ADD_TO_CART**	Target Cost Per ADD_TO_CART on app	bid_micro is treated as a goal, not a maximum, and can be exceeded
APP_PURCHASE**	Target Cost Per PURCHASE on app	bid_micro is treated as a goal, not a maximum, and can be exceeded
APP_SIGNUP**	Target Cost Per PURCHASE on app	bid_micro is treated as a goal, not a maximum, and can be exceeded
APP_REENGAGE_OPEN	Target Cost Per App open	bid_micro is treated as a goal, not a maximum, and can be exceeded

Optimization goals PIXEL_ADD_TO_CART, PIXEL_PURCHASE, PIXEL_SIGNUP, APP_ADD_TO_CART, APP_PURCHASE and APP_SIGNUP are auto enabled only for ad accounts that meet the following criteria:

• Pixel; Ad Account has Snap Pixel created and installed on website, relevant Pixel events like ADD_TO_CART, SIGNUP and PURCHASE have been configured successfully
• In-App events; App has been set to trigger and pass relevant events, ADD_TO_CART, SIGNUP and PURCHASE via the MMP
• Both; Ad account must be driving at least 50+ attributed conversions for the event over a rolling 7-day period, based on a 28d swipe and 1d view attribution window

Squad Optimization Goal Per Ad Type

This table outlines the Optimization Goals availability per Ad Type.

Optimization Goal	Ad Types
IMPRESSIONS	SNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, FILTER, LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_LONGFORM_VIDEO, LENS_REMOTE_WEBPAGE, LONGFORM_VIDEO, REMOTE_WEBPAGE, STORY, AD_TO_CALL, AD_TO_MESSAGE
SWIPES	AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LONGFORM_VIDEO, REMOTE_WEBPAGE, AD_TO_CALL, AD_TO_MESSAGE
APP_INSTALLS	APP_INSTALL, COLLECTION, DEEP_LINK, STORY
VIDEO_VIEWS	SNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LONGFORM_VIDEO, REMOTE_WEBPAGE
VIDEO_VIEWS_15_SEC	SNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, LONGFORM_VIDEO, REMOTE_WEBPAGE
USES	FILTER, LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_LONGFORM_VIDEO, LENS_REMOTE_WEBPAGE
STORY_OPENS	STORY
PIXEL_PAGE_VIEW	COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY
PIXEL_ADD_TO_CART	COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY
PIXEL_PURCHASE	COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY
PIXEL_SIGNUP	COLLECTION, DEEP_LINK, REMOTE_WEBPAGE, STORY
APP_ADD_TO_CART	APP_INSTALL, COLLECTION, DEEP_LINK, STORY
APP_PURCHASE	APP_INSTALL, COLLECTION, DEEP_LINK, STORY
APP_SIGNUP	APP_INSTALL, COLLECTION, DEEP_LINK, STORY
APP_REENGAGE_OPEN	DEEP_LINK, COLLECTION, STORY (COLLECTION and STORY Ads require deep_link_properties in Creative entity)

Squad Optimization Window

The optimization_window attribute allows you to optimize the AdSquad auction given a desired conversion window.

The optimization_window can only be used in conjunction with one of the following optimization goals, APP_INSTALLS, APP_PURCHASE, APP_SIGNUP, APP_ADD_TO_CART or APP_REENGAGE_OPEN.

Value	Description
SWIPE_28DAY_VIEW_1DAY	28 Day Swipe, 1 Day View
SWIPE_7D	7 Day Swipe

Frequency Cap Spec

Frequency cap spec cap_and_exclusion_config allows you to specify the maximum number of times a user is exposed to an ad over a period of time.

Attribute	Description	Type	Possible Values
frequency_cap_count	Number of times an ad is shown to the user in the interval	integer
frequency_cap_type	Allowed Optimization Goals	string	IMPRESSIONS, SWIPES, VIDEO_VIEWS_15_SEC, VIDEO_VIEWS, STORY_OPENS, USES
time_interval	Interval during which the frequency cap rule is applied. frequency_cap_count is reset at the end of the interval. (Max 30 days or 720 hours)	integer
frequency_cap_interval	Unit for time_interval	string	HOURS, DAYS

"cap_and_exclusion_config": {
    "frequency_cap_config": [
        {
            "frequency_cap_count": 4,
            "frequency_cap_type": "impressions",
            "time_interval": 48,
            "frequency_cap_interval": "hours"
        }
    ]
}

Third-Party Tracking Tags

Snap partners with select vendors are able to use a “tagless” integration, where measurement can be set at the ad squad level, which will then apply to all child ad units within the ad Squad.

Measurement Solution	Vendor Name
Viewability	Moat
Viewability	DoubleVerify

How to Apply Third Party Tracking

To apply third-party tracking for tagless integrations at the ad squad level, set the following value for the appropriate attribute:

Measurement Solution	Vendor Name	Required	Possible values
measurement_provider_names	Flag denotes auto-tagging of all child ads in the ad squad when set to the approved vendor’s enum. Supports Moat viewability tracking	O	MOAT_SS, DOUBLEVERIFY

Ad Scheduling

With ad_scheduling_config, you can explicitly set which days of the week and, to what hours within each day your ads should run.

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

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()

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

The above command returns JSON structured like this:

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

This endpoint retrieves all ads within a specified ad squad.

HTTP Request

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

Parameters

Parameter	Default	Description
ad_squad_id		Ad Squad ID

Get All Ads under an Ad Account

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get()

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

The above command returns JSON structured like this:

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

This endpoint retrieves all ads within a specified ad account.

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Get a Specific Ad

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.ads.get('e8d6217f-32ab-400f-9e54-39a86a7963e4')

curl "https://adsapi.snapchat.com/v1/ads/e8d6217f-32ab-400f-9e54-39a86a7963e4"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

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

This endpoint retrieves a specific ad.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the ad to retrieve

Delete an Ad

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get('f016fc4b-5b2d-44cf-be60-b9e7955829d2')

curl -X DELETE "https://adsapi.snapchat.com/v1/ads/2ded6d53-0805-4ff8-b984-54a7eb5c8918" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b01b6200ff05d100ff30ca9b1d0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010101",
  "ads": []
}

This endpoint deletes a specific ad.

HTTP Request

DELETE https://adsapi.snapchat.com/v1/ads/<ID>

URL Parameters

Parameter	Description
ID	The ID of the ad to delete

Third-Party Tracking Tags

On the 1st of January 2020 we will be sunsetting the fields on_swipe_tracking_urls and third_party_tracking_urls.

From the 1st of January 2020 it won’t be possible to update an Ad entity without removing the third-party tracking from the deprecated fields. This tracking can instead be implemented within the two fields third_party_on_swipe_tracking_urls and third_party_paid_impression_tracking_urls.

If you are trafficking third-party tags to the fields on_swipe_tracking_urls and/or third_party_tracking_urls you should amend your app as soon as possible and make use of the corresponding fields third_party_on_swipe_tracking_urls and third_party_paid_impression_tracking_urls.

Additionally MOAT tracking at Ad level will also be sunset on the 1st of January 2020, for any Ads where you wish to implement MOAT tracking you should instead activate the MOAT tracking at AdSquad level, using the new measurement_provider_names attribute. Activation at AdSquad level will apply MOAT tracking to all Ad entities within the AdSquad.

Snap currently allows third-party tags from DCM, MDAR and Integral Ad Science (IAS). MOAT tracking should be implemented at AdSquad level tracking activation via the measurement_provider_names attribute.

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.ads.create()

curl -X PUT \
  -d '{"ads":[{"id": "ebb64f61-0e12-4f3c-a55c-71a9a6d1ea63", "ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe", "creative_id":"c1e6e929-acec-466f-b023-852b8cacc18f", "name": "Ad One", "type": "SNAP_AD", "status": "ACTIVE", "third_party_paid_impression_tracking_urls": ["https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.222222222;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"],"third_party_on_swipe_tracking_urls": ["https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.333333333;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"]}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "58bb7c5000ff06616e9fa0e86e0001737e616473617069736300016275696c642d33333562626234342d312d35302d330001013d",
  "ads": [
    {
      "sub_request_status": "SUCCESS",
      "ad": {
        "id": "ebb64f61-0e12-4f3c-a55c-71a9a6d1ea63",
        "updated_at": "2017-03-18T00:16:17.690Z",
        "created_at": "2017-03-18T00:16:17.690Z",
        "name": "Ad One",
        "ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe",
        "creative_id": "c1e6e929-acec-466f-b023-852b8cacc18f",
        "third_party_paid_impression_tracking_urls": [
          {
            "trackingUrlMetadata": null,
            "expandedTrackingUrl": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.222222222;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?",
            "tracking_url": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.222222222;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"
          }
        ],
        "third_party_on_swipe_tracking_urls": [
          {
            "trackingUrlMetadata": null,
            "expandedTrackingUrl": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.33333333;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?",
            "tracking_url": "https://ad.doubleclick.net/ddm/trackimp/N0000.1111111SNAPCHAT.COM/B22222222.33333333;dc_trk_aid=111111111;dc_trk_cid=111111111;ord=~.~TIMESTAMP~.~;dc_lat=;dc_rdid=;tag_for_child_directed_treatment=;tfua=?"
          }
        ],
        "status": "PAUSED",
        "type": "SNAP_AD",
        "review_status": "APPROVED"
      }
    }
  ]
}

Additional Ad Attributes

Attribute	Description	Required
third_party_on_swipe_tracking_urls	Third-party swipe tags, executed on swipe of attachment	O
third_party_paid_impression_tracking_urls	Third-party impression tags, executed on ad impression	O
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

• DCM and IAS: Refer to your DCM/IAS Account Manager to request tags or generate them using the campaign management tools.

• mDAR: Clients should request their Snapchat Account Manager to provide a tag.

Notes

• Ensure all tags are secure and use https
• Choose standard type 1x1 pixel and not Javascript or iframe
• Make sure cachebusting parameter is ~.~TIMESTAMP~.~ and not [timestamp]

URL Macros

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

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

Media

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

Attributes

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

Create Media

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

The above command returns JSON structured like this:

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

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Upload Media - Video

Name	Description	Dimensions	File size	File type	Length seconds
Top Snap	Used as Top Snap video in Snap Ads, Top Snap specs	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/<ID>

URL Parameters

Parameter	Description
ID	The ID of the media to retrieve

Get Preview for a Specific Media

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get(2)

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

The above command returns JSON structured like this:

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

This endpoint retrieves the preview for a specific media.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the media to retrieve

Get Thumbnail for a Specific Media

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get(2)

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

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

Creatives

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

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

Attributes

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

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

Creative Types and attachments

Creative Types

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

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

Attachments

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

Create a Snap Ad

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

curl -X POST  \
  -d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837", "name": "Creative Creative", "type": "SNAP_AD", "brand_name": "Maxiumum Brand", "headline": "Healthy Living", "shareable": true}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives

The above command returns JSON structured like this:

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

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Create a Snap Ad with Long form Video attachment

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

Attributes

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

Additional Attributes

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

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

This endpoint creates a Creative within an Ad Account.

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

The above command returns JSON structured like this:

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

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Create a Snap Ad with App Install attachment

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

Attributes

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

Additional Attributes

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

Attribute	Description	Required	Possible Values
app_name	App name	R
ios_app_id	iOS App ID	R
android_app_url	Google Play Store ID	R	(eg “com.x.y”)
icon_media_id	Icon Media ID	R

Icon Media specifications

• Minimum 200 x 200 px, Maximum 2000 x 2000 px
• Must be PNG format
• The image should be square
• The image should not have any borders or padding

Mobile Measurement Partners - Setup Details

• Adjust
• Appsflyer
• Branch
• Kochava
• mParticle
• Singular
• Tenjin

curl -X POST \
  -d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837", "name": "Creative App Install", "type": "APP_INSTALL", "shareable": true, "call_to_action": "INSTALL_NOW", "app_install_properties": {"app_name": "Cool App Yo", "ios_app_id": "447188370", "android_app_url": "com.snapchat.android", "icon_media_id": "ab32d7e5-1f80-4e1a-a76b-3c543d2b28e4"}}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b0163000ff05bee93989450c0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010107",
  "creatives": [
    {
      "sub_request_status": "success",
      "creative": {
        "id": "1c7065c2-ad9f-41cc-b2c5-d48d9810439b",
        "updated_at": "2016-08-14T06:56:48.631Z",
        "created_at": "2016-08-14T06:56:48.631Z",
        "name": "Creative App Install",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "APP_INSTALL",
        "packaging_status": "PENDING",
        "review_status": "PENDING_REVIEW",
        "shareable": true,
        "call_to_action": "INSTALL_NOW",
        "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "top_snap_crop_position": "MIDDLE",
        "app_install_properties": {
          "app_name": "Cool App Yo",
          "ios_app_id": "447188370",
          "android_app_url": "com.snapchat.android",
          "icon_media_id": "ab32d7e5-1f80-4e1a-a76b-3c543d2b28e4"
        }
      }
    }
  ]
}

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Create a Snap Ad with Web View attachment

Web View attachments allow users to swipe up to view a web page, you have the option of preloading the website as directed by the block_preload attribute. You can see more details on preloading and recommendations for optimizations here.

Attributes

Attribute	Description	Required	Possible Values
ad_account_id	Ad Account ID	R
brand_name	Brand Name	R	25 characters max
call_to_action	Call to Action	O	APPLY_NOW, MORE, ORDER_NOW, PLAY, READ, SHOP_NOW, SHOW, SIGN_UP, VIEW, SHOW, WATCH, DOWNLOAD, APPLY_NOW, ORDER_NOW, RESPOND, BUY_TICKETS, SHOWTIMES, BOOK_NOW, GET_NOW, LISTEN, TRY
headline	Headline (displayed under brand name)	R	34 characters max
shareable	Allow Users to Share with Friends	O	true (default), false
name	Creative name	R
top_snap_media_id	Top Snap Media ID	R
top_snap_crop_position	Top Snap Crop Position	O	OPTIMIZED (default), MIDDLE, TOP, BOTTOM
type	Creative Type	R	WEB_VIEW
forced_view_eligibility	Indicates whether Creative can be used as a Commercial, see Commercials section for instructions on how to determine and set this value	O	FULL_DURATION, SIX_SECONDS, NONE

Additional Attributes

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

Attribute	Description	Required	Possible Values
url	Web view URL	R
allow_snap_javascript_sdk	Allow Snapchat Javascript SDK to autofill form fields, with this feature you can request Name, Phone Number and Email to be auto filled if the user agrees	O	true/false (default)
block_preload	Block Snapchat from preloading the web page	O	true/false (default)

curl -X POST \
  -d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837", "name": "Creative WV", "type": "WEB_VIEW", "shareable": true, "call_to_action": "VIEW", "web_view_properties": {"url": "http://snapchat.com/ads"}}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b0168400ff06efecfdcdc8da0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010c",
  "creatives": [
    {
      "sub_request_status": "success",
      "creative": {
        "id": "67e4296c-486b-4bf3-877b-f34e8eeb173c",
        "updated_at": "2016-08-14T06:58:12.768Z",
        "created_at": "2016-08-14T06:58:12.768Z",
        "name": "Creative WV",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "WEB_VIEW",
        "packaging_status": "PENDING",
        "review_status": "PENDING_REVIEW",
        "shareable": true,
        "call_to_action": "VIEW",
        "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "top_snap_crop_position": "MIDDLE",
        "web_view_properties": {
          "url": "http://snapchat.com/ads"
        }
      }
    }
  ]
}

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Create a Snap Ad with Deep Link attachment

The Deep Link attachment allows users who have the app installed to be directed to the location defined in the deep_link_properties, users who do not have the app installed will be directed to the App store to install the app.

If you have a web view with deep links there is no need to specify the deep links in a separate field on the Creative. The deep links inside the web view will be auto detected.

Attributes

Attribute	Description	Required	Possible Values
ad_account_id	Ad Account ID	R
brand_name	Brand Name	R	25 characters max
call_to_action	Call to Action	O	PLAY, SHOP_NOW, SIGN_UP, USE_APP, MORE, OPEN_APP, TRY, WATCH
headline	Headline (displayed under brand name)	R	34 characters max
shareable	Allow Users to Share with Friends	O	true (default), false
name	Creative name	R
top_snap_media_id	Top Snap Media ID	R
top_snap_crop_position	Top Snap Crop Position	O	OPTIMIZED (default), MIDDLE, TOP, BOTTOM
type	Creative Type	R	DEEP_LINK

Additional Attributes

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

Attribute	Description	Required
deep_link_uri	Deep Link URL	R
app_name	App name	R
ios_app_id	iOS App ID	Optional but one of ios_app_id or android_app_url is required
android_app_url	Google Play Store ID	Optional but one of ios_app_id or android_app_url is required
icon_media_id	Icon Media ID	R
fallback_type	Type of fallback to be used when user doesn’t have the app	O
web_view_fallback_url	Fallback web url to be used	O

Icon Media specifications

• Minimum 200 x 200 px, Maximum 2000 x 2000 px
• Must be PNG format
• The image should be square
• The image should not have any borders or padding

curl -X POST \
  -d '{"creatives": [{"name": "Deep Link test","ad_account_id": "{{ad_account_id}}","type": "DEEP_LINK","shareable": true,"headline": "some headline","brand_name": "some brand name","top_snap_media_id": "{{media_id}}","top_snap_crop_position": "MIDDLE","call_to_action": "{{cta}}","deep_link_properties": {"deep_link_uri":"spotify://somelink","ios_app_id": "1234","android_app_url": "com.snapchat.android","app_name": "not hotdog app","icon_media_id": "{{app_icon_media_id}}"}}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b0168400ff06efecfdcdc8da0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010c",
  "creatives": [
    {
      "sub_request_status": "success",
      "creative": {
        "id": "67e4296c-486b-4bf3-877b-f34e8eeb173c",
        "updated_at": "2016-08-14T06:58:12.768Z",
        "created_at": "2016-08-14T06:58:12.768Z",
        "name": "Deep Link test",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "DEEP_LINK",
        "packaging_status": "PENDING",
        "review_status": "PENDING_REVIEW",
        "shareable": true,
        "call_to_action": "VIEW",
        "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "top_snap_crop_position": "MIDDLE",
        "deep_link_properties": {
          "deep_link_uri":"spotify://somelink",
          "ios_app_id": "1234",
          "android_app_url": "com.snapchat.android",
          "app_name": "not hotdog app",
          "icon_media_id": "{{app_icon_media_id}}"
        }
      }
    }
  ]
}

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Create a Snap Ad with Lens attachment

The lens attachment will open up an AR Lens upon swipe up

Attributes

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

Additional Attributes

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

Attribute	Description	Required
lens_media_id	The Media ID of the lens to be opened upon swipe up	R

Lens Media file for a Lens Creative is not uploaded via the API, it’s instead created in Snapchat Lens Studio or Lens Web Builder and then transferred to the Ad Account in question via Lens Studio.

curl -X POST \
  -d '{"creatives": [{"name":"Swipe to Lens","ad_account_id":"0b5176e0-9d5e-467c-8275-c1b619bd87d1","type":"AD_TO_LENS","shareable":true,"headline":"Headline Headline","brand_name":"Best Brand","call_to_action":"TRY","top_snap_media_id":"77f0c0a5-3374-4196-ac71-eb9fce49a5f3","top_snap_crop_position":"MIDDLE","ad_product":"SNAP_AD","ad_to_lens_properties":{"lens_media_id":"708ba95f-74e4-4e95-b443-21ccd2091a96"}}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5b52250700ff0c3438c927b7db0001737e616473617069736300016275696c642d31393039356634322d312d3138352d310001011b",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "0df4bc92-00c8-4a6d-af89-533def1e5750",
                "updated_at": "2018-07-20T14:32:09.102Z",
                "created_at": "2018-07-20T14:29:44.160Z",
                "name": "Swipe to lens",
                "ad_account_id": "0b5176e0-9d5e-467c-8275-c1b619bd87d1",
                "type": "AD_TO_LENS",
                "packaging_status": "SUCCESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "Headline Healine",
                "brand_name": "Best Brand",
                "call_to_action": "TRY",
                "top_snap_media_id": "77f0c0a5-3374-4196-ac71-eb9fce49a5f3",
                "top_snap_crop_position": "MIDDLE",
                "ad_product": "SNAP_AD",
                "ad_to_lens_properties": {
                    "lens_media_id": "708ba95f-74e4-4e95-b443-21ccd2091a96"
                }
            }
        }
    ]
}

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Swipe to Call/Text - Phone number verification

All Phone Numbers used in Swipe to Call/Text Creatives need to be Verified via Snap Ads Manager as we use 2 factor authentication. You can do this by using Snap Ads Manager to set up a first Swipe to Call/Text Creative in your account, this set up will include adding a phone number and verifying it, see this guide for more details on how to verify your phone number.

After successful verification of the phone number you will be able to retrieve a phone number ID for the number in question.

curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/phone_numbers" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5e6fb44400ff098283dd16a12e0001737e616473617069736300016275696c642d31636430373832652d312d3333342d300001010a",
    "paging": {},
    "phone_numbers": [
        {
            "sub_request_status": "SUCCESS",
            "phone_number": {
                "id": "d85758e1-4aac-435d-9660-de29e9b97548",
                "updated_at": "2020-02-06T22:10:46.573Z",
                "created_at": "2020-02-06T22:10:37.609Z",
                "name": "Phone number - Pizza",
                "country_code": "us",
                "numerical_country_code": "1",
                "phone_number": "1111333444",
                "verification_status": "VERIFIED"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "phone_number": {
                "id": "dab10be9-6147-4ef4-9ad5-328f39777625",
                "updated_at": "2020-02-06T22:07:40.452Z",
                "created_at": "2020-02-06T22:07:26.553Z",
                "name": "Phone number - Chicken",
                "country_code": "us",
                "numerical_country_code": "1",
                "phone_number": "1111222333",
                "verification_status": "VERIFIED"
            }
        }
    ]
}

This endpoint retrieves all verified phone numbers for an Ad Account.

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Create a Snap ad with Swipe to Call attachment

Call attachments allow users to swipe up to initiate a call.

Attributes

Attribute	Description	Required	Possible Values
ad_account_id	Ad Account ID	R
brand_name	Brand Name	R	25 characters max
call_to_action	Call to Action	O	OPEN_APP
headline	Headline (displayed under brand name)	R	34 characters max
shareable	Allow Users to Share with Friends	O	true (default), false
name	Creative name	R
top_snap_media_id	Top Snap Media ID	R
top_snap_crop_position	Top Snap Crop Position	O	OPTIMIZED (default), MIDDLE, TOP, BOTTOM
type	Creative Type	R	AD_TO_CALL

Additional Attributes

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

Attribute	Description	Required	Possible Values
phone_number_id	ID of the phone number to be used	R

curl -X POST \
  -d '{"creatives": [{"ad_account_id": "497979f0-ed17-4971-8288-054883f1cbca","name" : "A new AD_TO_CALL Creative","type": "AD_TO_CALL","top_snap_media_id": "2fbaa906-d2d2-423d-b8e3-9535f1281998","ad_product": "SNAP_AD","headline": "Order your meal now","brand_name": "Honey Foods","call_to_action": "OPEN_APP","ad_to_call_properties": {"phone_number_id": "715b6ee0-357c-41d2-9246-feb09c199fc9"}}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/creatives

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5e6fb51900ff040ef4db1db40b0001737e616473617069736300016275696c642d31636430373832652d312d3333342d300001010a",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "dbf052de-139c-4860-9f29-9dc4fa580620",
                "updated_at": "2020-03-16T17:19:24.063Z",
                "created_at": "2020-03-16T17:19:24.063Z",
                "name": "A new AD_TO_CALL Creative",
                "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2",
                "type": "AD_TO_CALL",
                "packaging_status": "IN_PROGRESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "Order your meal now",
                "brand_name": "Honey Foods",
                "call_to_action": "OPEN_APP",
                "render_type": "STATIC",
                "top_snap_media_id": "2fbaa906-d2d2-423d-b8e3-9535f1281998",
                "top_snap_crop_position": "MIDDLE",
                "ad_product": "SNAP_AD",
                "ad_to_call_properties": {
                    "phone_number_id": "715b6ee0-357c-41d2-9246-feb09c199fc9",
                    "message": null
                }
            }
        }
    ]
}

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Create a Snap Ad with Swipe to Text attachment

Text attachments allow users to swipe up to initiate a text message.

Attributes

Attribute	Description	Required	Possible Values
ad_account_id	Ad Account ID	R
brand_name	Brand Name	R	25 characters max
call_to_action	Call to Action	O	OPEN_APP
headline	Headline (displayed under brand name)	R	34 characters max
shareable	Allow Users to Share with Friends	O	true (default), false
name	Creative name	R
top_snap_media_id	Top Snap Media ID	R
top_snap_crop_position	Top Snap Crop Position	O	OPTIMIZED (default), MIDDLE, TOP, BOTTOM
type	Creative Type	R	AD_TO_MESSAGE

Additional Attributes

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

Attribute	Description	Required	Possible Values
phone_number_id	ID of the phone number to be used	R
message	A pre-populated message for the user to send, max 160 characters	O

curl -X PUT \
  -d '{"creatives":[{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2","name" : "A new AD_TO_MESSAGE Creative","type": "AD_TO_MESSAGE",                "top_snap_media_id": "2fbaa906-d2d2-423d-b8e3-9535f1281998","ad_product": "SNAP_AD","headline": "Honey Dating","brand_name": "Dating for honey bears","call_to_action": "OPEN_APP","ad_to_message_properties": {"phone_number_id": "715b6ee0-357c-41d2-9246-feb09c199fc9","message": "Please send me details of Single Polar Bears"}}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/creatives

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5e6fb51900ff040ef4db1db40b0001737e616473617069736300016275696c642d31636430373832652d312d3333342d300001010a",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "48c1a68d-782c-48af-8dba-ceef18d22a3c",
                "updated_at": "2020-03-16T17:19:24.250Z",
                "created_at": "2020-03-16T17:19:24.250Z",
                "name": "A new AD_TO_MESSAGE Creative",
                "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2",
                "type": "AD_TO_MESSAGE",
                "packaging_status": "IN_PROGRESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "Honey Dating",
                "brand_name": "Dating for honey bears",
                "call_to_action": "OPEN_APP",
                "render_type": "STATIC",
                "top_snap_media_id": "2fbaa906-d2d2-423d-b8e3-9535f1281998",
                "top_snap_crop_position": "MIDDLE",
                "ad_product": "SNAP_AD",
                "ad_to_message_properties": {
                    "phone_number_id": "715b6ee0-357c-41d2-9246-feb09c199fc9",
                    "message": "Send me details of Single Polar Bears"
                }
            }
        }
    ]
}

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Create a Story Ad Creative

Story Ad Creatives are made up of two separate creatives, a Preview Creative and a Composite Creative.

The Preview Creative is used to display the thumbnail within the Discover tab of the app, the Composite Creative is used to define the individual Snap Ads that make up the story.

Create the Preview Creative

Additional Attributes

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

Attribute	Description	Required	Possible Values
preview_media_id	Image that is the preview for Story Ads	R
logo_media_id	Logo shown on the tile for Story Ads	R
preview_headline	Preview Headline shown on the tile for Story Ads	R	55 Character limit, emoji unicode characters allowed

Preview Image Specifications - Resolution 3:5 - Minimum dimensions: 360 x 600 px - Maximum file size: 2MB - File Type: png

Logo Specifications - Dimensions: 993 x 284 px - Maximum file size: 2MB - File Type: png

curl -X POST \
  -d '{"creatives": [{"ad_account_id": "0cf0aace-39d4-4502-8656-8f42daa473c7", "name": "Story Ad Preview", "type": "PREVIEW", "preview_properties": {"preview_media_id": "00a76e9f-186c-4ed4-87d7-d58a7dd06749", "logo_media_id": "6d54643b-e6e1-4c50-ab9a-a1f05965bf33", "preview_headline": "test preview headline"}}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/0cf0aace-39d4-4502-8656-8f42daa473c7/creatives

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ae7ac0a00ff09a390a9b9b4d60001737e616473617069736300016275696c642d36393364326336352d312d3136322d3400010101",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "62537bbc-1a3a-4a40-b46f-43d181eac8ee",
                "updated_at": "2018-04-30T23:51:40.466Z",
                "created_at": "2018-04-30T23:51:40.466Z",
                "name": "Story Ad Preview",
                "ad_account_id": "0cf0aace-39d4-4502-8656-8f42daa473c7",
                "type": "PREVIEW",
                "packaging_status": "SUCCESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "top_snap_crop_position": "MIDDLE",
                "preview_properties": {
                    "preview_media_id": "00a76e9f-186c-4ed4-87d7-d58a7dd06749",
                    "logo_media_id": "6d54643b-e6e1-4c50-ab9a-a1f05965bf33",
                    "preview_headline": "test preview headline"
                }
            }
        }
    ]
}

Create the Composite Creative

Additional Attributes

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

Attribute	Description	Required	Possible Values
creative_ids	List of creative ids that make up composite creative	R (For Story Ads)	Creative types SNAP_AD, APP_INSTALL, WEB_VIEW, DEEP_LINK, LONGFORM_VIDEO are supported

Composite creation guidelines - You can have a minimum of 3 and a maximum of 20 creatives within a composite creative - The Creative types listed in creative_ids attribute can be mixed as long as they are of the supported type listed above - Creatives are shown to the user in the order listed at creation - The order of the Creatives is immutable once created - The shareable attribute on the composite overrides the shareable value of the individual creatives

curl -X POST \
  -d '{"creatives": [{"ad_account_id": "0cf0aace-39d4-4502-8656-8f42daa473c7", "name": "First Composite Creative", "type": "COMPOSITE", "headline": "Test headline", "brand_name": "Test brand name",*", "shareable": true, "playback_type": "AUTO_ADVANCING", "preview_creative_id": "62537bbc-1a3a-4a40-b46f-43d181eac8ee", "composite_properties": {"creative_ids": ["2cc52fce-855e-40aa-bb4b-016c2befd8ab", "f9a4b56c-ece0-4da4-bc9d-08c29ef941a2", "9c4b3882-addc-48d9-8503-22f7d03d6309"]}}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ae7b4cb00ff05f9646ae5a400ff0001737e616473617069736300016275696c642d36393364326336352d312d3136322d3400010155",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "d3f4b7a5-e8dc-4e85-8d05-52094e3e3708",
                "updated_at": "2018-05-01T00:28:59.816Z",
                "created_at": "2018-05-01T00:28:59.816Z",
                "name": "First Composite Creative",
                "ad_account_id": "0cf0aace-39d4-4502-8656-8f42daa473c7",
                "type": "COMPOSITE",
                "packaging_status": "IN_PROGRESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "playback_type": "AUTO_ADVANCING",
                "headline": "Test headline",
                "brand_name": "Test brand name",
                "top_snap_crop_position": "MIDDLE",
                "composite_properties": {
                    "creative_ids": [
                        "2cc52fce-855e-40aa-bb4b-016c2befd8ab",
                        "f9a4b56c-ece0-4da4-bc9d-08c29ef941a2",
                        "9c4b3882-addc-48d9-8503-22f7d03d6309"
                    ]
                },
                "preview_creative_id": "62537bbc-1a3a-4a40-b46f-43d181eac8ee"
            }
        }
    ]
}

Create a Lens Creative

Lens Creatives can run both in regular auction and in Reach and Frequency, for creation of Lens creatives see the Lens Section.

curl -X POST \
  -d '{"creatives": [{"name":"Lens Creative","ad_account_id":"0b5176e0-9d5e-467c-8275-c1b619bd87d1","type":"LENS","shareable":true,"headline":"Headline Headline","brand_name":"Best Brand", "top_snap_media_id":"77f0c0a5-3374-4196-ac71-eb9fce49a5f3","ad_product":"LENS"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5b52250700ff0c3438c927b7db0001737e616473617069736300016275696c642d31393039356634322d312d3138352d310001011b",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "0df4bc92-00c8-4a6d-af89-533def1e5750",
                "updated_at": "2018-07-20T14:32:09.102Z",
                "created_at": "2018-07-20T14:29:44.160Z",
                "name": "Lens Creative",
                "ad_account_id": "0b5176e0-9d5e-467c-8275-c1b619bd87d1",
                "type": "LENS",
                "packaging_status": "SUCCESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "Headline Healine",
                "brand_name": "Best Brand",
                "top_snap_media_id": "77f0c0a5-3374-4196-ac71-eb9fce49a5f3",
                "top_snap_crop_position": "MIDDLE",
                "ad_product": "LENS"
            }
        }
    ]
}

Create a Lens Creative with Attachment

You can create a Lens Creative with any of the following attachments and the corresponding field then becomes required. The attachment unit will behave in the same way as it would in a Snap Ad. For measurement, you can also use the Snap Pixel with the attachment if it is a webview, make sure to associate the pixel_id at the Adsquad level. For attributes and examples, see the Lens Section.

Attachment For Lens	Creative Type	Required Field
WEB_VIEW	LENS_WEB_VIEW	web_view_properties
APP_INSTALL	LENS_APP_INSTALL	app_install_properties
LONGFORM_VIDEO	LONGFORM_VIDEO	longform_video_properties
DEEP_LINK	LENS_DEEP_LINK	deep_link_properties

Lens Creatives are also available for Reach and Frequency Campaigns.

curl -X POST \
  -d '{"creatives": [{"name":"Lens Creative","ad_account_id":"0b5176e0-9d5e-467c-8275-c1b619bd87d1","type":"LENS_WEB_VIEW","shareable":true,"headline":"Headline Headline","brand_name":"Best Brand", "top_snap_media_id":"77f0c0a5-3374-4196-ac71-eb9fce49a5f3","ad_product":"LENS", "web_view_properties": {"url": "http://snapchat.com/ads"}}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5b52250700ff0c3438c927b7db0001737e616473617069736300016275696c642d31393039356634322d312d3138352d310001011b",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "0df4bc92-00c8-4a6d-af89-533def1e5750",
                "updated_at": "2018-07-20T14:32:09.102Z",
                "created_at": "2018-07-20T14:29:44.160Z",
                "name": "Lens Creative",
                "ad_account_id": "0b5176e0-9d5e-467c-8275-c1b619bd87d1",
                "type": "LENS_WEB_VIEW",
                "packaging_status": "SUCCESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "Headline Healine",
                "brand_name": "Best Brand",
                "top_snap_media_id": "77f0c0a5-3374-4196-ac71-eb9fce49a5f3",
                "top_snap_crop_position": "MIDDLE",
                "ad_product": "LENS",
                "web_view_properties": {
                  "url": "http://snapchat.com/ads"
                }
            }
        }
    ]
}

Create a Collection Ad Creative

Additional Attributes

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

Attribute	Description	Required	Possible Values
interaction_zone_id	ID of the interaction zone to be used	R
default_fallback_interaction_type	The interation type when user swipes up on the full unit	R	WEB_VIEW, DEEP_LINK (must match the interaction type of the creative elements in the collection)
web_view_properties	Web View properties	Required if default_fallback_interaction_type=WEB_VIEW	Same as web_view_properties for Web View Creative
deep_link_properties	Deep Link properties	Required if default_fallback_interaction_type=DEEP_LINK	Same as deep_link_properties for Creative with deep links

For Collection Ad creatives, call_to_action must be set to null, and the headline property of the interaction zone is used instead.

curl -X POST \
  -d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74","name" : "Collection Ad creative","type": "COLLECTION","top_snap_media_id": "a871dcfd-3970-4917-a44a-b251220ce731","headline": "Collection Ad headline","brand_name": "My brand","collection_properties":{"interaction_zone_id":"a218dc8b-7a79-4da6-9a1c-e5a581c7bd44","default_fallback_interaction_type":"WEB_VIEW","web_view_properties":{"url":"https://snapchat.com"}}}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5bef549b00ff07105bd7e8604d0001737e616473617069736300016275696c642d61353965373533332d312d3232302d3100010144",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "e6ef3dea-0a5a-438e-928d-56726343d121",
                "updated_at": "2018-11-16T23:37:01.555Z",
                "created_at": "2018-11-16T23:37:01.555Z",
                "name": "Collection Ad creative",
                "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
                "type": "COLLECTION",
                "packaging_status": "IN_PROGRESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "Collection Ad headline",
                "brand_name": "My brand",
                "top_snap_media_id": "a871dcfd-3970-4917-a44a-b251220ce731",
                "top_snap_crop_position": "MIDDLE",
                "ad_product": "SNAP_AD",
                "collection_properties": {
                    "interaction_zone_id": "a218dc8b-7a79-4da6-9a1c-e5a581c7bd44",
                    "default_fallback_interaction_type": "WEB_VIEW",
                    "web_view_properties": {
                        "url": "https://snapchat.com",
                        "allow_snap_javascript_sdk": false,
                        "use_immersive_mode": false,
                        "deep_link_urls": [],
                        "block_preload": false
                    }
                }
            }
        }
    ]
}

Update a Creative

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get()

curl -X PUT \
  -d '{"creatives":[{"ad_account_id":"12325ba6-7559-4000-9663-bace8adff5f2","brand_name":"Example Inc","id":"7772efab-028d-40ec-aa9d-7eb8f065c10a","headline":"For all Citrus Fans","web_view_properties":{ "url":"https://www.example.com/intro?utm_source=snapchat&utm_medium=paidsocial&utm_campaign=2019_citrus","allow_snap_javascript_sdk":false,"block_preload":true},"type":"WEB_VIEW","ad_product":"SNAP_AD","top_snap_media_id":"647e6398-7e44-4ae5-a19d-c400b93bce32","top_snap_crop_position":"MIDDLE","name":"Citrus Creative","call_to_action":"LISTEN","shareable":true}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/12325ba6-7559-4000-9663-bace8adff5f2/creatives

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5c3008ed00ff04a89c4d5c66150001737e616473617069736300016275696c642d31326365666331382d312d3232362d3000000003",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "7772efab-028d-40ec-aa9d-7eb8f065c10a",
                "updated_at": "2019-01-11T21:21:50.991Z",
                "created_at": "2018-12-05T16:04:09.772Z",
                "name": "Citrus Creative",
                "ad_account_id": "12325ba6-7559-4000-9663-bace8adff5f2",
                "type": "WEB_VIEW",
                "packaging_status": "IN_PROGRESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "For all Citrus Fans",
                "brand_name": "Example Inc",
                "call_to_action": "LISTEN",
                "top_snap_media_id": "647e6398-7e44-4ae5-a19d-c400b93bce32",
                "top_snap_crop_position": "MIDDLE",
                "web_view_properties": {
                    "url": "https://www.example.com/intro?utm_source=snapchat&utm_medium=paidsocial&utm_campaign=2019_citrus",
                    "allow_snap_javascript_sdk": false,
                    "use_immersive_mode": false,
                    "deep_link_urls": [],
                    "block_preload": true
                },
                "ad_product": "SNAP_AD"
            }
        }
    ]
}

This endpoint will update the specified Creative. Making changes to a creative will impact all ads associated with the creative. These changes will trigger re-review of associated ads and the ads will be paused. Once the ads are re-approved, they will start delivering again.

Attributes that can be updated

Italicized attributes cannot be updated once a Creative is part of an Ad that has started serving.

Attribute	Required
brand_name	R
call_to_action	R
headline	R
shareable	R
name	R
top_snap_media_id	R
preview_creative_id	O
forced_view_eligibility	O

web_view_properties	Required
url	R
allow_snap_javascript_sdk	R
block_preload	R

longform_video_properties	Required
video_media_id	R

app_install_properties	Required
app_name	R
ios_app_id	R
android_app_url	R
icon_media_id	R

deep_link_properties	Required
deep_link_uri	R
app_name	R
ios_app_id	R
android_app_url	R
icon_media_id	R
web_view_fallback_url	R
fallback_type	R

preview_properties	Required
preview_media_id	R
logo_media_id	R
preview_headline	R

composite_properties	Required
creative_ids	R

ad_to_lens_properties	Required
lens_media_id	R

Get All Creatives

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get()

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

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b0171900ff0c73f50d5bd2f10001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010106",
  "creatives": [
    {
      "sub_request_status": "success",
      "creative": {
        "id": "184fe3d0-ff80-4388-8d5f-05c340eff231",
        "updated_at": "2016-08-14T06:54:38.229Z",
        "created_at": "2016-08-14T06:54:38.229Z",
        "name": "Creative LFV",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "LONGFORM_VIDEO",
        "packaging_status": "PENDING",
        "review_status": "PENDING_REVIEW",
        "shareable": true,
        "call_to_action": "WATCH",
        "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "top_snap_crop_position": "MIDDLE",
        "longform_video_properties": {
          "video_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837"
        }
      }
    },
    {
      "sub_request_status": "success",
      "creative": {
        "id": "1c7065c2-ad9f-41cc-b2c5-d48d9810439b",
        "updated_at": "2016-08-14T06:56:48.631Z",
        "created_at": "2016-08-14T06:56:48.631Z",
        "name": "Creative App Install",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "APP_INSTALL",
        "packaging_status": "PENDING",
        "review_status": "PENDING_REVIEW",
        "shareable": true,
        "call_to_action": "INSTALL_NOW",
        "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "top_snap_crop_position": "MIDDLE",
        "app_install_properties": {
          "app_name": "Cool App Yo",
          "ios_app_id": "447188370",
          "android_app_url": "com.snapchat.android",
          "icon_media_id": "ab32d7e5-1f80-4e1a-a76b-3c543d2b28e4"
        }
      }
    },
    {
      "sub_request_status": "success",
      "creative": {
        "id": "313e8415-6294-47d6-b064-5a0d9f21d224",
        "updated_at": "2016-08-14T06:54:52.107Z",
        "created_at": "2016-08-14T06:54:52.107Z",
        "name": "Creative LFV 2",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "LONGFORM_VIDEO",
        "packaging_status": "PENDING",
        "review_status": "PENDING_REVIEW",
        "shareable": true,
        "call_to_action": "WATCH",
        "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "top_snap_crop_position": "MIDDLE",
        "longform_video_properties": {
          "video_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837"
        }
      }
    },
    {
      "sub_request_status": "success",
      "creative": {
        "id": "67e4296c-486b-4bf3-877b-f34e8eeb173c",
        "updated_at": "2016-08-14T06:58:12.768Z",
        "created_at": "2016-08-14T06:58:12.768Z",
        "name": "Creative WV",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "WEB_VIEW",
        "packaging_status": "PENDING",
        "review_status": "PENDING_REVIEW",
        "shareable": true,
        "call_to_action": "VIEW_MORE",
        "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "top_snap_crop_position": "MIDDLE",
        "web_view_properties": {
          "url": "http://snapchat.com/ads"
        }
      }
    },
    {
      "sub_request_status": "success",
      "creative": {
        "id": "c1e6e929-acec-466f-b023-852b8cacc18f",
        "updated_at": "2016-08-14T06:45:04.300Z",
        "created_at": "2016-08-14T06:45:04.300Z",
        "name": "Creative Creative",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "type": "SNAP_AD",
        "packaging_status": "PENDING",
        "review_status": "PENDING_REVIEW",
        "shareable": true,
        "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837",
        "top_snap_crop_position": "MIDDLE"
      }
    }
  ]
}

This endpoint retrieves all creatives associated with an ad account.

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Get a Specific Creative

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get(2)

curl "https://adsapi.snapchat.com/v1/creatives/c1e6e929-acec-466f-b023-852b8cacc18f" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

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

This endpoint retrieves a specific Creative.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the creative to retrieve

Get Snapcode preview for a Creative

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get(2)

curl "https://adsapi.snapchat.com/v1/creatives/c1e6e929-acec-466f-b023-852b8cacc54f/snapcode" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5aa15e8000ff03acde535d9a200001737e616473617069736300016275696c642d62633562363761342d312d3134372d3600013326",
    "creative_id": "c1e6e929-acec-466f-b023-852b8cacc54f",
    "expires_at": "2018-03-09T15:51:33.248Z",
    "snapcode_link": "https://adsapisc.appspot.com/snapcodeimage/c1e6e929-acec-466f-b023-852b8cacc54f/352a899e-4a9d-3fdf-8efe-9bac9b8a0a21"
}

This endpoint retrieves the snapcode preview for a specific creative.

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the creative to retrieve

Commercials

Commercials are non-skippable video Snap Ads that allow you to drive awareness within Snap’s high-quality premium content.

A commercial is not a separate entity in the API, rather Creatives are eligible to be used as commercials given that they match a set of criteria including the length of the top snap video and the Creative type.

When this type of Creative is used in an Ad and targeted at Snap’s premium content bundles and/or Snap Games, it will automatically run as a commercial within that content.

Media requirements

The Media entity used as top snap in the Creative needs to be of the type VIDEO, the length of the video along with the Creative type will then determine if the Creative can be used as a Commercial or not.

Video media with duration_in_seconds of a minimum of 3 seconds are eligible to be used in a Creative with the intent of running as a Commercial.

Media of the type IMAGE are not eligible to be used as Commercials.

Media Attribute	Value
type	VIDEO
duration_in_seconds	3 second minimum

Creative requirements

Only Snap Ads can run as Commercials, the only allowed attachments are Webview, Long Form Video and AR Lens.

Creative attribute	Value
type	AD_TO_LENS, LONGFORM_VIDEO, SNAP_AD, WEB_VIEW

The attribute forced_view_eligibility needs to be set on the Creative entity, this indicates whether a Creative is eligible to be used as a Commerical or not, and for how long the Creative will be unskippable.

The forced_view_eligibility is based on the lengh of the Media entity used as top_snap_media_id and the intended Creative type.

Creatives classified as FULL_DURATION qualify to run as Commercials and will be unskippable for the full length of the Video, Creatives classified as SIX_SECONDS qualify to run as Commercials and will be unskippable for the first six seconds of the video, the rest of the video will be skippable.

Creatives of any other type than AD_TO_LENS, LONGFORM_VIDEO, SNAP_AD, WEB_VIEW are not eligible to run as commercials and should have the forced_view_eligibility set to NONE.

Top Snap Video length	Creative type	forced_view_eligibility value	Description
3 - 6 seconds	AD_TO_LENS, LONGFORM_VIDEO, SNAP_AD, WEB_VIEW	FULL_DURATION	The full length of the video will be unskippable
7 seconds or longer	AD_TO_LENS, LONGFORM_VIDEO, SNAP_AD, WEB_VIEW	SIX_SECONDS	The first six seconds of the video will be unskippable
any	APP_INSTALL, DEEP_LINK, PREVIEW, COMPOSITE, LENS, COLLECTION,LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_LONGFORM_VIDEO	NONE	Creative type is not eligible to run as a Commercial

AdSquad Targeting

Commercials can only be used in AdSquads that targets one of the following country codes; US, UK, AU, CA, FR, SA, AE, DE, NO, KW and IE.

Additionally the AdSquad needs to specify either INSTREAM in snapchat_positions and the premium_content_bundle_ids targeted, or GAMES in the snapchat_positions, this specifies the content that the Commercials are shown in.

placement_v2 attribute	Value
config	CUSTOM
platforms	SNAPCHAT
snapchat_positions	INSTREAM, GAMES
inclusion	premium_content_bundle_ids

Premium Content Bundles and Snap Games

The premium content bundles represent the content where commercials can be shown, the bundles are meant to be used in a mutually exclusive manner, if you target multiple bundles you will run Commercials on all targeted content.

ID	Description
c7e251af-3606-4f03-91f1-98456161655d	Run of Lifestyle, Sports Shows (no News) Only
1856c724-7cec-4139-a8a8-b87fc609f13e	Run of Shows (including News) Only

Creatives can also run as Commercials within Snap Games, this placement is achieved by specifying GAMES within snapchat_positions.

Fetching a Media entity to inspect type and duration_in_seconds

curl "https://adsapi.snapchat.com/v1/media/5f186aa6-51e4-4c86-95fc-f273e33247e4" \
  -H "Authorization: Bearer meowmeowmeow"

If the Media entity type is VIDEO and the duration_in_seconds is 3 seconds or longer it can be used in a Creative intended to run as a Commercial.

In this case the duration_in_seconds is 5.25 seconds meaning this Media can be used to set up a Creative with the forced_view_eligibility attribute set to FULL_DURATION.

The above request returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5db307d500ff0113ad83cc14370001737e616473617069736300016275696c642d63396263633066392d312d3239392d3100010161",
    "media": [
        {
            "sub_request_status": "SUCCESS",
            "media": {
                "id": "5f186aa6-51e4-4c86-95fc-f273e33247e1",
                "updated_at": "2017-10-17T12:32:09.493Z",
                "created_at": "2017-10-17T12:31:19.069Z",
                "name": "6569282748022784.mp4",
                "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
                "type": "VIDEO",
                "media_status": "READY",
                "file_name": "6569282748022784.mp4",
                "download_link": "https://storage.googleapis.com/rsp-ads-prod/22225ba6-7559-4000-9663-bace8adff5f2/6569282748022784.mp4",
                "duration_in_seconds": 6.72,
                "video_metadata": {
                    "width_px": 1080,
                    "height_px": 1920,
                    "rotation": null,
                    "integrated_loudness": -18.2,
                    "true_peak": -8.1
                },
                "file_size_in_bytes": 6061140,
                "is_demo_media": false,
                "hash": "3WQFkg=="
            }
        }
    ]
}

Create a Creative with the attribute forced_view_eligibility

curl -X POST  \
  -d '{
    "creatives": [
            {
                "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
                "name" : "Honey Badger - Webview - Commercial - FULL_TIME",
                "type": "WEB_VIEW",
                "headline": "Honey Badger Motion Picture",
                "brand_name": "Honey Badger Movies",
                "shareable": false,
                "forced_view_eligibility": "FULL_DURATION",
                "call_to_action": "WATCH",
                "top_snap_media_id": "5f186aa6-51e4-4c86-95fc-f273e33247e1",
                "web_view_properties": {
                    "url": "http://snapchat.com/ads"
                }
            }
        ]
}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/creatives

Having checked the type and duration_in_seconds of the Media used in top_snap_media_id we know we can set the attribute forced_view_eligibility to the value FULL_DURATION, this will allow the Creative to be used as a Commercial which is unskippable for it’s full duration.

The above request returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5db309da00ff04a2bcf03681950001737e616473617069736300016275696c642d63396263633066392d312d3239392d3100010106",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "2edef461-6998-4dd6-9afe-2ee2bf0d5b6c",
                "updated_at": "2019-10-25T14:42:35.810Z",
                "created_at": "2019-10-25T14:42:35.810Z",
                "name": "Honey Badger - Webview - Commercial - FULL_TIME",
                "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
                "type": "WEB_VIEW",
                "packaging_status": "IN_PROGRESS",
                "review_status": "PENDING_REVIEW",
                "shareable": false,
                "forced_view_eligibility": "FULL_DURATION",
                "headline": "Honey Badger Motion Picture",
                "brand_name": "Honey Badger Movies",
                "call_to_action": "WATCH",
                "render_type": "STATIC",
                "top_snap_media_id": "5f186aa6-51e4-4c86-95fc-f273e33247e4",
                "top_snap_crop_position": "MIDDLE",
                "web_view_properties": {
                    "url": "http://snapchat.com/ads",
                    "allow_snap_javascript_sdk": false,
                    "use_immersive_mode": false,
                    "deep_link_urls": [],
                    "block_preload": false
                },
                "ad_product": "SNAP_AD"
            }
        }
    ]
}

Creating an AdSquad that targets premium bundles

curl -X POST  \
  -d '{
"adsquads":[
            {
                "campaign_id":"44f535d7-fde6-4b72-b76d-2d8ccf03f591",
                "name":"Ad Squad - Commercial test",
                "type":"SNAP_ADS",
                "placement":"SNAP_ADS",
                "optimization_goal":"IMPRESSIONS",
                "daily_budget_micro":1000000000,
                "billing_event":"IMPRESSION",
                "auto_bid":true,
                "target_bid":false,
                "targeting":{
                    "regulated_content":false,
                    "geos":[
                    {
                        "country_code":"uk"
                    }
                    ]
                },
                "placement_v2":{
                    "config":"CUSTOM",
                    "platforms":[
                    "SNAPCHAT"
                    ],
                "snapchat_positions":[
                "INSTREAM"
                    ],
                "inclusion":{
                "premium_content_bundle_ids":[
                "31b1a5e4-2193-4542-affe-9ce62b7b17b8"
                ]
                }
                },
                "start_time":"2019-10-27T13:08:53.873Z",
                "pixel_id":"5eda10b7-a5fe-4ac6-80f4-417e68d748fb",
                "delivery_constraint":"DAILY_BUDGET",
                "pacing_type":"STANDARD"
                }
            ]
            }' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/campaigns/44f535d7-fde6-4b72-b76d-2d8ccf03f591/adsquads

In the placement_v2 we specify the bundle id 31b1a5e4-2193-4542-affe-9ce62b7b17b8 , this represents content made up of Lifestyle and Sports Shows (no News shows), the bundle also includes Games.

The above request returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5db063be00ff00ffff004124e334240001737e616473617069736300016275696c642d30623936353833662d312d3239382d3500010111",
    "adsquads": [
        {
            "sub_request_status": "SUCCESS",
            "adsquad": {
                "id": "e711d041-184d-4fd8-a3df-d957c83699d4",
                "updated_at": "2019-10-23T14:29:19.252Z",
                "created_at": "2019-10-23T14:29:19.252Z",
                "name": "Ad Squad - Commercial test",
                "status": "ACTIVE",
                "campaign_id": "44f535d7-fde6-4b72-b76d-2d8ccf03f591",
                "type": "SNAP_ADS",
                "targeting": {
                    "regulated_content": false,
                    "geos": [
                        {
                            "country_code": "uk"
                        }
                    ]
                },
                "placement_v2": {
                    "config": "CUSTOM",
                    "platforms": [
                        "SNAPCHAT"
                    ],
                    "snapchat_positions": [
                        "INSTREAM"
                    ],
                    "inclusion": {
                        "premium_content_bundle_ids": [
                            "31b1a5e4-2193-4542-affe-9ce62b7b17b8"
                        ]
                    }
                },
                "billing_event": "IMPRESSION",
                "auto_bid": true,
                "target_bid": false,
                "daily_budget_micro": 1000000000,
                "start_time": "2019-10-27T13:08:53.873Z",
                "optimization_goal": "IMPRESSIONS",
                "pixel_id": "5eda10b7-a5fe-4ac6-80f4-417e68d748fb",
                "delivery_constraint": "DAILY_BUDGET",
                "pacing_type": "STANDARD"
            }
        }
    ]
}

Create an Ad using the Creative

curl -X POST  \
  -d '{
  "ads": [
    {
      "ad_squad_id": "e711d041-184d-4fd8-a3df-d957c83699d1",
      "creative_id": "2edef461-6998-4dd6-9afe-2ee2bf0d5b61",
      "name": "Honey Badger Motion Picture - Ad - Commercial - FULL_DURATION",
      "type": "REMOTE_WEBPAGE",
      "status": "ACTIVE"
    }
  ]
}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adsquads/e711d041-184d-4fd8-a3df-d957c83699d4/ads

Finally we set up an Ad using the Creative that is eligible to serve as a Commercial and set the Ad to the AdSquad that targets premium content bundles, there are no other Commercial specific requirements for the Ad entity.

The above request returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5db3155c00ff01f1ce6a554ee80001737e616473617069736300016275696c642d63396263633066392d312d3239392d3100010152",
    "ads": [
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "586e41db-54cd-481c-a512-e8852e74df3b",
                "updated_at": "2019-10-25T15:31:40.646Z",
                "created_at": "2019-10-25T15:31:40.646Z",
                "name": "Honey Badger Motion Picture - Ad - Commercial - FULL_DURATION",
                "ad_squad_id": "e711d041-184d-4fd8-a3df-d957c83699d1",
                "creative_id": "2edef461-6998-4dd6-9afe-2ee2bf0d5b61",
                "status": "ACTIVE",
                "type": "REMOTE_WEBPAGE",
                "render_type": "STATIC",
                "review_status": "PENDING"
            }
        }
    ]
}

Creative Elements

A Creative Element is an individual unit that is combined with other Creative Elements to create a Collection Ad Creative.

Attributes

Attribute	Description	Required	Possible Values
ad_account_id	Ad Account ID	R
name	Creative Element name	R
type	Creative Type	R	BUTTON
interaction_type	Type of interaction to be used on the element	R	WEB_VIEW, DEEP_LINK
description	Description of the creative element	O
title	Title of the creative element	O
button_properties	Properties of the button like the image to be shown	R (for type=BUTTON)
web_view_properties	Properties of the web view to be used	R (if interaction_type=WEB_VIEW)
deep_link_properties	Properties of the deep link to be used	R (if interaction_type=DEEP_LINK)

Additional Attributes

button_properties object must contain the following attributes

Attribute	Description	Required	Possible Values
button_overlay_media_id	The image to be used for the button tile	R	See MediaMust be at least 120 X 120px. Max size: 2MB

web_view_properties object must contain the following attributes

Attribute	Description	Required	Possible Values
url	Web view URL	R
allow_snap_javascript_sdk	Allow Snapchat Javascript SDK to autofill form fields	O	true/false
block_preload	Block Snapchat from preloading the web page	O	true/false

deep_link_properties object must contain the following attributes

Attribute	Description	Required
deep_link_uri	Deep Link URL	R
app_name	App name	R
ios_app_id	iOS App ID	Optional but one of ios_app_id or android_app_url is required
android_app_url	Google Play Store ID	Optional but one of ios_app_id or android_app_url is required
icon_media_id	Icon Media ID	R
fallback_type	Type of fallback to be used when user doesn’t have the app	O
web_view_fallback_url	Fallback web url to be used	O

Create a Creative Element

curl -X POST  \
  -d '{"creative_elements": [{"name":"Product 1 button", "type":"BUTTON", "description": "Product 1", "interaction_type":"WEB_VIEW", "title":"Best title", "button_properties":{"button_overlay_media_id":"008a5ae9-bcc1-4c2e-a3f1-7e924d582019"},"web_view_properties":{"url":"https://snapchat.com"}}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creative_elements

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5bee332000ff06b565385cab550001737e616473617069736300016275696c642d33373039663463642d312d3232302d3000010145",
    "creative_elements": [
        {
            "sub_request_status": "SUCCESS",
            "creative_element": {
                "id": "f63bb5f5-471c-404f-8f0d-e5c1a003e4d9",
                "updated_at": "2018-11-16T03:01:52.907Z",
                "created_at": "2018-11-16T03:01:52.907Z",
                "name": "Product 1 button",
                "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
                "type": "BUTTON",
                "interaction_type": "WEB_VIEW",
                "title": "Best title",
                "description": "Product 1",
                "button_properties": {
                    "button_overlay_media_id": "008a5ae9-bcc1-4c2e-a3f1-7e924d582019"
                },
                "web_view_properties": {
                    "url": "https://snapchat.com",
                    "allow_snap_javascript_sdk": false,
                    "use_immersive_mode": false,
                    "deep_link_urls": [],
                    "block_preload": false
                }
            }
        }
    ]
}

Create Multiple Creative Elements

curl -X POST  \
  -d '{"creative_elements": [{"name":"Product 1 button", "type":"BUTTON", "description": "Product 1", "interaction_type":"WEB_VIEW", "title":"Best title", "button_properties":{"button_overlay_media_id":"008a5ae9-bcc1-4c2e-a3f1-7e924d582019"},"web_view_properties":{"url":"https://snapchat.com"}}, {"name":"Product 2 button", "type":"BUTTON", "description": "Product 2", "interaction_type":"WEB_VIEW", "title":"Best title", "button_properties":{"button_overlay_media_id":"008a5ae9-bcc1-4c2e-a3f1-7e924d582012"},"web_view_properties":{"url":"https://snapchat2.com"}}, {"name":"Product 3 button", "type":"BUTTON", "description": "Product 3", "interaction_type":"WEB_VIEW", "title":"Best title", "button_properties":{"button_overlay_media_id":"008a5ae9-bcc1-4c2e-a3f1-7e924d582013"},"web_view_properties":{"url":"https://snapchat3.com"}}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creative_elements

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5bee33f200ff057a031dfee6af0001737e616473617069736300016275696c642d33373039663463642d312d3232302d300001011a",
    "creative_elements": [
        {
            "sub_request_status": "SUCCESS",
            "creative_element": {
                "id": "70debf44-cb4b-4b5f-8828-bd2b68b9f0ca",
                "updated_at": "2018-11-16T03:05:23.241Z",
                "created_at": "2018-11-16T03:05:23.241Z",
                "name": "Product 1 button",
                "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
                "type": "BUTTON",
                "interaction_type": "WEB_VIEW",
                "title": "Best title",
                "description": "Product 1",
                "button_properties": {
                    "button_overlay_media_id": "008a5ae9-bcc1-4c2e-a3f1-7e924d582019"
                },
                "web_view_properties": {
                    "url": "https://snapchat.com",
                    "allow_snap_javascript_sdk": false,
                    "use_immersive_mode": false,
                    "deep_link_urls": [],
                    "block_preload": false
                }
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "creative_element": {
                "id": "a2d1c8a0-0466-4924-b769-7a7e6ed5be3d",
                "updated_at": "2018-11-16T03:05:23.241Z",
                "created_at": "2018-11-16T03:05:23.241Z",
                "name": "Product 2 button",
                "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
                "type": "BUTTON",
                "interaction_type": "WEB_VIEW",
                "title": "Best title",
                "description": "Product 2",
                "button_properties": {
                    "button_overlay_media_id": "008a5ae9-bcc1-4c2e-a3f1-7e924d582012"
                },
                "web_view_properties": {
                    "url": "https://snapchat.com",
                    "allow_snap_javascript_sdk": false,
                    "use_immersive_mode": false,
                    "deep_link_urls": [],
                    "block_preload": false
                }
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "creative_element": {
                "id": "4091233e-3351-405d-8684-a97e70c3b5da",
                "updated_at": "2018-11-16T03:05:23.242Z",
                "created_at": "2018-11-16T03:05:23.242Z",
                "name": "Product 3 button",
                "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
                "type": "BUTTON",
                "interaction_type": "WEB_VIEW",
                "title": "Best title",
                "description": "Product 3",
                "button_properties": {
                    "button_overlay_media_id": "008a5ae9-bcc1-4c2e-a3f1-7e924d582013"
                },
                "web_view_properties": {
                    "url": "https://snapchat.com",
                    "allow_snap_javascript_sdk": false,
                    "use_immersive_mode": false,
                    "deep_link_urls": [],
                    "block_preload": false
                }
            }
        }
    ]
}

Create an Interaction Zone

Attributes

Attribute	Description	Required	Possible Values
ad_account_id	Ad Account ID	R
name	Creative Element name	R
headline	Headline for the interaction zone	R	Same as all allowed call_to_action values for Web View Creative
creative_elements	Array of Creative Element IDs	R	Must have at least 4 creative elements.

curl -X POST  \
  -d '{"interaction_zones": [{"name": "First Interaction Zone", "creative_element_ids": ["d28427e5-0604-406c-8f23-167b211a3317","dc80a56f-800c-499b-846b-78e74bd39a9d","75a98c65-1e62-4507-97fe-50cbc523523a","faefe7cd-567d-4647-bb1d-b918fb0ac98a", "f63bb5f5-471c-404f-8f0d-e5c1a003e4d9"], "headline":"MORE"}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/interaction_zones

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5bee38df00ff00ff5858a22dbc9f0001737e616473617069736300016275696c642d33373039663463642d312d3232302d3000010154",
    "interaction_zones": [
        {
            "sub_request_status": "SUCCESS",
            "interaction_zone": {
                "id": "a218dc8b-7a79-4da6-9a1c-e5a581c7bd46",
                "updated_at": "2018-11-16T03:26:23.130Z",
                "created_at": "2018-11-16T03:26:23.130Z",
                "name": "First Interaction Zone",
                "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
                "headline": "MORE",
                "creative_element_ids": [
                    "70debf44-cb4b-4b5f-8828-bd2b68b9f0cf",
                    "a2d1c8a0-0466-4924-b769-7a7e6ed5be3b",
                    "4091233e-3351-405d-8684-a97e70c3b5dc",
                    "f63bb5f5-471c-404f-8f0d-e5c1a003e4d9"
                ]
            }
        }
    ]
}

Targeting

The API offers a variety of Targeting options to allow an advertiser to find the right user at the right time.

There are a variety of endpoints offered that expose the available targeting options.

Targeting Spec

The targeting spec should be constructed based on the possible dimensions outlined below.

Attribute	Description	Required	Note
demographics	List of Demographic Targets	O	Required when using Multi-country targeting
devices	List of Device Targets	O
geos	List of Geo/Location Targets	R	Multi-country targeting is allowed from 1st April 2020, each country needs to be placed in a geos entry, a targeting spec that uses multi-country targeting needs to also include a demographics entry that incorporates a single languages entry
interests	List of Interest Targets	O
locations	List of Location categories/Circles	O
regulated_content	Flag to mark content within the Ad Squad as Regulated Content	O	FALSE (default), TRUE
segments	List of Snap Audience Match Segment Targets	O
enable_targeting_expansion	Boolean, enabling this allows Snapchat to expand the audience beyond the selected targeting	O	FALSE, TRUE

General Guidance

In general, dimensions that are grouped within the same JSON object is in AND relation. JSON objects within a JSON array are in OR relation. The exception to this is EXCLUDE, which is always AND and applied last.

Targeting Inclusion / Exclusion

Category	Type	Support	Description
demographics	gender, languages, age_group, min_age, max_age, DLXD	INCLUDE	Gender, Language, Age Groups, Age Range, Advanced Demographics
devices	connection_type, os_type, os_version, carrier, marketing_name	INCLUDE	Connection type, OS Type, OS Version, Carrier, Make
geos	country	INCLUDE/EXCLUDE	Multi-country targeting is allowed from 1st April 2020, each country needs to be placed in a geos entry, a targeting spec that uses multi-country targeting needs to also include a demographics entry that incorporates a single languages entry
geos	region	INCLUDE/EXCLUDE	Region/State
geos	metro	INCLUDE/EXCLUDE	Metro/DMA
geos	postal_code	INCLUDE/EXCLUDE	Zipcode/Post code
interests	SLC	INCLUDE/EXCLUDE	Snap Lifestyle Categories
interests	DLX, DLXS, DLXC, NLN	INCLUDE	Oracle Datalogix DLX/DLXS/DLXC Interest Targeting, Nielsen Interest Targeting
locations	categories_loi, circles	INCLUDE	Location Categories, Location Point Radius
segments	segment_id	INCLUDE/EXCLUDE	Snap Audience Match, Pixel Custom Audiences, Mobile Audiences, Engagement Audiences

Targeting Dimensions

All targeting dimensions will now have a deprecated boolean flag that will show whether the targeting dimension is deprecated. If a dimension has deprecated=true you will no longer be able to use it in the targeting_spec of an Ad Squad.

Targeting Type Support by Country

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.get()

curl "https://adsapi.snapchat.com/v1/targeting/options/US" \
  -H "Authorization: Bearer  meowmeowmeow"

The above command returns JSON structured like this:

 {
  "request_status": "SUCCESS",
  "request_id": "58db128000099520da4b9237",
  "targeting_option": {
    "snap_ads": [
      "demographics:advanced_demographics",
      "demographics:age_groups",
      "demographics:gender",
      "devices:carrier",
      "devices:connection_type",
      "devices:os_type",
      "geos:country",
      "geos:metro",
      "geos:region",
      "interests:dlxc",
      "interests:dlxs",
      "interests:slc",
      "regulated_content",
      "segments:ab_segments",
      "segments:engagement",
      "segments:first_party",
      "segments:lookalike"
    ]
  }
}

This endpoint retrieves all targeting options available for the specified country code.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/options/{country_code}

Parameters

Parameter	Default	Description
country_code		ISO ALPHA-2 Country Code (lowercase)

Demographics

Demographics targeting allows an advertiser to find a user based on a variety of criteria.

Demographics - Age Groups

Get Age Group Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.demographics.age_groups()

curl "https://adsapi.snapchat.com/v1/targeting/demographics/age_group" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "57d1cb6900ff0c21bb32e920a00001737e616473617069736300016275696c642d66333735626434642d312d31332d3700010111",
  "targeting_dimensions": [
    {
      "sub_request_status": "SUCCESS",
      "age_group": {
        "name": "13-17",
        "id": "13"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "age_group": {
        "name": "18-20",
        "id": "18"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "age_group": {
        "name": "21-24",
        "id": "21"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "age_group": {
        "name": "25-34",
        "id": "25"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "age_group": {
        "name": "35+",
        "id": "35"
      }
    }
  ]
}

This endpoint retrieves the list of age group targeting options.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/demographics/age_group

Demographics - Age Range

You can target ages using “min_age” and “max_age” attributes without using predefined age groups. Leaving out “max_age” from the targeting_spec will result in no age cap. Leaving out “min_age” will target 13 as the minimum age.

Attribute	Description	Possible values
min_age	35+ is deprecated but may be found in existing ad squads	35+
min_age	integer, defines the minimum age targeted	13 - 35
max_age	integer, defines the maximum age targeted. If you want no maximum cap, do not set a max_age	13 - 49

See the Targeting Spec Examples for usage examples.

Demographics - Gender

Get Gender Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.demographics.genders()

curl "https://adsapi.snapchat.com/v1/targeting/demographics/gender" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "57d1cb8800ff01f6194d8f9a100001737e616473617069736300016275696c642d66333735626434642d312d31332d370001010f",
  "targeting_dimensions": [
    {
      "sub_request_status": "SUCCESS",
      "gender": {
        "name": "MALE",
        "id": "1"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "gender": {
        "name": "FEMALE",
        "id": "2"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "gender": {
        "name": "OTHER",
        "id": "3"
      }
    }
  ]
}

This endpoint retrieves the list of gender targeting options.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/demographics/gender

Demographics - Language

Get Language Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.demographics.languages()

curl "https://adsapi.snapchat.com/v1/targeting/demographics/languages" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "591e4d8c00ff065b2527b9753e0001737e616473617069736300016275696c642d31616566313737632d312d36382d3000010156",
  "targeting_dimensions": [
    {
      "sub_request_status": "SUCCESS",
      "languages": {
        "id": "ar",
        "name": "Arabic"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "languages": {
        "id": "en",
        "name": "English"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "languages": {
        "id": "es",
        "name": "Spanish"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "languages": {
        "id": "zh",
        "name": "Chinese"
      }
    }
  ]
}

This endpoint retrieves the list of language targeting options.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/demographics/languages

Demographics - Advanced Demographics

Get Advanced Demographics Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.demographics.advanced_demographics()

curl "https://adsapi.snapchat.com/v1/targeting/demographics/advanced_demographics" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "57d1cb6900ff0c21bb32e920a00001737e616473617069736300016275696c642d66333735626434642d312d31332d3700010111",
    "targeting_dimensions": [
        {
            "sub_request_status": "SUCCESS",
            "advanced_demographics": {
                "name": "College Graduates",
                "id": "DLXD_100"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "advanced_demographics": {
                "name": "Married People",
                "id": "DLXD_300"
            }
        }
    ]
}

This endpoint retrieves the list of Advanced Demographics targeting options.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/demographics/advanced_demographics

Device

Device targeting allows an advertiser to find a user based on a variety of criteria regarding the user’s mobile device.

Device - Connection Type

Get Connection Type Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.device.connection_types()

curl "https://adsapi.snapchat.com/v1/targeting/device/connection_type"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "status": "success",
  "request_id": "57abbd65000543a87d7116e2",
  "targeting_dimensions": [
    {
      "sub_request_status": "success",
      "connection_type": {
        "name": "WIFI",
        "id": "1"
      }
    },
    {
      "sub_request_status": "success",
      "connection_type": {
        "name": "CELL",
        "id": "2"
      }
    }
  ]
}

This endpoint retrieves the list of device connection type targeting options.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/device/connection_type

Device - OS Type

Get Device OS Type Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.device.os_types()

curl "https://adsapi.snapchat.com/v1/targeting/device/os_type"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "status": "success",
  "request_id": "57abbe48000da048b37f6ddc",
  "targeting_dimensions": [
    {
      "sub_request_status": "success",
      "os_type": {
        "name": "iOS",
        "id": "1"
      }
    },
    {
      "sub_request_status": "success",
      "os_type": {
        "name": "ANDROID",
        "id": "2"
      }
    }
  ]
}

This endpoint retrieves the list of device OS type targeting options.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/device/os_type

Device - OS Version

Get Device OS Version Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.device.os_types()

curl "https://adsapi.snapchat.com/v1/targeting/device/iOS/os_version"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5913bd1900ff0878f97f6fb40f0001737",
  "targeting_dimensions": [
    {
      "sub_request_status": "SUCCESS",
      "os_version": {
        "id": "1970324836974592",
        "name": "7.0"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "os_version": {
        "id": "1970333426909184",
        "name": "7.0.2"
      }
    },
    [[snip]]
    {
      "sub_request_status": "SUCCESS",
      "os_version": {
        "id": "2818056891924480",
        "name": "10.3.2"
      }
    }
  ]
}

This endpoint retrieves the list of device OS version targeting options. These OS versions can then be used in targeting as os_version_min and os_version_max.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/device/{{OS_TYPE}}/os_version

Parameter	Possible Values
OS_TYPE	iOS, ANDROID

Device - Carrier

Get Device Carrier Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.device.carriers()

curl "https://adsapi.snapchat.com/v1/targeting/device/carrier"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5833291400ff098fc49db751b80001737e616473617069736300016275696c642d32663033323832622d646d612d63617272696572320001011e",
  "targeting_dimensions": [
    {
      "sub_request_status": "SUCCESS",
      "carrier": {
        "id": "US_ATT",
        "name": "AT&T",
        "valid_country": "us"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "carrier": {
        "id": "US_BOOSTMOBILE",
        "name": "Boost Mobile",
        "valid_country": "us"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "carrier": {
        "id": "US_CSPIRE",
        "name": "C Spire",
        "valid_country": "us"
      }
    }
  ]
}

This endpoint retrieves the list of device carrier targeting options.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/device/carrier

Device - Make

Get Device Make Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.device.marketingname()

curl "https://adsapi.snapchat.com/v1/targeting/device/marketing_name"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5964167200ff0255988362e6420001737e616473617069736300016275696c642d32353936663565632d312d38312d3100010126",
    "paging": {},
    "targeting_dimensions": [
        {
            "sub_request_status": "SUCCESS",
            "marketing_name": {
                "id": "Acer/",
                "name": "Acer"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "marketing_name": {
                "id": "Apple/",
                "name": "Apple"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "marketing_name": {
                "id": "Apple/iPad (3rd Gen)/",
                "name": "Apple > iPad (3rd Gen)"
            }
        },
        [[[snip]]]
        {
            "sub_request_status": "SUCCESS",
            "marketing_name": {
                "id": "Xiaomi/Redmi Note 4/",
                "name": "Xiaomi > Redmi Note 4"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "marketing_name": {
                "id": "ZTE/",
                "name": "ZTE"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "marketing_name": {
                "id": "ZTE/Zmax Pro/",
                "name": "ZTE > Zmax Pro"
            }
        }
    ]
}

This endpoint retrieves the list of device make targeting options. Please note that specifying a parent level make option like “Apple/” in the targeting spec will include all devices of the kind “Apple/*” like “Apple/iPad (3rd Gen)/”, “Apple/iPhone 4/”, “Apple/iPhone 7 Plus/” etc.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/device/marketing_name

Geolocation

Geolocation targeting is based on the device’s location at the time the ad is served.

Geolocation - Country

Get Country Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.geo.countries()

curl "https://adsapi.snapchat.com/v1/targeting/geo/country"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "status": "success",
  "request_id": "57abb71f00067458450ddec8",
  "targeting_dimensions": [
    {
      "sub_request_status": "success",
      "country": {
        "lat": 0,
        "lon": 0,
        "continent": {
          "id": "3",
          "name": "au"
        },
        "country": {
          "id": "166",
          "name": "cocos (keeling) islands",
          "code": "cck",
          "code2": "cc"
        }
      }
    },
    {
      "sub_request_status": "success",
      "country": {
        "lat": 0,
        "lon": 0,
        "continent": {
          "id": "5",
          "name": "eu"
        },
        "country": {
          "id": "246",
          "name": "finland",
          "code": "fin",
          "code2": "fi"
        }
      }
    },


    [[[ snip ]]]


    {
      "sub_request_status": "success",
      "country": {
        "lat": 0,
        "lon": 0,
        "continent": {
          "id": "3",
          "name": "au"
        },
        "country": {
          "id": "334",
          "name": "heard and mc donald islands",
          "code": "hmd",
          "code2": "hm"
        }
      }
    },
    {
      "sub_request_status": "success",
      "country": {
        "lat": 0,
        "lon": 0,
        "continent": {
          "id": "1",
          "name": "af"
        },
        "country": {
          "id": "454",
          "name": "malawi",
          "code": "mwi",
          "code2": "mw"
        }
      }
    }
  ]
}

This endpoint retrieves the list of country targeting options.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/geo/country

Geolocation - Region / State

Get Region / State Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.geo.regions(country_code='us')

curl "https://adsapi.snapchat.com/v1/targeting/geo/us/region"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "status": "success",
  "request_id": "57abb9ac000caa30eb4ac303",
  "targeting_dimensions": [
    {
      "sub_request_status": "success",
      "region": {
        "lat": 0,
        "lon": 0,
        "continent": {
          "id": "6",
          "name": "na"
        },
        "country": {
          "id": "840",
          "name": "united states",
          "code": "usa",
          "code2": "us"
        },
        "region": {
          "id": "16",
          "code": "ia",
          "name": "iowa"
        }
      }
    },
    {
      "sub_request_status": "success",
      "region": {
        "lat": 0,
        "lon": 0,
        "continent": {
          "id": "6",
          "name": "na"
        },
        "country": {
          "id": "840",
          "name": "united states",
          "code": "usa",
          "code2": "us"
        },
        "region": {
          "id": "21",
          "code": "md",
          "name": "maryland"
        }
      }
    },


    [[[ snip ]]]


    {
      "sub_request_status": "success",
      "region": {
        "lat": 0,
        "lon": 0,
        "continent": {
          "id": "6",
          "name": "na"
        },
        "country": {
          "id": "840",
          "name": "united states",
          "code": "usa",
          "code2": "us"
        },
        "region": {
          "id": "31",
          "code": "nj",
          "name": "new jersey"
        }
      }
    },
    {
      "sub_request_status": "success",
      "region": {
        "lat": 0,
        "lon": 0,
        "continent": {
          "id": "6",
          "name": "na"
        },
        "country": {
          "id": "840",
          "name": "united states",
          "code": "usa",
          "code2": "us"
        },
        "region": {
          "id": "22",
          "code": "ma",
          "name": "massachusetts"
        }
      }
    },
    {
      "sub_request_status": "success",
      "region": {
        "lat": 0,
        "lon": 0,
        "continent": {
          "id": "6",
          "name": "na"
        },
        "country": {
          "id": "840",
          "name": "united states",
          "code": "usa",
          "code2": "us"
        },
        "region": {
          "id": "48",
          "code": "wa",
          "name": "washington"
        }
      }
    }
  ]
}

This endpoint retrieves the list of region/state targeting options.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/geo/{country_code}/region

Parameters

Parameter	Default	Description
country_code		ISO ALPHA-2 Country Code (lowercase)

Geolocation - Metro / DMA

Get Metro / DMA Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.geo.metros(country_code='us')

curl "https://adsapi.snapchat.com/v1/targeting/geo/us/metro"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5848879d00ff0ade2a482631b50001737e616473617069736300016275696c642d39323764616530622d312d32372d330001010c",
  "targeting_dimensions": [
    {
      "sub_request_status": "SUCCESS",
      "metro": {
        "lat": 0,
        "lon": 0,
        "continent": {
          "id": "6",
          "name": "na"
        },
        "country": {
          "id": "840",
          "name": "united states",
          "code": "us",
          "code2": "us"
        },
        "metro": {
          "id": "557",
          "name": "knoxville",
          "regions": "ky/tn"
        }
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "metro": {
        "lat": 0,
        "lon": 0,
        "continent": {
          "id": "6",
          "name": "na"
        },
        "country": {
          "id": "840",
          "name": "united states",
          "code": "us",
          "code2": "us"
        },
        "metro": {
          "id": "641",
          "name": "san antonio",
          "regions": "tx"
        }
      }
    },


    [[[ snip ]]]


    {
      "sub_request_status": "SUCCESS",
      "metro": {
        "lat": 0,
        "lon": 0,
        "continent": {
          "id": "6",
          "name": "na"
        },
        "country": {
          "id": "840",
          "name": "united states",
          "code": "us",
          "code2": "us"
        },
        "metro": {
          "id": "717",
          "name": "quincy-hannibal-keokuk",
          "regions": "ia/il/mo"
        }
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "metro": {
        "lat": 0,
        "lon": 0,
        "continent": {
          "id": "6",
          "name": "na"
        },
        "country": {
          "id": "840",
          "name": "united states",
          "code": "us",
          "code2": "us"
        },
        "metro": {
          "id": "546",
          "name": "columbia, sc",
          "regions": "sc"
        }
      }
    }
  ]
}

This endpoint retrieves the list of metro/dma targeting options.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/geo/{country_code}/metro

Parameters

Parameter	Default	Description
country_code		ISO ALPHA-2 Country Code (lowercase)

Zipcode

Get Zipcode Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.geo.zipcode()

curl "https://adsapi.snapchat.com/v1/targeting/geo/us/postal_code?cursor=0&limit=500"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "594db13f00ff05364288a100ff4b0001737e616473617069736300016275696c642d36356130306562372d312d37382d3100010121",
    "paging": {
        "next_link": "https://adsapisc.appspot.com/v1/targeting/geo/us/postal_code?limit=500&cursor=1"
    },
    "targeting_dimensions": [
        {
            "sub_request_status": "SUCCESS",
            "postal_code": {
                "postalCode": "13024",
                "lat": 0,
                "lon": 0,
                "continent": {
                    "id": "6",
                    "name": "na"
                },
                "country": {
                    "id": "840",
                    "name": "united states",
                    "code": "us",
                    "code2": "us"
                },
                "region": {
                    "id": "33",
                    "code": "ny",
                    "name": "new york"
                },
                "city": {
                    "id": "4587",
                    "name": "auburn"
                }
            }
        },
        [[snip]
        {
            "sub_request_status": "SUCCESS",
            "postal_code": {
                "postalCode": "94927",
                "lat": 0,
                "lon": 0,
                "continent": {
                    "id": "6",
                    "name": "na"
                },
                "country": {
                    "id": "840",
                    "name": "united states",
                    "code": "us",
                    "code2": "us"
                },
                "region": {
                    "id": "5",
                    "code": "ca",
                    "name": "california"
                },
                "city": {
                    "id": "2370",
                    "name": "rohnert park"
                }
            }
        }
    ]
}

This endpoint retrieves the list of zipcode targeting options.

This endpoint supports pagination. Specify the number of entries to be returned using the limit paramter. The paging object in the response will include next_link which indicates the next url to be fetched.

Please note that United Arab Emirates do not use zip codes.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/geo/{country_code}/postal_code?cursor=0&limit=500

Parameters

Parameter	Default	Description
country_code		ISO ALPHA-2 Country Code (lowercase)
cursor		cursor/page number
limit		Page size. the number of entries to be retrieved in one page. Can be between 10-10000

Interests

Interest targeting allows an advertiser to find a user based on Snap Lifestyle Categories or Oracle Datalogix (DLX) Interests.

Interests - Snap Lifestyle Categories

Interest targeting is based on Snap Lifestyle Categories.

Get Snap Lifestyle Categories Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.interests.scls()

curl "https://adsapi.snapchat.com/v1/targeting/interests/scls"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57acea61000484407b52009b",
  "targeting_dimensions": [
    {
      "sub_request_status": "success",
      "scls": {
        "name": "Fashion & Style Gurus",
        "id": "SLC_7"
      }
    },
    {
      "sub_request_status": "success",
      "scls": {
        "name": "Film & TV Fans",
        "id": "SLC_8"
      }
    },
    {
      "sub_request_status": "success",
      "scls": {
        "name": "Comedy Fans",
        "id": "SLC_36_8"
      }
    },
    {
      "sub_request_status": "success",
      "scls": {
        "name": "Serious Gamers",
        "id": "SLC_45_13"
      }
    },
    {
      "sub_request_status": "success",
      "scls": {
        "name": "Music Fans",
        "id": "SLC_19"
      }
    }
  ]
}

This endpoint retrieves the list of Snap Lifestyle Categories targeting options.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/interests/scls

Get Snap Lifestyle Categories By Country

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.interests.scls()

curl "https://adsapi.snapchat.com/v1/targeting/interests/us/scls"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5bce471800ff020b339480a1fc0001737e616473617069736300016275696c642d64636363373137632d312d3231342d3000010141",
    "paging": {},
    "targeting_dimensions": [
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_1",
                "name": "Adventure Seekers",
                "path": "/Adventure Seekers",
                "parentId": "SLC_0",
                "source": "SNAPCHAT"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_10",
                "name": "Do-It-Yourselfers",
                "path": "/Do-It-Yourselfers",
                "parentId": "SLC_0",
                "source": "SNAPCHAT"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_100",
                "name": "Talent & Competition Show Fans",
                "path": "/Film & TV Fans/Talent & Competition Show Fans",
                "parentId": "SLC_12",
                "source": "SNAPCHAT"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_101",
                "name": "Talk Show Fans",
                "path": "/Film & TV Fans/Talk Show Fans",
                "parentId": "SLC_12",
                "source": "SNAPCHAT"
            }
        },
        <<snip>>
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_102",
                "name": "Teen & Young Adult Genre Fans",
                "path": "/Film & TV Fans/Teen & Young Adult Genre Fans",
                "parentId": "SLC_12",
                "source": "SNAPCHAT"
            }
        }
    ]
}

This endpoint retrieves the list of Snap Lifestyle Categories targeting options by the specified country code.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/interests/<targeting-country-code>/scls

Interests - Oracle Datalogix (DLX)

Interest targeting can also be based on Oracle Datalogix (DLX) Interests.

Get Oracle Datalogix DLXS Interest Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.interests.dlxs()

curl "https://adsapi.snapchat.com/v1/targeting/interests/dlxs"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57acea61000484407b52009b",
  "targeting_dimensions": [
    {
      "sub_request_status": "success",
      "dlxs": {
        "name": "Apparel Shoppers",
        "id": "DLXS_1"
      }
    },
    {
      "sub_request_status": "success",
      "dlxs": {
        "name": "Small & Mid-size SUV Shoppers",
        "id": "DLXS_100"
      }
    }
  ]
}

This endpoint retrieves the list of Oracle Datalogix DLXS Interests targeting options.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/interests/dlxs

Get Oracle Datalogix DLXC Interest Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.interests.dlxc()

curl "https://adsapi.snapchat.com/v1/targeting/interests/dlxc"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57acea61000484407b52009b",
  "targeting_dimensions": [
    {
      "sub_request_status": "success",
      "dlxc": {
        "name": "Home Movie Viewers (Action)",
        "id": "DLXC_101"
      }
    },
    {
      "sub_request_status": "success",
      "dlxc": {
        "name": "TV Viewers (Variety Shows)",
        "id": "DLXC_133"
      }
    }
  ]
}

This endpoint retrieves the list of Oracle Datalogix DLXC targeting options.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/interests/dlxc

Get Oracle Datalogix DLXP Interest Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.interests.dlxp()

curl "https://adsapi.snapchat.com/v1/targeting/interests/dlxp"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "590850dd00ff05d022b1d7a5c50001737e616473617069736300016275696c642d62663930383438312d312d36322d320001013e",
  "targeting_dimensions": [
    {
      "sub_request_status": "SUCCESS",
      "dlxp": {
        "id": "DLXP_107",
        "name": "Ford Dealers"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "dlxp": {
        "id": "DLXP_108",
        "name": "Foreign Vehicle Dealers"
      }
    },
    {
      "sub_request_status": "SUCCESS",
      "dlxp": {
        "id": "DLXP_109",
        "name": "Honda Dealers"
      }
    }
  ]
}

This endpoint retrieves the list of Oracle Datalogix DLXP targeting options.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/interests/dlxp

Get Nielsen Interest Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.interests.nln()

curl "https://adsapi.snapchat.com/v1/targeting/interests/nln"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5b3426d900ff072f79188f4fe20001737e616473617069736300016275696c642d38666335393665372d312d3137392d",
    "paging": {
        "next_link": "https://adsapisc.appspot.com/v1/targeting/interests/nln?cursor=1&limit=999"
    },
    "targeting_dimensions": [
        {
            "sub_request_status": "SUCCESS",
            "nln": {
                "id": "NLN_1000",
                "name": "Apparel Buyers",
                "path": "/Apparel Buyers",
                "source": "Nielsen"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "nln": {
                "id": "NLN_10000",
                "name": "Pet Product Buyers",
                "path": "/Pet Product Buyers",
                "source": "Nielsen"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "nln": {
                "id": "NLN_10001",
                "name": "Pet Store Buyers",
                "parent_id": "NLN_10000",
                "path": "/Pet Product Buyers/Pet Store Buyers",
                "source": "NBI"
            }
        }
      ]
  }

This endpoint retrieves the list of Nielsen interest targeting options. The response is paginated and contains a link to the next page of the response. To fetch all categories please keep issuing a GET request to next_link contained in the paging parameter in the response, until paging returns nothing.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/interests/nln

Interests - Placed Visitation Segments

Interest targeting based on Placed Visitation Segments.

Get Placed Visitation Segments

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.interests.plcs()

curl "https://adsapi.snapchat.com/v1/targeting/interests/plc"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5b9aa65c00ff02fdc17b1cdd170001737e616473617069736300016275696c642d33346634346232622d312d3230302d3200010158",
    "paging": {},
    "targeting_dimensions": [
        {
            "sub_request_status": "SUCCESS",
            "plc": {
                "id": "PLC_101",
                "name": "Auto Dealer Visitors",
                "path": "/Auto Dealer Visitors",
                "source": "PLACED"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "plc": {
                "id": "PLC_102",
                "name": "Asian Vehicle Dealers",
                "path": "/Auto Dealer Visitors/Asian Vehicle Dealers",
                "parent_id": "PLC_101",
                "source": "PLACED"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "plc": {
                "id": "PLC_103",
                "name": "Big3 Vehicle Dealers",
                "path": "/Auto Dealer Visitors/Big3 Vehicle Dealers",
                "parent_id": "PLC_101",
                "source": "PLACED"
            }
        },
        <snip>
        {
            "sub_request_status": "SUCCESS",
            "plc": {
                "id": "PLC_618",
                "name": "Marriott Chain Hotels",
                "path": "/Travel Venue Visitors/Hotels/Marriott Chain Hotels",
                "parent_id": "PLC_605",
                "source": "PLACED"
            }
        }
    ]
}

This endpoint retrieves the list of Placed Visitation Segments for targeting.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/interests/plc

Location

Location targeting allows an advertiser to target users based on their location.

Location - Categories

Get Location Categories Targeting Options

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.targeting.location.catgeories()

curl "https://adsapi.snapchat.com/v1/targeting/location/categories_loi"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

Response:
{
    "request_status": "SUCCESS",
    "request_id": "5a01027200ff0e853c41a9d4810001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d33356139343261632d6c6f632d6c6f6900010106",
    "paging": {},
    "targeting_dimensions": [
        {
            "sub_request_status": "SUCCESS",
            "categories_loi": {
                "id": "LOI_1000",
                "name": "Arts & Entertainment",
                "path":"/Arts & Entertainment"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "categories_loi": {
                "id": "LOI_1001",
                "name": "Comedy Clubs",
                "parent_id": "LOI_1000",
                "path":"/Arts & Entertainment/Comedy Clubs"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "categories_loi": {
                "id": "LOI_1002",
                "name": "Galleries & Museums",
                "parent_id": "LOI_1000",
                "path":"/Arts & Entertainment/Galleries & Museums"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "categories_loi": {
                "id": "LOI_1003",
                "name": "Movie Theaters",
                "parent_id": "LOI_1000",
                "path":"/Arts & Entertainment/Movie Theaters"
            }
        },
        ... // etc
    ]
}

This endpoint retrieves the list of location categories.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/location/categories_loi

Attributes

Attribute	Description	Required	Possible Values
proximity	Proximity to selected location categories	R
proximity_unit	Unit to be used for radius	R	METERS (default), KILOMETERS, FEET, MILES

Location - Point Radius

"targeting": {
          "regulated_content": "false",
        "demographics": [
          {
            "age_groups": [
              "21-24"
            ]
          }
        ],
        "geos": [
          {
            "country_code": "us"
          }
        ],
        "locations": [
          {
            "circles": [
              {
                "latitude": 47.612447,
                "longitude":  -122.336751,
                "radius": 500
              },
              {
                "latitude": 47.617102, 
                "longitude": -122.203961,
                "radius": 50,
                "unit": "KILOMETERS"
              }
            ],
            "operation": "INCLUDE"
          }
        ]
      }

Using point radius targeting advertisers can pass in lists of latitude, longitude, and radius “circles” for location targeting. You can add up to 500 circles in the targeting spec.

Attributes

Attribute	Description	Required	Possible Values
latitude	Latitude in decimal degrees	R
longitude	Longitude in decimal degrees	R
radius	Radius in meters (minimum 96 meters and maximum 100000 meters)	R
unit	Unit to be used for radius	O	METERS (default), KILOMETERS, FEET, MILES

Snap Audience Match

Snap Audience Match (SAM) allows an advertiser to use first-party data to create an Audience Segment. The segment can be used to target or exclude a specific group of users.

Attributes

Attribute	Description	Required	Possible Values
ad_account_id	Ad Account ID	R
description	Audience Segment Description	O
name	Audience Segment name	R
retention_in_days	# of days to retain audience members	R	(Default retention is lifetime represented as 9999)
source_type	Data source type	R	FIRST_PARTY, ENGAGEMENT, PIXEL, MOBILE, FOOT_TRAFFIC_INSIGHTS
approximate_number_users	Approximate # of users in the segment	Read Only
status	Status of the segment	Read Only	ACTIVE
upload_status	Upload status of the segment	Read Only	NO_UPLOAD, PROCESSING, COMPLETE
targetable_status	Status of whether this segment can be targeted	Read Only	NOT_READY, TOO_FEW_USERS, READY

Create an Audience Segment

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{"segments": [{"name": "all the sams in the world", "description": "all the sams in the world", "source_type": "FIRST_PARTY", "retention_in_days": 180, "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74"}]}' \
   "https://adsapi.snapchat.com/v1/adaccounts/{ad_acount_id}/segments"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57ae54d800ff0a4a5232b1a7210001737e616473617069736300016275696c642d35396264653638322d312d31312d37000100",
  "segments": [
    {
      "sub_request_status": "success",
      "segment": {
        "updated_at": "2016-08-12T22:59:42.452Z",
        "created_at": "2016-08-12T22:59:42.405Z",
        "name": "all the sams in the world",
        "id": "5677923948298240",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "description": "all the sams in the world",
        "status": "PENDING",
        "source_type": "FIRST_PARTY",
        "retention_in_days": 180,
        "approximate_number_users": 0
      }
    }
  ]
}

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

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Segment Status

Upload Status	Description
NO_UPLOAD	Segment has been created but no uploads have been received yet
PROCESSING	Not all uploads to this segment have been processed so audience size might change
COMPLETE	All received uploads have been processed and matched. Audience size reflects segment size

Targetable Status	Description
NOT_READY	This segment won’t work when used in targeting
TOO_FEW_USERS	This segment doesn’t have enough users to target
READY	Segment is ready to target

Get All Audience Segments

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()

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

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57ae554a00ff0487459c8ac85c0001737e616473617069736300016275696c642d34363138393265642d312d31312d3200010103",
  "segments": [
    {
      "sub_request_status": "success",
      "segment": {
        "updated_at": "2016-08-12T21:11:01.325Z",
        "created_at": "2016-08-12T21:11:01.196Z",
        "name": "super duper sam 2",
        "id": "5689640350646272",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "description": "all the sams in the world",
        "status": "PENDING",
        "source_type": "FIRST_PARTY",
        "retention_in_days": 180,
        "approximate_number_users": 0
      }
    },
    {
      "sub_request_status": "success",
      "segment": {
        "updated_at": "2016-08-12T20:58:16.098Z",
        "created_at": "2016-08-12T20:58:16.036Z",
        "name": "super duper sam",
        "id": "5715031928864768",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "description": "all the sams in the world",
        "status": "PENDING",
        "source_type": "FIRST_PARTY",
        "retention_in_days": 180,
        "approximate_number_users": 0
      }
    }
  ]
}

This endpoint retrieves all Snap Audience Match segments within a specified ad account.

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Get a specific Audience Segment

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()

curl "https://adsapi.snapchat.com/v1/segments/{segment_id}"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5b3116c800ff0cfbb4758de4670001737e616473617069736300016275696c642d32636336303266382d312d3137382d300001015d",
    "segments": [
        {
            "sub_request_status": "SUCCESS",
            "segment": {
                "id": "5701023945457664",
                "updated_at": "2018-06-25T02:13:52.956Z",
                "created_at": "2018-03-09T00:57:57.462Z",
                "name": "Lookalike - Balance - hashed_emails_old_groupB",
                "ad_account_id": "3f539865-c001-4f5e-bd31-5ae129a4550a",
                "status": "ACTIVE",
                "targetable_status": "READY",
                "upload_status": "COMPLETE",
                "source_type": "LOOKALIKE",
                "retention_in_days": 180,
                "approximate_number_users": 11487000,
                "creation_spec": {
                    "seed_segment_id": "5749764677173248",
                    "country": "US",
                    "type": "BALANCE"
                }
            }
        }
    ]
}

This endpoint retrieves the Snap Audience Segment with the corresponding segment id.

HTTP Request

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

Parameters

Parameter	Default	Description
segment_id		Segment ID

Update an Audience Segment

curl "https://adsapi.snapchat.com/v1/segments/{segment_id}"
  -H "Authorization: Bearer meowmeowmeow"

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"segments":[{"id":"5603670370513719","name":"Honey Bear Segment 2019","organization_id":"1fdeefec-f502-4ca8-9a84-6411e0a51052","description":"A list of Honey bear lovers across the globe","retention_in_days":"60"}]}'
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/segments

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5dc3096800ff0c266ebe6eeaac0001737e616473617069736300016275696c642d65653836646631392d312d3330322d300001013a",
    "segments": [
        {
            "sub_request_status": "SUCCESS",
            "segment": {
                "id": "5603670370513719",
                "updated_at": "2019-11-06T17:56:57.053Z",
                "created_at": "2019-03-28T14:47:17.956Z",
                "name": "Honey Bear Segment 2019",
                "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
                "organization_id": "1fdeefec-f502-4ca8-9a84-6411e0a51052",
                "description": "A list of Honey bear lovers across the globe",
                "status": "PAUSED",
                "targetable_status": "TOO_FEW_USERS",
                "upload_status": "COMPLETE",
                "source_type": "FIRST_PARTY",
                "retention_in_days": 60,
                "approximate_number_users": 500000,
                "visible_to": [
                    "AdAccountEntity_22225ba6-7559-4000-9663-bace8adff5f1"
                ]
            }
        }
    ]
}

This endpoint updates the Snap Audience Segment.

Attributes that can be updated

Attribute	Required
name	R
description	O
retention_in_days	R

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Adding Users

Users can be added to a segment at any time. The API supports matching via email, 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

1. Normalize email addresses by trimming leading and trailing whitespace and converting all characters to lowercase before hashing
2. Normalize mobile advertiser id by using all lowercase. Do not remove hyphens.
3. Normalize phone numbers by including country code, and exclude any non-numeric characters such as whitespace, parentheses, ‘+’, or ‘-’

Hashing Identifiers

Hash raw identifiers with lowercase hex SHA256 format.

Adding Users (Single-Key)

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()

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

The above command returns JSON structured like this:

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

This example uses a single key/identifier per user.

Removing Users

Users can also be removed from the segment at any time. The API supports matching via email, 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
country	ISO-2 Country Code	R
seed_segment_id	Seed Audience Segment ID	R
type	The type of Lookalike to be created	O	BALANCE (default), SIMILARITY, REACH

Create an Lookalike Segment

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.sam.get()

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Example Targeting Specs

Targeting Spec Examples for an Ad Squad

Example 1

United States, Male+Female, All Age Ranges

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

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

Example 2

United States, Male, Age Groups 21-34

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

Example 3

Canada, Female, 13-20, iOS

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

Example 4

UK, Male+Female, Age 25, WIFI Only

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

Example 5

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

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

Example 6

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

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

Example 7

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

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

Example 8

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

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

Example 9

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

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

Example 10

United States, AT&T

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

Example 11

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

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

Example 12

United States, metros New York or Los Angeles only

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

Example 13

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

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

Example 14

Zipcode Targeting

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

Example 15

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

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

Example 16

Location Categories: Targeting Sports Arenas, Fitness Centers

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

Example 17

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

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

Example 18

Multi-country targeting: Targeting the US and Canada

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

Example 19

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

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

Audience Insights

Get Audience Insights

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		The Ad Account ID to be used

Attributes

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

Query Parameters

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

Example

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.kittens.get()

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

The above command returns JSON structured like this:

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

Audience Size

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

By Ad Squad Spec

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

The above command returns JSON structured like this:

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

HTTP Request

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

URL Parameters

Parameter	Description
ad_account_id	Ad Account ID

By Ad Squad ID

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter	Description
ad_squad_id	Ad squad ID

By Targeting Spec

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the ad account

Bid Estimate

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

By Ad Squad

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the ad squad

By Targeting Spec

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

Parameter	Description
ID	The ID of the ad account

Attributes

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

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
	INAVLID_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
swipe_up_attribution_window	Attribution window for swipe ups	O	1_DAY, 7_DAY, 28_DAY (default)
view_attribution_window	Attribution window for views	O	1_HOUR, 3_HOUR, 6_HOUR, 1_DAY (default), 7_DAY, 28_DAY
position_stats	Position metric breakdown for Snap Ads within a Story Ad	O	true
omit_empty	Omits records with zero data for all metrics for a given date/entity. If there is data for any metric for a given date/entity, all metrics for that date/entity are returned	O	false (default), true
conversion_source_types	Conversion source breakout by platform	O	web, app, total
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

Response Parameters

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

Pagination

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

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

Core Metrics

The following metrics are available for all Snap Ads.

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

Additional Metrics

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

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

Conversion Event Stats

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

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

Conversion breakout

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

Parameter	Metric	Description
total	conversion_purchases	All purchase events
web	conversion_purchases_web	Purchases from a web browser
app	conversion_purchases_app	Purchases from an app

Conversion breakout example

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

The above command returns JSON structured like this:

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

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

Omitting empty records example

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

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

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

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

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

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

The parameter omit_empty will omit records with zero data for all metrics for a given date/entity. If there is data for any metric for a given date/entity, all metrics for that date/entity are returned.

The omit_empty parameter allows developers to speed up calculations as empty entries can be removed before the calculation is made, it also allows developers to structure an app to avoid displaying empty entries in the UI.

Metrics and supported granularities

Metric	Real time	HOUR	DAY	TOTAL	LIFETIME
android_installs	YES	YES. time must be of hour boundary, start_time and end_time within 7 days	YES. time must be of day boundary, start_time and end_time within 31 days	YES. time must be of day boundary, start_time and end_time must be both specified, or neither. In the latter case, it combines lifetime and realtime stats.	YES. no start_time, end_time can be specified.
attachment_avg_view_time_millis
attachment_impressions
attachment_quartile_1
attachment_quartile_2
attachment_quartile_3
attachment_total_view_time_millis
attachment_view_completion
avg_screen_time_millis
avg_view_time_millis
impressions
ios_installs
quartile_1
quartile_2
quartile_3
screen_time_millis
spend
swipe_up_percent
swipes
total_installs
video_views
video_views_time_based
video_views_15s
view_completion
view_time_millis
conversion_purchases
conversion_purchases_value
conversion_save
conversion_start_checkout
conversion_add_cart
conversion_view_content
conversion_add_billing
conversion_signups
conversion_searches
conversion_level_completes
conversion_app_opens
conversion_page_views
conversion_subscribe
conversion_ad_click
conversion_ad_view
conversion_complete_tutorial
conversion_invite
conversion_login
conversion_share
conversion_reserve
conversion_achievement_unlocked
conversion_add_to_wishlist
conversion_spend_credits
conversion_rate
conversion_start_trial
conversion_list_view
custom_event_1
custom_event_2
custom_event_3
custom_event_4
custom_event_5
attachment_frequency	YES	YES	YES	Not supported. Use LIFETIME
attachment_uniques
frequency
uniques

Example for All Metrics

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.campaigns.get('123').stats()

curl -H "Authorization: Bearer meowmeow" \
    "https://adsapi.snapchat.com/v1/campaigns/2bbaa6e3-4ddb-4358-9efe-48334952f4aa/stats?breakdown=adsquad&fields=android_installs,avg_screen_time_millis,attachment_frequency,attachment_quartile_1,attachment_quartile_2,attachment_quartile_3,attachment_total_view_time_millis,attachment_uniques,attachment_view_completion,frequency,impressions,ios_installs,quartile_1,quartile_2,quartile_3,spend,swipe_up_percent,swipes,total_installs,uniques,view_completion,screen_time_millis&granularity=DAY&start_time=2016-10-24T07:00:00.000-00:00&end_time=2016-10-26T07:00:00.000-00:00"

{
  "request_status": "SUCCESS",
  "request_id": "5813ccf400ff07b016a837c09f0001737e616473617069736300016275696c642d65373832323966352d73746174732d322d7465737400010133",
  "timeseries_stats": [
    {
      "sub_request_status": "SUCCESS",
      "timeseries_stat": {
        "id": "2bbaa6e3-4ddb-4358-9efe-48334952f4aa",
        "type": "CAMPAIGN",
        "start_time": "2016-10-24T07:00:00.000Z",
        "end_time": "2016-10-26T07:00:00.000Z",
        "breakdown_stats": {
          "adsquad": [
            {
              "id": "134aeb99-6552-4f1d-b7a6-82b9813fd079",
              "type": "AD_SQUAD",
              "granularity": "DAY",
              "start_time": "2016-10-24T07:00:00.000Z",
              "end_time": "2016-10-26T07:00:00.000Z",
              "timeseries": [
                {
                  "start_time": "2016-10-24T07:00:00.000Z",
                  "end_time": "2016-10-25T07:00:00.000Z",
                  "stats": {
                    "impressions": 18294,
                    "swipes": 0,
                    "quartile_1": 7489,
                    "quartile_2": 2595,
                    "quartile_3": 1964,
                    "view_completion": 1635,
                    "attachment_quartile_1": 0,
                    "attachment_quartile_2": 0,
                    "attachment_quartile_3": 0,
                    "attachment_view_completion": 0,
                    "attachment_total_view_time_millis": 0,
                    "frequency": 1.0014,
                    "avg_screen_time_millis": 1832,
                    "swipe_up_percent": 0,
                    "attachment_frequency": 0,
                    "attachment_avg_view_time_millis": 0,
                    "uniques": 18268,
                    "attachment_uniques": 0,
                    "ios_installs": 0,
                    "android_installs": 0,
                    "total_installs": 0,
                    "spend": 144213617,
                    "screen_time_millis": 33876700
                  }
                },
                {
                  "start_time": "2016-10-25T07:00:00.000Z",
                  "end_time": "2016-10-26T07:00:00.000Z",
                  "stats": {
                    "impressions": 15377,
                    "swipes": 0,
                    "quartile_1": 6345,
                    "quartile_2": 2185,
                    "quartile_3": 1596,
                    "view_completion": 1324,
                    "attachment_quartile_1": 0,
                    "attachment_quartile_2": 0,
                    "attachment_quartile_3": 0,
                    "attachment_view_completion": 0,
                    "attachment_total_view_time_millis": 0,
                    "frequency": 1.0011,
                    "avg_screen_time_millis": 1828,
                    "swipe_up_percent": 0,
                    "attachment_frequency": 0,
                    "attachment_avg_view_time_millis": 0,
                    "uniques": 15360,
                    "attachment_uniques": 0,
                    "ios_installs": 0,
                    "android_installs": 0,
                    "total_installs": 0,
                    "spend": 120978178,
                    "screen_time_millis": 28547600
                  }
                }
              ]
            }
}

Get Ad Account Stats

curl "https://adsapi.snapchat.com/v1/adaccounts/22335ba6-7558-4100-9663-baca7adff5f2/stats?granularity=TOTAL&fields=spend" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b24d9c00ff0d85622341e7c60001737e616473617069736300016275676c642b34326313636139312d332d31312d390001010d",
  "total_stats": [
    {
      "sub_request_status": "success",
      "total_stat": {
        "id": "22335ba6-7558-4100-9663-baca7adff5f2",
        "type": "AD_ACCOUNT",
        "granularity": "TOTAL",
        "stats": {
          "spend": 89196290
        },
        "finalized_data_end_time": "2019-08-29T03:00:00.000-07:00"
      }
    }
  ]
}

This endpoint retrieves the spend metric for the specified Ad Account, the spend metric is the only metric available for the ad account entity.

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Get Campaign Stats

import snapchat_ads_api

api = snapchat_ads_api.authorize('meowmeowmeow')
api.