NAV Navbar

Ads API

cURL

Introduction

Welcome to the Snapchat Marketing API!

Code references are presented in the main column and examples in CURL can be viewed in the dark area to the right.

Announcements

Subscribing to Marketing API Announcements

To keep up to date on the latest changes to the Marketing API, you can sign up to receive Marketing API Announcements. Subscribing to these announcements allows you to receive updates on new releases, changes and deprecations for the Marketing API and the Conversions API.

February 2024

Effective February 26th, 2024, we are requiring Public Profile usage in ads via the Marketing API. This means your Creatives need to include the profile_properties attribute where a profile_id is to be used (see API docs here). While including the profile_properties is required on creation, you will still be able to override the Profile name by using the brand_name attribute.

July 2023

European Union Digital Services Act

Effective August 25, 2023 in compliance with the European Digital Services Act (DSA), some targeting and optimization settings will no longer be available when targeting Snapchatters aged 13-17 in the 27 countries of the European Union (EU). We are also extending this to the United Kingdom (UK).

Some targeting options will no longer be available for Ad Squads reaching Snapchatters aged 13-17 in the EU and the UK

No longer available targeting Available targeting
Gender Placement
Interest targeting Age
Customer lists Language
Dynamic Product Ads Retargeting Location
Advanced demographics (already unavailable in the EU and the UK Device
Install state targeting

Most optimization goals will no longer be available for Ad Squads reaching Snapchatters aged 13-17 in the EU and the UK

No longer available Optimisation Goals Available Optimisation Goals
SWIPES IMPRESSIONS
APP_INSTALLS Reserved Campaigns (Takeovers, Reach & Frequency, Snap Select)
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, APP_REENGAGE_OPEN, APP_REENGAGE_PURCHASE
LEAD_FORM_SUBMISSIONS

To learn how these changes may impact current campaigns visit our Business Help Centre article on the EU DSA

May 2023

Pagination

To reduce latencies and improve reliability we are now introducing a default pagination size to all of our endpoints that support pagination. Currently we support pagination for Marketing API endpoints that can request large amounts of data, but we do not enforce any default limit.

Impact

This change will only apply to GET requests that are retrieving data. Non-paginated requests will continue to work, however, they will only return a maximum of 1000 entities per request by default.

For example, if you are currently calling GET /v1/adsquads/{ad_squad_id}/ads and receiving 2000 ad entities in the response. You will now receive 1000 ad entities in the response along with a next_link that can be used to fetch the next page.

Migration

Follow the Pagination section of API Patterns to implement pagination in your requests.

December 2022

Deprecation announcements

Targeting auto-expansion changes

In late January we will make two changes to Targeting auto expansion:

May 2022

SKAdnetwork updates - Deprecation of Opt-out & Introduction of ecid_status

On the 7 September 2022 we are limiting enrollment to the point of Ad Squad creation, we are also deprecating the opt-out action for SKAd enrolled Ad Squads.

Whilst you won’t be able to opt-out an Ad Squad out of SKAd tracking, you will be able to free up the Apple Campaign ID by pausing the Ad Squad and detaching the Campaign ID using the new attribute ecid_status

The full changes along with a description of how to set the ecid_status are described in the SKAdnetwork tracking section of our docs.

April 2022

Rename of “Snap Audience Match” (or “SAM”) to “Customer List”

We found that the term “Snap Audience Match” (or its acronym, “SAM”) was not intuitive for most advertisers. To help advertisers better understand what the feature does at a glance, we renamed this to “Customer List”.

August/October 2021

Ad Squad endpoint update

We are introducing an important behavior change to Ad Squad endpoint and the targeting entity in it. This is behavior change only affects targeting specs that have 500 or more GEO targeting criteria (country, region_id, postal_code). If you do not use more than 500 GEO targeting criteria in a single ad squad, you may ignore this change.

The complete changes are listed in the Targeting section for greater than 500 targeting rows

Timeline The changes listed below are already available for testing under a query parameter - targeting_spec_response_scope=AD_SQUAD_ONLY.

The changes will become default without the query parameter starting the 6th of January. On this date the old behavior will be deprecated.

Changes Any Ad Squad that contains more than 500 targeting criteria will have its targeting specifications broken out into a separate sub resource called targeting_specs and will be replaced by a property called separated_types. Any further updates or reads to the targeting spec will need to be performed on the new targeting_spec sub resource and not in the Ad Squad resource.

Pagination

To reduce latencies and improve reliability we are now introducing a default pagination size to all of our endpoints that support pagination. Currently we support pagination for Marketing API endpoints that can request large amounts of data, but we do not enforce any default limit.

May 2021

Deprecation of Story Ad Position Reach Metrics

On the 23 August 2021 We are deprecating the Story Ad specific metrics position_uniques and position_frequency, the deprecation date will be 90 days after the announcement date.

Deprecation of position_uniques and position_frequency

Announcement date: 25 May 2021
Deprecation date: 23 August 2021

The parameters position_uniques and position_frequency as described in the following section will be deprecated.

April 2021

Measurement And Reporting

As part of the changes made by Apple for their ATT (Apple Transparent Tracking) rollout, we will be making changes to our attribution. These changes will be reflected in our reporting API. There will be no changes to the existing API interface and so this is not a strict breaking change. However, API developers will need to update their implementation to account for the changes listed in the measurement section of the docs as there will be a regression in the API functionality.

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 identifiers using the advertiser’s first-party data.

An Organization (Org A) can grant another Organization (Org B) permission to access one or more of their Ad Accounts. A common case is a Brand granting a Snapchat MPP permission to advertise on their behalf using the Brand’s line of credit.

Quick Start

Here’s a high-level look at what it takes to launch a Snap Ad.

Let’s Run a Snap Ad!

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

API Patterns

The API has a consistent pattern for requests.

Get Many Entities

Pattern:

GET /v1/{PLURAL_PARENT_ENTITY_NAME}/{PARENT_ENTITY_ID}/{PLURAL_ENTITY_NAME}

Example:

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

Get a Single Entity

Pattern:

GET /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}

Example:

GET /v1/adaccounts/ff869d1f-0923-4d28-8577-4c36291f0fca

Pagination

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

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5b3f92d000ff0943024587937a0001737e616473617069736300016275696c642d33346664346130642d312d3138322d320001010d",
    "paging": {
        "next_link": "https://adsapisc.appspot.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/ads?cursor=CnEKFgoJY3JlYXRlZEF0EgkIoLnp8JLP0QISU2oKc35hZHNhcGlzY3ItCxIDQWRzIiQzMmFkZmYzMC1iNDk0LTQ4NWQtODMwYi04MjZlNDAzZTVkNjgMogEVYWQtbWFuYWdlci1wcm9kdWN0aW9uGAAgAQ&limit=50"
    },
    "ads": [
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "8ade8ef7-0cde-4eaa-bde6-990133575229",
                "updated_at": "2018-04-04T00:59:02.774Z",
                "created_at": "2018-04-04T00:56:35.051Z",
                "created_by_app_id": "87947032-5fbd-46a7-ba60-073ca8efefbb",
                "created_by_user": "1dcd753d-aca4-4f2d-8818-1edd38053a36",
                "last_updated_by_app_id": "87947032-5fbd-46a7-ba60-073ca8efefbb",
                "last_updated_by_user": "1dcd753d-aca4-4f2d-8818-1edd38053a36",
                "name": "Test",
                "ad_squad_id": "4c8e53c2-1747-4b50-a8a8-8200fe75aac5",
                "creative_id": "6ad4e432-f679-4a9b-af1d-c5781212dd75",
                "status": "ACTIVE",
                "type": "SNAP_AD",
                "review_status": "APPROVED"
            }...
            {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "32adff30-b494-485d-830b-826e403e5d68",
                "updated_at": "2017-07-31T21:34:50.311Z",
                "created_at": "2017-01-19T21:26:02.020Z",
                "created_by_app_id": "4bc57a9c-c2ab-4a12-ba71-adda3c0189f9",
                "last_updated_by_app_id": "4bc57a9c-c2ab-4a12-ba71-adda3c0189f9",
                "name": "happy time in 910 2",
                "ad_squad_id": "33a7ea1e-6413-4bb7-a4ac-35b0a258681e",
                "creative_id": "9e37d1ee-5f27-45ff-8317-ab35a57a5bf4",
                "status": "PAUSED",
                "type": "SNAP_AD",
                "review_status": "APPROVED"
            }
        }
    ]
}

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

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

Paginated calls are supported for these requests;

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

Pattern:

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

Example:

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

Entity Request Limits

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

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

Create One or More Entities

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

Pattern:

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

Example:

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

Update One or More Entities

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

Pattern:

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

Example:

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

Delete a Single Entity

Pattern:

DELETE /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}

Example:

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

Monetary Values

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

Examples

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

Authentication

To authorize, use this code:

# 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.

The Snapchat Marketing API uses access tokens to control access and authenticate requests, the access token will reflect the user permissions when used in API requests.

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

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 Developer Terms and the Snap Business Tools Terms.

Refer to this guide to setup your OAuth app in Business Manager.

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. The user will be presented with a login screen and confirmation prompt asking the user to authorize the OAuth App to act on behalf of the user.

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 Refer to the scopes reference table below
state Optional; Will be passed through in redirect; Used for verification of request authenticity

Scopes

Scope Description
snapchat-marketing-api This scope allows the app to read and write to the Snapchat marketing APIs
snapchat-offline-conversions-api This scope allows the app to read and write to the Snapchat Conversions APIs
snapchat-profile-api This scope allows the app to read the Snapchat Public Profile APIs

Note: To use multiple scopes please pass in a space separated list of scopes example scope=snapchat-marketing-api snapchat-offline-conversions-api

# Sample URL to redirect the OAuth users to - Single Scope
https://accounts.snapchat.com/login/oauth2/authorize
  ?client_id=4cxxxx8-1c33-xxxx-8798-xxxxxxxx
  &redirect_uri=https://test.animalfarm.com/callback
  &response_type=code
  &scope=snapchat-marketing-api

# Sample URL to redirect the OAuth users to - Multiple Scopes
https://accounts.snapchat.com/login/oauth2/authorize
  ?client_id=4cxxxx8-1c33-xxxx-8798-xxxxxxxx
  &redirect_uri=https://test.animalfarm.com/callback
  &response_type=code
  &scope=snapchat-marketing-api snapchat-offline-conversions-api

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 for the OAuth App to act on their behalf, 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 on behalf of the user that just authorised the app you must generate an Access Token that represents the user. 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



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

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

The above command returns JSON structured like this:

"me": {
        "id": "a22b5575-9052-437e-96c1-db781d62d203",
        "updated_at": "2018-09-28T23:33:01.706Z",
        "created_at": "2018-09-28T23:30:27.009Z",
        "email": "honey.badger@hooli.com",
        "organization_id": "40d6719b-da09-410b-9185-0cc9c0dfed1d",
        "display_name": "Honey Badger",
        "snapchat_username": "honey_badger",
        "member_status": "MEMBER",
        "bitmoji": {
            "avatar_id": "199953104_65-s7",
            "selfie_id": "10226021",
            "background_id": "398580551",
            "scene_id": ""
        }
    }

This endpoint retrieves information about the Snapchat user that is represented by the access token used, the information includes the snapchat_username.

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

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

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

Get a Specific Organization

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

POST 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 POST \
  -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.

Transactions

Transactions enable businesses to manage and track all financial exchanges within the Snap Business Manager.

Attributes

Attribute Description Required Possible Values
organization_id Organization ID R
account_id Ad Account ID R
payment_action_id Payment Action ID R
payment_action_type Payment Type R AUTHORIZATION, CHARGE, CORRECTION, REFUND, VERIFICATION, UNRECOGNIZED.
credential_id Credential ID R
credential_type Credential Type R COUPON, CREDIT_CARD, DIRECT_DEBIT, IN_APP_PURCHASE, LINE_OF_CREDIT, PAYPAL, PREPAY, SNAPCHAT.
payment_items Array of Payment Items. See table below R
status Transaction Status R COMPLETED, FAILED, PENDING, UNRECOGNIZED.
total_amount Transaction Amount R { “amount”: Number, “currency_type”: “USD”}

Payment Item

Attribute Description Required Possible Values
payment_item_id Payment Item ID R
name Payment Item Name R
start_date Start Date in ISO time string R
end_date End Date in ISO time string R
subtotal_amount.amount Item Amount R
subtotal_amount.currency_type Item Amount Currency R USD, CAD, GBP, EUR, AUD

Get all Transactions

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

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "1f4f4b52-91cc-4d9a-9bdf-f7aa93337df2",
    "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51053",
    "transactions": [
        {
            "sub_request_status": "SUCCESS",
            "transaction": {
                "id": "755d42ac-13b9-492f-95a5-628455fd8331",
                "account_id": "ea3e370f-43ae-5h53-8f10-1d2z47d9778a",
                "payment_items": [
                    {
                        "payment_item_id": "23c06de7-526b-472c-a041-c3da568e5b00",
                        "name": "Example Transactions",
                        "start_date": "2023-10-07T04:00:00.000Z",
                        "end_date": "2023-10-08T03:59:59.999Z",
                        "subtotal_amount": {
                            "amount": 585,
                            "currency_type": "USD"
                        },
                        "quantity": 1847
                    },
                    {
                        "payment_item_id": "23c06de7-526b-471c-a041-c3da568e5b00",
                        "name": "Example Transactions",
                        "start_date": "2023-10-07T04:00:00.000Z",
                        "end_date": "2023-10-08T03:59:59.999Z",
                        "subtotal_amount": {
                            "amount": 79000,
                            "currency_type": "USD"
                        },
                        "quantity": 469559
                    },
                ],
                "payment_action_id": "90dbd505-577b-4249-81e6-377be22ed8d3",
                "payment_action_type": "CHARGE",
                "credential_type": "LINE_OF_CREDIT",
                "credential_id": "288194d8-02bb-4719-a448-28g865e3e213",
                "payment_method_id": "e703eb9f-8eac-4eda-deec3935444d",
                "total_amount": {
                    "amount": 210252,
                    "currency_type": "USD"
                },
                "status": "COMPLETED",
                "created_time": "2023-10-08T10:31:14.804Z",
                "last_update_time": "2023-10-08T10:31:15.684Z"
            }
        }
    ]
}

The following API request retrieves all Transactions for an Organization.

HTTP Request

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

Parameters

Parameter Default Description
start_time Start time of transactions in UTC yyyy-mm-ddThh:mm:ss
end_time End time of transactions in UTC yyyy-mm-ddThh:mm:ss
ad_account_id Ad Account ID of the ad account to retrieve

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

Create an Ad Account

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

Parameters

Parameter Default Description
organization_id Organization ID

Get All Ad Accounts

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

The above command returns JSON structured like this:

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

This endpoint retrieves all ad accounts for the specified Organization.

HTTP Request

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

Parameters

Parameter Default Description
organization_id Organization ID

Get a Specific Ad Account

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

The above command returns JSON structured like this:

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

This endpoint retrieves a specific Ad Account.

HTTP Request

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

URL Parameters

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

Update Ad Account

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

The above command returns JSON structured like this:

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

This endpoint updates a specific Ad Account.

Attributes that can be updated

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

HTTP Request

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

URL Parameters

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

Update an Ad Account’s Lifetime Spend Cap

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

The above command returns JSON structured like this:

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

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

Assign Funding Source

Assigning funding sources to ad accounts can be done in Business Manager. Please reach out to your partner manager for further assistance.

Ad Account creation - Example 1

Ad Account - Used for Political advertising

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

The above command returns JSON structured like this:

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

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

Ad Account creation - Example 2

Ad Account - Used for Credit, Housing, Employment Ads

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

The above command returns JSON structured like this:

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

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

Ad Account creation - Example 3

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

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

The above command returns JSON structured like this:

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

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

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 admin, business_admin, data_admin, member

A Member entity must be assigned one of the Organization role types.

Name Description
admin Admin access to everything in the Organization and all Ad Accounts including creating, updating, deleting entities, adding new Members, assigning Roles
business_admin Can access full Business Manager capabilities (payment methods, roles, organization details), but doesn’t have access to individual ad accounts or catalogs
data_admin Reporting Admin role tailored for reporting only, this Role has reporting access only to all Ad Accounts in the Organization
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 Ad Account 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

Catalog Roles

Attributes

Attribute Description Required Possible Values
member_id Member ID R
catalog_id Catalog ID R
type Catalog role type R catalog_admin, catalog_advertiser

In order to be assigned a Catalog role the Member in question first needs the Organization role type member.

Name Description
catalog_admin Catalog Admins can edit and view existing catalogs which they have been assigned to by an Organization Admin, as well as create ads from those catalogs
catalog_advertiser Catalog Advertisers can create ads from catalogs which they have been assigned to by an Organization Admin, however they cannot edit those catalogs

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/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/roles?limit=200" \
  -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 under 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

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Update Ad Account Role

curl -X PUT \
  -d '{"roles":[{"id":"f7cd2f3c-de7e-4b4f-b8f4-44f2b428bca9","container_kind":"AdAccounts","container_id":"22225ba6-7559-4000-9663-bace8adff5f2","member_id":"9db3e9a8-b7d4-4bb9-922f-72ea22d10aa6","ad_account_id":"22225ba6-7559-4000-9663-bace8adff5f2","type":"general"}]}' \
  -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": "583521e0-da89-48a6-8bc9-195ad595391b",
    "roles": [
        {
            "sub_request_status": "SUCCESS",
            "role": {
                "id": "f7cd2f3c-de7e-4b4f-b8f4-44f2b428bca9",
                "updated_at": "2022-09-21T00:50:46.146Z",
                "created_at": "2020-03-25T17:55:01.344Z",
                "container_kind": "AdAccounts",
                "container_id": "22225ba6-7559-4000-9663-bace8adff5f2",
                "member_id": "9db3e9a8-b7d4-4bb9-922f-72ea22d10aa6",
                "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2",
                "type": "general"
            }
        }
    ]
}

The following API request updates the Ad Account role for a Member.

Attributes that can be updated

Attribute Description Required Possible Values
type role type R admin, audience, creative, general, reports

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Create Catalog Role

curl -X POST \
  -d '{"roles": [{"member_id": "819eff0f-2673-480b-8f72-c128e61c6cc4","catalog_id": "9318ff5c-78f7-47db-8a32-675f0b787c75","type": "catalog_admin"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/catalogs/9318ff5c-78f7-47db-8a32-675f0b787c75/roles

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "6074452e00ff00ff05354518127f0001737e616473617069736300016275696c642d34303334633634322d312d3433382d320001015c",
  "roles": [
    {
      "sub_request_status": "SUCCESS",
      "role": {
        "id": "9f53e57d-cdbc-4c04-901d-bbe940b2a36c",
        "updated_at": "2021-04-12T13:03:42.378Z",
        "created_at": "2021-04-12T13:03:42.378Z",
        "container_kind": "Catalogs",
        "container_id": "8318ff5c-78f7-47db-8a32-675f0b787c75",
        "member_id": "819eff0f-2673-480b-8f72-c128e61c6cc4",
        "catalog_id": "9318ff5c-78f7-47db-8a32-675f0b787c75",
        "type": "catalog_admin"
      }
    }
  ]
}

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

HTTP Request

POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/roles

Parameters

Parameter Default Description
catalog_id Catalog ID

Get all Roles for Catalog

curl "https://adsapi.snapchat.com/v1/catalogs/9318ff5c-78f7-47db-8a32-675f0b787c75/roles?limit=200" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "60744c2d00ff0e2580408852b00001737e616473617069736300016275696c642d34303334633634322d312d3433382d320001012b",
    "paging": {},
    "roles": [
        {
            "sub_request_status": "SUCCESS",
            "role": {
                "id": "9f53e57d-cdbc-4c04-901d-bbe940b2a36c",
                "container_kind": "Catalogs",
                "container_id": "8318ff5c-78f7-47db-8a32-675f0b787c75",
                "member_id": "919eff0f-2673-480b-8f72-c128e61c6cc4",
                "catalog_id": "9318ff5c-78f7-47db-8a32-675f0b787c75",
                "type": "catalog_admin"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "role": {
                "id": "9e85e2f6-e6fe-4bc8-883d-a7d839c3e5bd",
                "container_kind": "Catalogs",
                "container_id": "8318ff5c-78f7-47db-8a32-675f0b787c75",
                "member_id": "971cfcae-895d-4314-9460-e2ffd2515dd0",
                "catalog_id": "9318ff5c-78f7-47db-8a32-675f0b787c75",
                "type": "catalog_advertiser"
            }
        }
    ]
}

The following API request gets a list of all Roles that have been created under a Catalog.

HTTP Request

GET https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/roles

Parameters

Parameter Default Description
catalog_id Catalog ID
limit integer, min 50, max 1000

Public Profiles Roles

Attributes

API Attribute Ads Manager Description
business_account_manager Admin Can change Public Profiles, add or remove any Snaps from Public Story, manage Saved Stories, assign roles and view insights
business_account_collaborator Collaborator Can view insights and add or remove any Snaps from their Public Story within a profile
business_account_story_contributor Story Contributor Can view all past Snaps. They can also add, remove and view insights on Snaps they post within a profile.
business_account_data_analyst Insights Viewer Can view the profile’s Public Story, Saved Story, Lens and profile analytics.
creative_contributor Creative Contributor Can submit content, such as Lenses, to profile’s Public Profile.

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, Catalog or Ad Account. If you are deleting all of a Member’s Roles, you should also delete the Member entity 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 max length: 375 characters
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 BRAND_AWARENESS (default), APP_CONVERSION, APP_INSTALL, CATALOG_SALES, ENGAGEMENT, LEAD_GENERATION, VIDEO_VIEW, WEB_CONVERSION, PROMOTE_STORIES, PROMOTE_PLACES
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
deleted Indicates whether the entity has been deleted or not, only shown when using the parameter read_deleted_entities Read-only true

** Coming soon. See Reach And Frequency

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

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

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

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

Create a Campaign

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{"campaigns": [{"name": "Cool Campaign", "ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1d0d", "status": "PAUSED", "start_time": "2016-08-11T22:03:58.869Z"}]}' \
   "https://adsapi.snapchat.com/v1/adaccounts/{ad_acount_id}/campaigns"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b002ad00ff07e1f50fd2267f0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
  "campaigns": [
    {
      "sub_request_status": "success",
      "campaign": {
        "id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
        "updated_at": "2016-08-14T05:33:33.876Z",
        "created_at": "2016-08-14T05:33:33.876Z",
        "name": "Cool Campaign",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "status": "PAUSED",
        "start_time": "2016-08-11T22:03:58.869Z"
      }
    }
  ]
}

This endpoint will create a campaign within a specified ad account.

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Update a Campaign

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"campaigns": [{"name": "Cool Campaign", "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "status": "PAUSED", "start_time": "2016-08-11T22:03:58.869Z", "end_time": "2016-08-21T22:03:58.869-0700", "id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39"}]}' 
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/campaigns

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b0032700ff07e0cfdaa5e1a40001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010105",
  "campaigns": [
    {
      "sub_request_status": "success",
      "campaign": {
        "id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
        "updated_at": "2016-08-14T05:35:35.943Z",
        "created_at": "2016-08-14T05:33:33.876Z",
        "name": "Cool Campaign",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "status": "PAUSED",
        "start_time": "2016-08-11T22:03:58.869Z",
        "end_time": "2016-08-22T05:03:58.869Z"
      }
    }
  ]
}

This endpoint will update a specified campaign.

Attributes that can be updated

Attribute Description Required Possible Values
end_time End time O
name Campaign name R
daily_budget_micro Daily Spend Cap (micro-currency) O
lifetime_spend_cap_micro Lifetime spend cap for the campaign (micro-currency) O
start_time Start time O
status Campaign status R ACTIVE, PAUSED

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Get All Campaigns

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

The above command returns JSON structured like this:

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

    [[[ snip ]]]

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

This endpoint retrieves all campaigns within a specified ad account.

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID
read_deleted_entities true optional parameter, this param will return the deleted attribute on deleted Campaign entities

Get a Specific Campaign

curl "https://adsapi.snapchat.com/v1/campaigns/92e1c28a-a331-45b4-8c26-fd3e0eea8c39" \
  -H "Authorization: Bearer  meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b0049c00ff0e8cb21af5199c0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010107",
  "campaigns": [
    {
      "sub_request_status": "success",
      "campaign": {
        "id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
        "updated_at": "2016-08-14T05:36:46.441Z",
        "created_at": "2016-08-14T05:33:33.876Z",
        "name": "Cool Campaign",
        "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
        "status": "PAUSED",
        "start_time": "2016-08-11T22:03:58.869Z",
        "end_time": "2016-08-22T05:03:58.869Z"
      }
    }
  ]
}

This endpoint retrieves a specific campaign.

HTTP Request

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

URL Parameters

Parameter Default Description
campaign_id Campaign ID
read_deleted_entities true optional parameter, this param will return the deleted attribute on deleted Campaign entities

Delete a Specific Campaign

curl -X DELETE "https://adsapi.snapchat.com/v1/campaigns/92e1c28a-a331-45b4-8c26-fd3e0eea8c39" \
  -H "Authorization: Bearer  meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b004dc00ff0e29c26b5d51840001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010106",
  "campaigns": []
}

This endpoint deletes a specific campaign.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the campaign to delete

Ad Squads

An Ad Squad is owned by a Campaign and contains one or more Ads.

Attributes

Attribute Description Required Possible Values
campaign_id Campaign ID R
bid_micro Max Bid (micro-currency) R bid_micro is currency specific see Currency Specific bids for Mininum/Maximum value
billing_event Billing Event R IMPRESSION
child_ad_type Indicates what Ad type the Ad Squad uses, if not set this value will be set automatically once an Ad has been added under the Ad Squad, at that point the attribute becomes immutable O 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
forced_view_setting Indicates the type of Commercial used by the Ad Squad. If this is set, all Creatives in the Ad Squad must have a forced_view_eligibility value of FULL_DURATION or SIX_SECONDS. If not set this value will be set automatically once a Creative with forced_view_eligibility is added to the Ad Squad, once this value is set it’s immutable O FULL_DURATION, SIX_SECONDS
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 Delivery optimisation window O SWIPE_28DAY_VIEW_1DAY (default), SWIPE_7DAY , see Delivery Optimization Windows
placement_v2 Placement R Json object containing advanced placement options See placement_v2
start_time Start time O
status Ad Squad status O ACTIVE, PAUSED
story_ad_creative_type Indicates the type of Creative used in Dynamic Story Ads, required when using Dynamic Story Ads O APP_INSTALL, WEB_VIEW, DEEP_LINK
targeting Targeting spec R
type Ad Squad Type R SNAP_ADS, LENS, FILTER
cap_and_exclusion_config The frequency cap and exclusion spec O If this is set and the Ad Squad is inside of an Auction campaign, Multi-format Delivery cannot be used and all ads in the ad squad must be of the same ad type.
ad_scheduling_config The schedule for running ads O
bid_strategy Bidding strategy for this Ad Squad R AUTO_BID, LOWEST_COST_WITH_MAX_BID, MIN_ROAS, TARGET_COST, see bid_strategy
roas_value_micro The desired ROAS used with the MIN_ROAS BidStrategy R if BidStrategy = MIN_ROAS Minimum value 10000 , Maximum value 100000000
pixel_id Pixel to be associated with the Ad Squad O
measurement_provider_names approved measurement provider O MOAT_SS, DOUBLEVERIFY
reach_and_frequency_status** Status of the reach and frequency booking R Must be set to PENDING which automatically updates to ACTIVE or FAILED after booking
delivery_constraint Type of delivery R DAILY_BUDGET (when using daily_budget_micro), LIFETIME_BUDGET (when using lifetime_budget_micro), REACH_AND_FREQUENCY**
reach_goal** Reach goal as specified in the Forecasting request R Must match the value in the forecasting request
impression_goal** Reach goal as specified in the Forecasting request R Must match the value in the forecasting request
pacing_type Type of pacing O STANDARD (default), ACCELERATED
delivery_status Delivery status Read-only See Delivery status
event_sources Snap App Id to be associated with the Ad Squad O/Required when using SKAdnetwork enrollment Availble for Optimization Goals APP_REENGAGE_OPEN / APP_REENGAGE_PURCHASE and Dynamic Product Ads when using APP_INSTALL / DEEP_LINK
skadnetwork_properties.status SKAdnetwork enrollment status Read-only ENROLLED, NEVER_ENROLLED, WITHDRAWN
deleted Indicates whether the entity has been deleted or not, only shown when using the parameter read_deleted_entities Read-only true
separated_types Indicates if a targeting spec type has been separated into the new “targeting_spec” entity. Read-only “separated_types”: [“GEO”]

** See Reach And Frequency

Currency specific bids

The minimum/maximum value of bid_micro is determined by the currency attribute which is set on the Ad Account entity. All values listed are in micro-currency.

ISO code Currency Minimum (micro-currency) Maximum (micro-currency)
AED UAE Dirham 10,000 500,000,000
AUD Australian Dollar 10,000 100,000,000
BAM Bosnian Mark 10,000 100,000,000
CAD Canadian Dollar 10,000 100,000,000
CHF Swiss Franc 10,000 100,000,000
CNY Chinese Yuan 10,000 500,000,000
DKK Danish Krone 10,000 500,000,000
EUR Euro 10,000 100,000,000
GBP Pound Sterling 10,000 100,000,000
HKD Hong Kong Dollar 10,000 500,000,000
ILS Israeli New Shekel 10,000 500,000,000
INR Indian Rupee 10,000 500,000,000
KWD Kuwaiti Dinar 10,000 100,000,000
NOK Norwegian Krone 10,000 500,000,000
QAR Qatari Rial 10,000 500,000,000
SAR Saudi Riyal 10,000 500,000,000
SEK Swedish Krona 10,000 500,000,000
USD US Dollar 10,000 500,000,000

Multi-Format Delivery

It is possible to combine Ads of different types in the same Ad Squad with some restrictions.

The rules governing Multi-Format Delivery are described further in the following sections.

Eligible Ad Squad Optimization Goals

If you use one of the following Goal-based Bidding optimization goals, you will be able to put multiple types of ads in an Ad Squad.

Supported Ad Combinations

The following table shows which ad types can be combined in the same Ad Squad.

Ad Name Ad Type Supports Multi-Format Delivery? Notes
Snap Ads (attachment), Story Ad, Collection Ad SNAP_AD, APP_INSTALL, REMOTE_WEBPAGE, DEEP_LINK, AD_TO_LENS, AD_TO_CALL, AD_TO_MESSAGE, LEAD_GEN, STORY, COLLECTION YES Snap Ads with different attachment types, Story Ads and Collection Ads can be mixed in the same Ad Squad.

Story Ads run in between stories (no thumbnail) when targeted at INTERSTITIAL_USER or INTERSTITIAL_CONTENT
Dynamic Snap Ad SNAP_AD, STORY, COLLECTION YES Dynamic Product Ads can be mixed with each other, cannot be mixed with non-dynamic Ad types.

DPA Ad are Creatives with render_type DYNAMIC
Commercial SNAP_AD, REMOTE_WEBPAGE, AD_TO_LENS YES Commercials can be mixed with each other, cannot be mixed with non-commercials.

Commercials are Creatives with forced_view_eligibility set to FULL_DURATION or SIX_SECONDS and targeted at Premium Content Bundles.
Lens LENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK YES Lenses cannot be mixed with non-Lens Ad types.

List Ad Types in an Ad Squad

curl -X GET \
-H 'Authorization: Bearer meowmeowmeow' \
'https://adsapi.snapchat.com/v1/adsquads/67fb5af9-b95f-413e-a998-130b4b58caad/ad_squad_ad_restrictions'

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "6543215600ff04cc8908e19ab30001737e616473617069736300016275696c642d62333561306232372d312d3533332d3000123123",
    "ad_squad_ad_restrictions": [
        {
            "sub_request_status": "SUCCESS",
            "ad_squad_ad_restrictions": {
                "id": "567890f9-b95f-413e-a998-130b4b765432",
                "updated_at": "2022-04-15T19:10:19.220Z",
                "created_at": "2021-12-07T01:18:19.226Z",
                "ad_types": {
                    "SNAP_AD": 3,
                    "REMOTE_WEBPAGE": 1,
                    "STORY": 1
                }
            }
        }
    ]
}

This API request fetches a summary of the Ad types currently in the Ad Squad. The list is found in the response’s ad_types attribute.

HTTP Request

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

Parameters

Parameter Default Description
ad_squad_id Ad Squad

Multi-format Ad Squad Example 1

This is an example of an Ad Squad that contains a SNAP_AD, a STORY Ad, and a REMOTE_WEBSITE ad.

Example output from listing the ads in the ad squad

{
    "request_status": "SUCCESS",
    "request_id": "625f4f7500ff054633669e73350001737e616473617069736300016275696c642d66316366613233612d312d353312345697800110",
    "paging": {},
    "ads": [
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "2b3b55f3-ddf6-43e8-9f76-c74d94db5e2a",
                "updated_at": "2022-04-19T07:53:07.943Z",
                "created_at": "2022-04-15T01:03:28.845Z",
                "effective_status": "PAUSED",
                "name": "My Snap Ad",
                "ad_squad_id": "654321ab-b95f-413e-a998-12345678xyza",
                "creative_id": "ee9a155d-0883-4888-aa25-3d7375yu5432",
                "status": "ACTIVE",
                "type": "SNAP_AD",
                "render_type": "STATIC",

                ...

                [[snip]]

                ...

            }
        },
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "3fbc4a8d-61f1-4a50-8327-b68a4d7042d6",
                "updated_at": "2022-04-19T07:40:06.541Z",
                "created_at": "2022-04-15T01:01:55.315Z",
                "effective_status": "PAUSED",
                "name": "My Story Ad",
                "ad_squad_id": "654321ab-b95f-413e-a998-12345678xyza",
                "creative_id": "f2afa2cd-799c-4848-8f71-192830jkf1211",
                "status": "ACTIVE",
                "type": "STORY",
                "render_type": "STATIC",

                ...

                [[snip]]

                ...
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "7976e781-ddc1-4f4f-80e4-82d91d3d596e",
                "updated_at": "2022-04-19T08:14:47.629Z",
                "created_at": "2022-04-15T19:10:19.174Z",
                "effective_status": "PAUSED",
                "name": "My Website Ad",
                "ad_squad_id": "654321ab-b95f-413e-a998-12345678xyza",
                "creative_id": "6fcc0703-c3e5-47ad-bf00-js82ks9102ec",
                "status": "ACTIVE",
                "type": "REMOTE_WEBPAGE",
                "render_type": "STATIC",

                ...

                [[snip]]

                ...
            }
        }
    ]
}

Multi-format Ad Squad Example 2

This is an example of an Ad Squad that contains a LENS ad and a LENS_REMOTE_WEBPAGE ad.

Example output from listing the ads in the ad squad

{
    "request_status": "SUCCESS",
    "request_id": "6yh2781920ff01d69c4f55568e0001737e616473617069736300016275696c642d66316366613233612d312d3533342d392k287620",
    "paging": {},
    "ads": [
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "87654231-a083-48bd-bda1-776b3944308e",
                "updated_at": "2022-04-16T07:06:46.062Z",
                "created_at": "2022-04-15T21:52:22.942Z",
                "name": "test lens ad no attachment",
                "ad_squad_id": "6543610c-9e8e-4b28-86b8-40acc2f4abcd",
                "creative_id": "ed2eaf37-515d-4a54-bf6b-113j827d6543",
                "status": "PAUSED",
                "type": "LENS",
                "render_type": "STATIC"

                ...

                [[snip]]

                ...

            }
        },
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "12349876-cbad-42da-8f57-091416cd75ed",
                "updated_at": "2022-04-20T00:53:59.890Z",
                "created_at": "2022-04-20T00:53:59.545Z",
                "name": "test lens remote webpage",
                "ad_squad_id": "6543610c-9e8e-4b28-86b8-40acc2f4abcd",
                "creative_id": "7684b71d-ec74-4de6-b1bd-c32abcdh7usi",
                "status": "ACTIVE",
                "type": "LENS_REMOTE_WEBPAGE",
                "render_type": "STATIC",

                ...

                [[snip]]

                ...
            }
        }
    ]
}

Event sources

Example request setting the event_sources to Snap App ID

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"adsquads": [{"id": "7e52b0f4-a3fc-46f2-9a33-f03d71c55047","name": "Badger Supplies Ad Squad","status": "ACTIVE","campaign_id": "7b15f643-3052-4eb3-b5e1-09fa1ce0116a","type": "SNAP_ADS","targeting": {"regulated_content": false,"geos": [{"country_code": "uk"}],"devices": [{"os_type": "iOS"}],"auto_expansion_options":{"interest_expansion_option":{"enabled": true},"custom_audience_expansion_option":{"enabled": true}}},"placement_v2": {"config": "AUTOMATIC"},"billing_event": "IMPRESSION","bid_strategy": "AUTO_BID","daily_budget_micro": 50000000,"start_time": "2021-11-01T17:12:49.707Z","end_time": "2021-12-01T17:12:49.707Z","optimization_goal": "SWIPES","event_sources": {"MOBILE_APP": ["8b5b83ec-c593-4a64-9c6d-a0eb9da0edb8"]}}]}'
  https://adsapi.snapchat.com/v1/campaigns/88539b6b-93f2-4b3a-8181-ca869cb45088/adsquads

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "6011886c00ff09fe1978d146130001737e616473617069736300016275696c642d65386534326330362d312d3431372d3000010113",
    "adsquads": [
        {
            "sub_request_status": "SUCCESS",
            "adsquad": {
                "id": "7e52b0f4-a3fc-46f2-9a33-f03d71c55047",
                "updated_at": "2021-01-27T15:36:13.676Z",
                "created_at": "2020-11-11T10:24:46.334Z",
                "name": "Badger Supplies Ad Squad",
                "status": "ACTIVE",
                "campaign_id": "7b15f643-3052-4eb3-b5e1-09fa1ce0116a",
                "type": "SNAP_ADS",
                "targeting": {
                    "regulated_content": false,
                    "geos": [
                        {
                            "country_code": "uk"
                        }
                    ],
                    "devices": [
                        {
                            "os_type": "iOS"
                        }
                    ],
                    "auto_expansion_options":
                    {
                        "interest_expansion_option":
                        {
                            "enabled": true
                        },
                        "custom_audience_expansion_option":
                        {
                            "enabled": true
                        }
                    }
                },
                "targeting_reach_status": "VALID",
                "placement_v2": {
                    "config": "AUTOMATIC"
                },
                "billing_event": "IMPRESSION",
                "auto_bid": true,
                "target_bid": false,
                "bid_strategy": "AUTO_BID",
                "daily_budget_micro": 50000000,
                "start_time": "2021-11-01T17:12:49.707Z",
                "end_time": "2021-12-01T17:12:49.707Z",
                "optimization_goal": "SWIPES",
                "event_sources": {
                    "MOBILE_APP": [
                        "8b5b83ec-c593-4a64-9c6d-a0eb9da0edb8"
                    ]
                },
                "delivery_constraint": "DAILY_BUDGET",
                "pacing_type": "STANDARD",
                "creation_state": "PUBLISHED"
            }
        }
    ]
}

The event_sources attribute defines a Snap App ID which is associated with the Ad Squad, events triggered by the App will be eligible for conversions and can also used to set up Mobile custom audiences. It is recommended that you add event_sources to any Ad Squad using the optimization goals APP_INSTALLS or DEEP_LINK.

The event_sources attribute is a prerequisite for App Install state targeting.

SKAdNetwork tracking

SKAdNetwork upcoming changes

On the 7 September 2022 we are making the following changes to SKAd tracking.

SKAdNetwork prerequisites & restrictions

SKAdNetwork prerequisites

Enrolling your Ad Squad into SKAdnetwork attribution has a number of prerequisites:

  1. A Snap App ID has been set up, the iOS App ID has been added and verified, this can be checked by fetching the App with the Snap App ID and reading the attribute ios_app_id_verified, read more about the Snap App ID.
  2. A SKAdnetwork Campaign ID is available for the Snap App ID.
  3. The Ad Squad has the attribute event_sources set to the Snap App ID and is targeting only iOS devices.

SKAdNetwork restrictions

Ad Squads that are enrolled into SKAdNetwork tracking are subject to the following restrictions:

SKAdNetwork Campaign ID check

curl "https://adsapi.snapchat.com/v1/mobile_apps/fb5b83ec-c593-4a64-9c6d-a0eb9da0edba/ecid_status"
  -H "Authorization: Bearer meowmeowmeow"

Example - checking SKAdnetwork campaign id availability

{
    "request_status": "SUCCESS",
    "request_id": "6000ff63ae00ff0aca494709c9440001737e616473617069736300016275696c642d32396339353666662d312d3431332d3100010117",
    "ecid_status": "AVAILABLE_IN_GRACE_PERIOD"
}

Before you can create an Ad Squad which is opted into SKAdnetwork tracking you should carry out a check to find out the status of available Apple Campaign IDs (ecid) for the App in question. The response will inidcate whether there is a free Apple Campaign ID and the status which it is currently in.

An App is limited to 38 simultaneously live Ad sets that can be measured through the SKAdNetwork, you should allow for a cool-down period between uses of the same Apple Campaign ID to ensure clean reporting of your conversions.

SKAdnetwork Campaign ID status

ecid_status Description
AVAILABLE There is at least one available App Campaign ID
AVAILABLE_IN_GRACE_PERIOD An Apple Campaign ID is available but was recently attached to another campaign, some conversions might get attributed to the new Campagin for the next 48 hours
NOT_AVAILABLE There is no available Apple Campaign ID

HTTP Request

GET https://adsapi.snapchat.com/v1/mobile_apps/{snap_app_id}/ecid_status

Parameters

Parameter Default Description
snap_app_id Snap App ID

SKAdnetwork enrollment

If all the prerequisites are met an Ad Squad can be enrolled into SKAdnetwork tracking, this can happen by creating a new Ad Squad that is enrolled on creation.

Attribute Description Possible Values
placement_v2 Placement for the Ads Placement V2

SKAdnetwork AdSquad ecid status check

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

Example - checking all AdSquads currently assigned an Apple Campaign ID

{
    "request_status": "SUCCESS",
    "request_id": "62730c8b00ff0c935616bdb0930001737e7465616d6b6f363139000161646d616e616765722d6170693a776e75636b6f6c737465737400010154",
    "ad_squads": [
        {
            "ad_squad_id": "2b985a73-eef7-4532-a64c-4b5b898666aa",
            "ad_squad_name": "United States, All Genders, All Ages",
            "ad_squad_status": "ACTIVE",
            "ecid_status": "NOT_AVAILABLE",
            "ad_account_id": "1703100d-cc15-4857-b8bf-dfb590f33999"
        },
        {
            "ad_squad_id": "7fde64a5-936c-4ca8-b841-6d865b4ee929",
            "ad_squad_name": "United States, All Genders, All Ages",
            "ad_squad_status": "ACTIVE",
            "ecid_status": "NOT_AVAILABLE",
            "ad_account_id": "1703100d-cc15-4857-b8bf-dfb590f33999"
        },
        {
            "ad_squad_id": "75a5de36-bcc0-4eae-a440-495e3b335d1b",
            "ad_squad_name": "United States, All Genders, All Ages - a",
            "ad_squad_status": "PAUSED",
            "ecid_status": "AVAILABLE_IN_GRACE_PERIOD",
            "ad_account_id": "2ac22383-6e7e-4134-83a3-299f1e2a05db"
        },
        {
            "ad_squad_id": "42eb60be-91bd-4a9d-9ed0-806b550638b5",
            "ad_squad_name": "United States, All Genders, All Ages",
            "ad_squad_status": "ACTIVE",
            "ecid_status": "NOT_AVAILABLE",
            "ad_account_id": "2ac22383-6e7e-4134-83a3-299f1e2a05db"
        },
        {
            "ad_squad_id": "0cb8390a-4c63-4cae-a6df-c77d1405546e",
            "ad_squad_name": "United States, All Genders, All Ages",
            "ad_squad_status": "PAUSED",
            "ecid_status": "AVAILABLE_IN_GRACE_PERIOD",
            "ad_account_id": "1703100d-cc15-4857-b8bf-dfb590f33999"
        },
        {
            "ad_squad_id": "f3827145-dd9e-47d0-b57b-a2ad0eab4068",
            "ad_squad_name": "United States, All Genders, All Ages",
            "ad_squad_status": "ACTIVE",
            "ecid_status": "NOT_AVAILABLE",
            "ad_account_id": "1703100d-cc15-4857-b8bf-dfb590f33999"
        },
        {
            "ad_squad_id": "f750048e-a1c4-4b50-979f-4d1fda2ea7d4",
            "ad_squad_name": "United States, All Genders, All Ages",
            "ad_squad_status": "ACTIVE",
            "ecid_status": "NOT_AVAILABLE",
            "ad_account_id": "2ac22383-6e7e-4134-83a3-299f1e2a05db"
        },
        {
            "ad_squad_id": "4f579fce-9a65-4ba5-84d6-a475326b1796",
            "ad_squad_name": "United States, All Genders, All Ages",
            "ad_squad_status": "ACTIVE",
            "ecid_status": "NOT_AVAILABLE",
            "ad_account_id": "2ac22383-6e7e-4134-83a3-299f1e2a05db"
        },
        {
            "ad_squad_id": "33773acc-c0af-49d7-846f-1d67325a400d",
            "ad_squad_name": "United States, All Genders, All Ages - a",
            "ad_squad_status": "PAUSED",
            "ecid_status": "AVAILABLE_IN_GRACE_PERIOD",
            "ad_account_id": "2ac22383-6e7e-4134-83a3-299f1e2a05db"
        },
        {
            "ad_squad_id": "55b3c4c0-2406-4a37-b610-92951bb642a6",
            "ad_squad_name": "United States, All Genders, All Ages",
            "ad_squad_status": "ACTIVE",
            "ecid_status": "NOT_AVAILABLE",
            "ad_account_id": "2ac22383-6e7e-4134-83a3-299f1e2a05db"
        },
        {
            "ad_squad_id": "bb5fb714-1d3c-4638-8e54-7320ab5ff81a",
            "ad_squad_name": "United States, All Genders, All Ages",
            "ad_squad_status": "ACTIVE",
            "ecid_status": "NOT_AVAILABLE",
            "ad_account_id": "1703100d-cc15-4857-b8bf-dfb590f33999"
        }
    ]
}


This method returns a list of all Ad Squads that are using an Apple Campaign Id (ecid) for the Snap App ID in question.

The response returns the status of that Campaign Id, the status can be either NOT_AVAILABLE or AVAILABLE_IN_GRACE_PERIOD. Since Apple Campaign IDs are platform wide, you may not have permission to see all Ad Squads that are assigned an Apple Campaign ID.

Once an Apple Campaign ID has come out of it’s cool-down period it’s no longer associated with an Ad Squad and is no longer visible in the response of this request.

SKAdnetwork AdSquad status

ecid_status Description
AVAILABLE_IN_GRACE_PERIOD The Apple Campaign ID attached to this AdSquad is in a cooldown period, if used some conversions might get attributed to the new Campagin for the next 48 hours
NOT_AVAILABLE This AdSquad has an Apple Campaign ID attached to it

HTTP Request

GET https://adsapi.snapchat.com/v1/mobile_apps/{{mobile_app_id}}/skadnetwork_adsquads

Parameters

Parameter Default Description
snap_app_id Snap App ID

SKAdnetwork example 1

SKAdNetwork enrollement by updating an Ad Squad

Example - Updating an Ad Squad to be enrolled in the SKAdnetwork tracking

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"adsquads":[{"id":"1b99bd80-5279-41c1-9d8d-e28875d7e7dd","name":"SKAdNetwork Example - Opt in","status":"ACTIVE","campaign_id":"46fb184a-d371-49f0-8384-ea533cef217a","type":"SNAP_ADS","targeting":{"regulated_content":false,"demographics":[{"min_age":"21","max_age":"24"}],"geos":[{"country_code":"us"}],"devices":[{"os_type":"iOS","os_version_min":"11.3"}]},"targeting_reach_status":"VALID","placement_v2":{"config":"AUTOMATIC"},"billing_event":"IMPRESSION","bid_micro":200000000,"auto_bid":false,"target_bid":false,"bid_strategy":"LOWEST_COST_WITH_MAX_BID","daily_budget_micro":2000000000,"start_time":"2021-08-15T19:16:17.444Z","end_time":"2021-08-19T19:16:17.444Z","optimization_goal":"APP_INSTALLS","event_sources":{"MOBILE_APP":["fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"]},"skadnetwork_properties":{"enroll_action":"OPT_IN"}}]}'
  https://adsapi.snapchat.com/v1/campaigns/46fb184a-d371-49f0-8384-ea533cef217a/adsquads

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "6006dd1400ff04d29d47769a7c0001737e616473617069736300016275696c642d34343839623532342d312d3431342d3000010141",
    "adsquads": [
        {
            "sub_request_status": "SUCCESS",
            "adsquad": {
                "id": "1b99bd80-5279-41c1-9d8d-e28875d7e7dd",
                "updated_at": "2021-01-19T13:22:29.264Z",
                "created_at": "2021-01-15T13:46:43.768Z",
                "created_by_app_id": "ff503f30-8e94-450b-abac-18e3e25a8da1",
                "created_by_user": "82beca53-2402-45f6-bc0f-1244a2cb8936",
                "name": "SKAdNetwork Example - Opt in",
                "status": "ACTIVE",
                "campaign_id": "46fb184a-d371-49f0-8384-ea533cef217a",
                "type": "SNAP_ADS",
                "targeting": {
                    "regulated_content": false,
                    "demographics": [
                        {
                            "min_age": "21",
                            "max_age": "24"
                        }
                    ],
                    "geos": [
                        {
                            "country_code": "us"
                        }
                    ],
                    "devices": [
                        {
                            "os_type": "iOS",
                            "os_version_min":"11.3"
                        }
                    ]
                },
                "targeting_reach_status": "VALID",
                "placement_v2": {
                    "config": "AUTOMATIC"
                },
                "billing_event": "IMPRESSION",
                "bid_micro": 200000000,
                "auto_bid": false,
                "target_bid": false,
                "bid_strategy": "LOWEST_COST_WITH_MAX_BID",
                "daily_budget_micro": 2000000000,
                "start_time": "2021-08-15T19:16:17.444Z",
                "end_time": "2021-08-19T19:16:17.444Z",
                "optimization_goal": "APP_INSTALLS",
                "event_sources": {
                    "MOBILE_APP": [
                        "fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"
                    ]
                },
                "delivery_constraint": "DAILY_BUDGET",
                "pacing_type": "STANDARD",
                "creation_state": "PUBLISHED",
                "delivery_status": [
                    "INVALID_START_TIME",
                    "INVALID_NOT_EFFECTIVE_ACTIVE",
                    "INVALID_EFFECTIVE_INVALID"
                ],
                "skadnetwork_properties": {
                    "status": "ENROLLED"
                }
            }
        }
    ]
}

By updating the Ad Squad and including the attribute enroll_action with the value OPT_IN the Ad Squad will be enrolled into SKAdnetwork tracking.

skadnetwork_properties":{"enroll_action":"OPT_IN"}}]}

SKAdnetwork example 2

SKAdNetwork withdrawal by updating an Ad Squad

Example - Updating an Ad Squad to be withdrawn from the SKAdnetwork tracking

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"adsquads":[{"id":"1b99bd80-5279-41c1-9d8d-e28875d7e7dd","name":"SKAdNetwork Example - Opt out","status":"ACTIVE","campaign_id":"46fb184a-d371-49f0-8384-ea533cef217a","type":"SNAP_ADS","targeting":{"regulated_content":false,"demographics":[{"min_age":"21","max_age":"24"}],"geos":[{"country_code":"us"}],"devices":[{"os_type":"iOS","os_version_min":"11.3"}]},"targeting_reach_status":"VALID","placement_v2":{"config":"AUTOMATIC"},"billing_event":"IMPRESSION","bid_micro":200000000,"auto_bid":false,"target_bid":false,"bid_strategy":"LOWEST_COST_WITH_MAX_BID","daily_budget_micro":2000000000,"start_time":"2021-08-15T19:16:17.444Z","end_time":"2021-08-19T19:16:17.444Z","optimization_goal":"APP_INSTALLS","event_sources":{"MOBILE_APP":["fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"]},"skadnetwork_properties":{"enroll_action":"OPT_OUT"}}]}'
  https://adsapi.snapchat.com/v1/campaigns/46fb184a-d371-49f0-8384-ea533cef217a/adsquads

By updating the Ad Squad and including the attribute enroll_action with the value OPT_OUT the Ad Squad will be withdrawn from SKAdnetwork tracking.

skadnetwork_properties":{"enroll_action":"OPT_OUT"}}]}

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "6006dd1400ff04d29d47769a7c0001737e616473617069736300016275696c642d34343839623532342d312d3431342d3000010141",
    "adsquads": [
        {
            "sub_request_status": "SUCCESS",
            "adsquad": {
                "id": "1b99bd80-5279-41c1-9d8d-e28875d7e7dd",
                "updated_at": "2021-01-19T13:22:29.264Z",
                "created_at": "2021-01-15T13:46:43.768Z",
                "created_by_app_id": "ff503f30-8e94-450b-abac-18e3e25a8da1",
                "created_by_user": "82beca53-2402-45f6-bc0f-1244a2cb8936",
                "name": "SKAdNetwork Example - Opt out",
                "status": "ACTIVE",
                "campaign_id": "46fb184a-d371-49f0-8384-ea533cef217a",
                "type": "SNAP_ADS",
                "targeting": {
                    "regulated_content": false,
                    "demographics": [
                        {
                            "min_age": "21",
                            "max_age": "24"
                        }
                    ],
                    "geos": [
                        {
                            "country_code": "us"
                        }
                    ],
                    "devices": [
                        {
                            "os_type": "iOS",
                            "os_version_min":"11.3"
                        }
                    ]
                },
                "targeting_reach_status": "VALID",
                "placement_v2": {
                    "config": "AUTOMATIC"
                },
                "billing_event": "IMPRESSION",
                "bid_micro": 200000000,
                "auto_bid": false,
                "target_bid": false,
                "bid_strategy": "LOWEST_COST_WITH_MAX_BID",
                "daily_budget_micro": 2000000000,
                "start_time": "2021-08-15T19:16:17.444Z",
                "end_time": "2021-08-19T19:16:17.444Z",
                "optimization_goal": "APP_INSTALLS",
                "event_sources": {
                    "MOBILE_APP": [
                        "fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"
                    ]
                },
                "delivery_constraint": "DAILY_BUDGET",
                "pacing_type": "STANDARD",
                "creation_state": "PUBLISHED",
                "delivery_status": [
                    "INVALID_START_TIME",
                    "INVALID_NOT_EFFECTIVE_ACTIVE",
                    "INVALID_EFFECTIVE_INVALID"
                ],
                "skadnetwork_properties": {
                    "status": "WITHDRAWN"
                }
            }
        }
    ]
}

SKAdnetwork example 3

SKAdNetwork enrollement at Ad Squad creation

Example - Updating an Ad Squad to be enrolled in the SKAdnetwork tracking

curl -X POST \
  -d '{"adsquads":[{"name":"SKAdNetwork Example - Creation Opt in","status":"ACTIVE","campaign_id":"46fb184a-d371-49f0-8384-ea533cef217a","bid_micro":"200000000","bid_strategy":"LOWEST_COST_WITH_MAX_BID","daily_budget_micro":"2000000000","start_time":"2021-08-15T12:16:17.444-07:00","end_time":"2021-08-19T12:16:17.444-07:00","optimization_goal":"APP_INSTALLS","event_sources":{"MOBILE_APP":["fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"]},"skadnetwork_properties":{"enroll_action":"OPT_IN"},"placement_v2":{"config":"AUTOMATIC"},"targeting":{"regulated_content":"false","demographics":[{"min_age":"21","max_age":"24"}],"geos":[{"country_code":"us"}],"devices":[{"os_type":"iOS"},"os_version_min":"11.3"]}}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/campaigns/46fb184a-d371-49f0-8384-ea533cef217a/adsquads

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "6006dd1400ff04d29d47769a7c0001737e616473617069736300016275696c642d34343839623532342d312d3431342d3000010141",
    "adsquads": [
        {
            "sub_request_status": "SUCCESS",
            "adsquad": {
                "id": "1b99bd80-5279-41c1-9d8d-e28875d7e7dd",
                "updated_at": "2021-01-19T13:22:29.264Z",
                "created_at": "2021-01-15T13:46:43.768Z",
                "name": "SKAdNetwork Example - Creation Opt in",
                "status": "ACTIVE",
                "campaign_id": "46fb184a-d371-49f0-8384-ea533cef217a",
                "type": "SNAP_ADS",
                "targeting": {
                    "regulated_content": false,
                    "demographics": [
                        {
                            "min_age": "21",
                            "max_age": "24"
                        }
                    ],
                    "geos": [
                        {
                            "country_code": "us"
                        }
                    ],
                    "devices": [
                        {
                            "os_type": "iOS",
                            "os_version_min":"11.3"
                        }
                    ]
                },
                "targeting_reach_status": "VALID",
                "placement_v2": {
                    "config": "AUTOMATIC"
                },
                "billing_event": "IMPRESSION",
                "bid_micro": 200000000,
                "auto_bid": false,
                "target_bid": false,
                "bid_strategy": "LOWEST_COST_WITH_MAX_BID",
                "daily_budget_micro": 2000000000,
                "start_time": "2021-08-15T19:16:17.444Z",
                "end_time": "2021-08-19T19:16:17.444Z",
                "optimization_goal": "APP_INSTALLS",
                "event_sources": {
                    "MOBILE_APP": [
                        "fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"
                    ]
                },
                "delivery_constraint": "DAILY_BUDGET",
                "pacing_type": "STANDARD",
                "creation_state": "PUBLISHED",
                "delivery_status": [
                    "INVALID_START_TIME",
                    "INVALID_NOT_EFFECTIVE_ACTIVE",
                    "INVALID_EFFECTIVE_INVALID"
                ],
                "skadnetwork_properties": {
                    "status": "ENROLLED"
                }
            }
        }
    ]
}

By creating an Ad Squad and including the attribute enroll_action with the value OPT_IN the Ad Squad will be enrolled into SKAdnetwork tracking, but this assumes an Apple Campaign ID is vailable.

skadnetwork_properties":{"enroll_action":"OPT_IN"}}]}

SKAdnetwork example 4

SKAdNetwork detaching an Apple Campaign ID

Example - detaching an Apple Campaign ID (ecid)

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"adsquads":[{"id":"1b99bd80-5279-41c1-9d8d-e28875d7e7dd","name":"SKAdNetwork Example - ECID Detach","status":"PAUSED","campaign_id":"46fb184a-d371-49f0-8384-ea533cef217a","type":"SNAP_ADS","targeting":{"regulated_content":false,"demographics":[{"min_age":"21","max_age":"24"}],"geos":[{"country_code":"us"}],"devices":[{"os_type":"iOS","os_version_min":"11.3"}]},"targeting_reach_status":"VALID","placement_v2":{"config":"AUTOMATIC"},"billing_event":"IMPRESSION","bid_micro":200000000,"auto_bid":false,"target_bid":false,"bid_strategy":"LOWEST_COST_WITH_MAX_BID","daily_budget_micro":2000000000,"start_time":"2021-08-15T19:16:17.444Z","end_time":"2021-08-19T19:16:17.444Z","optimization_goal":"APP_INSTALLS","event_sources":{"MOBILE_APP":["fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"]},"skadnetwork_properties":{"ecid_enroll_action":"DETACH"}}]}'
  https://adsapi.snapchat.com/v1/campaigns/46fb184a-d371-49f0-8384-ea533cef217a/adsquads

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "6006dd1400ff04d29d47769a7c0001737e616473617069736300016275696c642d34343839623532342d312d3431342d3000010141",
    "adsquads": [
        {
            "sub_request_status": "SUCCESS",
            "adsquad": {
                "id": "1b99bd80-5279-41c1-9d8d-e28875d7e7dd",
                "updated_at": "2021-01-19T13:22:29.264Z",
                "created_at": "2021-01-15T13:46:43.768Z",
                "name": "SKAdNetwork Example - ECID Detach",
                "status": "ACTIVE",
                "campaign_id": "46fb184a-d371-49f0-8384-ea533cef217a",
                "type": "SNAP_ADS",
                "targeting": {
                    "regulated_content": false,
                    "demographics": [
                        {
                            "min_age": "21",
                            "max_age": "24"
                        }
                    ],
                    "geos": [
                        {
                            "country_code": "us"
                        }
                    ],
                    "devices": [
                        {
                            "os_type": "iOS",
                            "os_version_min":"11.3"
                        }
                    ]
                },
                "targeting_reach_status": "VALID",
                "placement_v2": {
                    "config": "AUTOMATIC"
                },
                "billing_event": "IMPRESSION",
                "bid_micro": 200000000,
                "auto_bid": false,
                "target_bid": false,
                "bid_strategy": "LOWEST_COST_WITH_MAX_BID",
                "daily_budget_micro": 2000000000,
                "start_time": "2021-08-15T19:16:17.444Z",
                "end_time": "2021-08-19T19:16:17.444Z",
                "optimization_goal": "APP_INSTALLS",
                "event_sources": {
                    "MOBILE_APP": [
                        "fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"
                    ]
                },
                "delivery_constraint": "DAILY_BUDGET",
                "pacing_type": "STANDARD",
                "creation_state": "PUBLISHED",
                "delivery_status": [
                    "INVALID_START_TIME",
                    "INVALID_NOT_EFFECTIVE_ACTIVE",
                    "INVALID_EFFECTIVE_INVALID"
                ],
                "skadnetwork_properties": {
                    "status": "ENROLLED",
                    "ecid_enrollment_status": "DETACHED"
                }
            }
        }
    ]
}

To detach an Apple Campaign ID from an Opted-in Ad Squad in order to free it up for use elsewhere you will need to detach the Apple Campaign ID and pause the Ad Squad in question.

You can detach the Campaign ID via ecid_enroll_action and so withdraw the Ad Squad from SKAd tracking, it’s possible to set the Ad Squad to paused and to detach the Campaign ID with the same API request. Note that it’s not possible to set an Ad Squad live once the Apple Campaign ID has been detached.

“skadnetwork_properties”:{“ecid_enroll_action”:”DETACH”}

SKAdnetwork example 5

SKAdNetwork re-attaching an Apple Campaign ID

Example - Re-attaching an Apple Campaign ID (ecid)

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"adsquads":[{"id":"1b99bd80-5279-41c1-9d8d-e28875d7e7dd","name":"SKAdNetwork Example - ECID attach","status":"ACTIVE","campaign_id":"46fb184a-d371-49f0-8384-ea533cef217a","type":"SNAP_ADS","targeting":{"regulated_content":false,"demographics":[{"min_age":"21","max_age":"24"}],"geos":[{"country_code":"us"}],"devices":[{"os_type":"iOS","os_version_min":"11.3"}]},"targeting_reach_status":"VALID","placement_v2":{"config":"AUTOMATIC"},"billing_event":"IMPRESSION","bid_micro":200000000,"auto_bid":false,"target_bid":false,"bid_strategy":"LOWEST_COST_WITH_MAX_BID","daily_budget_micro":2000000000,"start_time":"2021-08-15T19:16:17.444Z","end_time":"2021-08-19T19:16:17.444Z","optimization_goal":"APP_INSTALLS","event_sources":{"MOBILE_APP":["fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"]},"skadnetwork_properties":{"ecid_enroll_action":"ATTACH"}}]}'
  https://adsapi.snapchat.com/v1/campaigns/46fb184a-d371-49f0-8384-ea533cef217a/adsquads

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "6006dd1400ff04d29d47769a7c0001737e616473617069736300016275696c642d34343839623532342d312d3431342d3000010141",
    "adsquads": [
        {
            "sub_request_status": "SUCCESS",
            "adsquad": {
                "id": "1b99bd80-5279-41c1-9d8d-e28875d7e7dd",
                "updated_at": "2021-01-19T13:22:29.264Z",
                "created_at": "2021-01-15T13:46:43.768Z",
                "name": "SKAdNetwork Example - ECID attach",
                "status": "ACTIVE",
                "campaign_id": "46fb184a-d371-49f0-8384-ea533cef217a",
                "type": "SNAP_ADS",
                "targeting": {
                    "regulated_content": false,
                    "demographics": [
                        {
                            "min_age": "21",
                            "max_age": "24"
                        }
                    ],
                    "geos": [
                        {
                            "country_code": "us"
                        }
                    ],
                    "devices": [
                        {
                            "os_type": "iOS",
                            "os_version_min":"11.3"
                        }
                    ]
                },
                "targeting_reach_status": "VALID",
                "placement_v2": {
                    "config": "AUTOMATIC"
                },
                "billing_event": "IMPRESSION",
                "bid_micro": 200000000,
                "auto_bid": false,
                "target_bid": false,
                "bid_strategy": "LOWEST_COST_WITH_MAX_BID",
                "daily_budget_micro": 2000000000,
                "start_time": "2021-08-15T19:16:17.444Z",
                "end_time": "2021-08-19T19:16:17.444Z",
                "optimization_goal": "APP_INSTALLS",
                "event_sources": {
                    "MOBILE_APP": [
                        "fb5b83ec-c593-4a64-9c6d-a0eb9da0edba"
                    ]
                },
                "delivery_constraint": "DAILY_BUDGET",
                "pacing_type": "STANDARD",
                "creation_state": "PUBLISHED",
                "delivery_status": [
                    "INVALID_START_TIME",
                    "INVALID_NOT_EFFECTIVE_ACTIVE",
                    "INVALID_EFFECTIVE_INVALID"
                ],
                "skadnetwork_properties": {
                    "status": "ENROLLED",
                    "ecid_enrollment_status": "ATTACHED"
                }
            }
        }
    ]
}

To re-enable a withdrawn Ad Squad into SKAdnetwork tracking again you need to attach a free Apple Campaign ID (ecid) to the Ad Squad.

The two methods SKAdNetwork Campaign ID check and SKAdNetwork AdSquad ecid status check will allow you to find out if a Campaign ID is available, or if you need to free one up by detaching it from an AdSquad.

Once you have a free Campaign ID you can attach it by updating the Ad Squad using the ecid_enroll_action

“skadnetwork_properties”:{“ecid_enroll_action”:”ATTACH”}

Bid Strategy

Example request setting bid_strategy and bid_micro

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"adsquads":[{"id": "9077bb86-fb9a-4ded-9da9-67bc2e1dd6c5","name": "Badger Supplies Ad Squad - event sources","status": "ACTIVE","campaign_id": "4813d068-370b-45f6-a8d6-e01de878f1b5","type": "SNAP_ADS","targeting": {"regulated_content": false,"geos": [{"country_code": "uk"}],"devices": [{"os_type": "ANDROID"}],"auto_expansion_options":{"interest_expansion_option":{"enabled": true},"custom_audience_expansion_option":{"enabled": true}}},"placement_v2": {"config": "AUTOMATIC"},"bid_micro": 1000000,"bid_strategy": "TARGET_COST","daily_budget_micro": 50000000,"start_time": "2021-01-30T23:43:45.000Z","end_time": "2021-02-08T07:59:59.000Z","optimization_goal": "APP_INSTALLS","event_sources": {"MOBILE_APP": ["9b5b83ec-c593-4a64-9c6d-a0eb9da0edb9"]}}]}'
  https://adsapi.snapchat.com/v1/campaigns/4813d068-370b-45f6-a8d6-e01de878f1b5/adsquads

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "60118f4f00ff026a940c321500ff0001737e616473617069736300016275696c642d65386534326330362d312d3431372d3000010143",
    "adsquads": [
        {
            "sub_request_status": "SUCCESS",
            "adsquad": {
                "id": "9077bb86-fb9a-4ded-9da9-67bc2e1dd6c5",
                "updated_at": "2021-01-27T16:05:35.770Z",
                "created_at": "2021-01-27T16:03:14.293Z",
                "name": "Badger Supplies Ad Squad - event sources",
                "status": "ACTIVE",
                "campaign_id": "4813d068-370b-45f6-a8d6-e01de878f1b5",
                "type": "SNAP_ADS",
                "targeting": {
                    "regulated_content": false,
                    "geos": [
                        {
                            "country_code": "uk"
                        }
                    ],
                    "devices": [
                        {
                            "os_type": "ANDROID"
                        }
                    ],
                    "auto_expansion_options":
                    {
                        "interest_expansion_option":
                        {
                            "enabled": true
                    },
                        "custom_audience_expansion_option":
                        {
                            "enabled": true
                        }
                    }
                },
                "targeting_reach_status": "VALID",
                "placement_v2": {
                    "config": "AUTOMATIC"
                },
                "billing_event": "IMPRESSION",
                "bid_micro": 1000000,
                "auto_bid": false,
                "target_bid": true,
                "bid_strategy": "TARGET_COST",
                "daily_budget_micro": 50000000,
                "start_time": "2021-01-30T23:43:45.000Z",
                "end_time": "2021-02-08T07:59:59.000Z",
                "optimization_goal": "APP_INSTALLS",
                "event_sources": {
                    "MOBILE_APP": [
                        "9b5b83ec-c593-4a64-9c6d-a0eb9da0edb9"
                    ]
                },
                "delivery_constraint": "DAILY_BUDGET",
                "pacing_type": "STANDARD",
                "creation_state": "PUBLISHED"
            }
        }
    ]
}

On the 20th of March 2020 we announced the deprecation of the attributes auto_bid and target_bid, please ensure that you have switched to using only bid_strategy by the 20th of June 2020. Creation of AdSquads and updating of AdSquads should only use the bid_strategy attribute.

The API will return the attributes auto_bid/target_bid when requesting the AdSquad entity but these attributes should be stripped out for any update AdSquad requests you make or the API will reject your requests come the 20th June 2020.

The below table outlines the relationship between the old bid settings and bid_strategy.

auto_bid target_bid bid_micro bid_strategy
true false —– AUTO_BID
false false used for bid LOWEST_COST_WITH_MAX_BID
false true used for bid TARGET_COST

The bid_strategy attribute defines the bid strategy used for the Ad Squad, bid_strategy is an enumeration field which should be set to the bidding strategy of your choice, given the below options.

bid_strategy Description Additional Settings
AUTO_BID Drive the most efficient cost per action while spending your budget —–
LOWEST_COST_WITH_MAX_BID Bids conservatively at or below your desired bid use bid_micro to set bid
MIN_ROAS** Achieves the most purchase value while maintaining a minimum return on your ad spend, this strategy requires that that APP_PURCHASE event along with the price parameter has been implemented use roas_value_micro to set minimum ROAS in micro currency, one full unit of a currency in roas_value_micro represents a ROAS of 1, roas_value_micro value can be set between 10000 and a maximum of 100000000.
TARGET_COST Achieves the most volume while aiming to keep your average cost per action below your target cost use bid_micro to set bid

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

Optimization Goals allowed per Bid Strategy.

bid_strategy Optimization goals
AUTO_BID APP_INSTALLS, IMPRESSIONS, STORY_OPENS, SWIPES, USES, VIDEO_VIEWS, 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
LOWEST_COST_WITH_MAX_BID No restrictions
MIN_ROAS APP_PURCHASE
TARGET_COST APP_INSTALLS, SWIPES, USES, VIDEO_VIEWS_15_SEC, PIXEL_PURCHASE, PIXEL_SIGNUP, PIXEL_PAGE_VIEW, PIXEL_ADD_TO_CART, APP_PURCHASE, APP_SIGNUP, APP_ADD_TO_CART, APP_REENGAGE_PURCHASE, APP_REENGAGE_OPEN, STORY_OPENS

MIN_ROAS examples

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

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

Examples using “bid_strategy”:“MIN_ROAS”;

Placement V2

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

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

The below table outlines the relationship between placement and placement_v2.

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

Placement V2 Specification

Attribute Description Required Possible Values
config Configuration for placement R AUTOMATIC, CUSTOM
platforms The platform to place the ads O SNAPCHAT
snapchat_positions List of possible placement positions INTERSTITIAL_USER, INTERSTITIAL_CONTENT, INTERSTITIAL_SPOTLIGHT, INSTREAM, PUBLIC_STORIES_INSTREAM, FEED, 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, none of the other properties in placement_v2 can 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

Position Description
INTERSTITIAL_USER. Ads run between friends stories.
INTERSTITIAL_CONTENT. Ads run before and after stories in publisher and our stories.
INTERSTITIAL_SPOTLIGHT* Ads run before and after public Snaps from the community.
INSTREAM Ads run inside i.e. in between stories in publisher and our stories.
PUBLIC_STORIES_INSTREAM Ads run within public stories.
FEED Story Ads run alongside Publisher and Creator content in the Stories tab.
CAMERA Ads run in the Lens carousel.

* The INTERSTITIAL_SPOTLIGHT placement cannot be targeted on it’s own, it needs to be combined with other placements

snapchat_positions Ad Squad type / Ad type

This table outlines the Ad Squad and Ad availability per placement position.

Position Ad Squad Type Ad Type
INTERSTITIAL_USER SNAP_ADS SNAP_AD, AD_TO_CALL, AD_TO_LENS, AD_TO_MESSAGE, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE, STORY*
INTERSTITIAL_CONTENT SNAP_ADS SNAP_AD, AD_TO_CALL, AD_TO_LENS, AD_TO_MESSAGE, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE, STORY*
INTERSTITIAL_SPOTLIGHT*** SNAP_ADS SNAP_AD, AD_TO_CALL, AD_TO_MESSAGE, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE, STORY*
INSTREAM SNAP_ADS AD_TO_CALL, AD_TO_LENS, AD_TO_MESSAGE, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE, SNAP_AD, STORY
PUBLIC_STORIES_INSTREAM SNAP_ADS AD_TO_CALL, AD_TO_LENS, AD_TO_MESSAGE, APP_INSTALL, COLLECTION, DEEP_LINK, LEAD_GENERATION, REMOTE_WEBPAGE, SNAP_AD, STORY
FEED SNAP_ADS STORY**
CAMERA LENS LENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK

* Story Ads using the INTERSTITIAL_USER, INTERSTITIAL_CONTENT, INTERSTITIAL_SPOTLIGHT placements are not required to have a Preview Creative
** Story Ads using the FEED placement are required to have a Preview Creative
*** Ads serving in the INTERSTITIAL_SPOTLIGHT placement are required to have the Top Snap Media type VIDEO (IMAGE media is not allowed), Dynamic Ads are not allowed in the INTERSTITIAL_SPOTLIGHT placement

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

Story Ad running in the Stories tab

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

Example 7

Story Ad running in the Stories tab, between User stories and between Curated content

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

Example 8

Lens Ad placed in the Camera

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

Example 9

Story Ad running in the Stories tab and placed in between public Snaps from the community.

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

Pacing Types

Validations

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

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

Squad Optimization Goals

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

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

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

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

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

Squad Optimization Goal Per Ad Type

This table outlines the Optimization Goals availability per Ad Type.

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

Delivery Optimization Windows

The conversion_window attribute specifies the delivery optimisation window to be used for the Ad Squad, further information on the delivery optimization window can be found in our Business Help Centre.

Optimization Goal Ad Types Description
All Optimization Goals SWIPE_28DAY_VIEW_1DAY (default) This is the default delivery optimization for all optimization goals, it can be left out on creation
PIXEL_PURCHASE SWIPE_7DAY This delivery optimization window will unlock for Ad Accounts that has accrued a certain amount of PIXEL_PURCHASE conversions

Delivery Optimisation window example

Using conversion_window with PIXEL_PURCHASE

Example - Using PIXEL_PURCHASE optimization goal with SWIPE_7DAY

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"adsquads":[{"campaign_id":"91a5edee-a6cf-42e7-8317-a310e0f65a54","name":"7 Day click delivery optimization","type":"SNAP_ADS","placement":"SNAP_ADS","optimization_goal":"PIXEL_PURCHASE","conversion_window":"SWIPE_7DAY","pixel_id":"5eda10b7-a5fe-4ac6-80f4-417e68d748fb","bid_micro":10000,"daily_budget_micro":50000000,"targeting":{"regulated_content":false,"demographics":[{"min_age":"18","gender":"FEMALE"}],"geos":[{"country_code":"us"}]},"delivery_constraint":"DAILY_BUDGET","start_time":"2021-07-13T21:12:45Z","status":"ACTIVE"}]}'
  https://adsapi.snapchat.com/v1/campaigns/91a5edee-a6cf-42e7-8317-a310e0f65a54/adsquads

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "25356d15-e8b1-4757-9a93-92fda600f861",
    "adsquads": [
        {
            "sub_request_status": "SUCCESS",
            "adsquad": {
                "id": "544b400a-c13e-4733-bfed-62aba316156b",
                "updated_at": "2023-07-21T17:39:36.611Z",
                "created_at": "2023-07-21T17:39:36.611Z",
                "effective_status": "ACTIVE",
                "name": "7 Day click delivery optimization",
                "status": "ACTIVE",
                "campaign_id": "91a5edee-a6cf-42e7-8317-a310e0f65a54",
                "type": "SNAP_ADS",
                "targeting": {
                    "regulated_content": false,
                    "demographics": [
                        {
                            "min_age": "18",
                            "gender": "FEMALE"
                        }
                    ],
                    "geos": [
                        {
                            "country_code": "us"
                        }
                    ],
                    "enable_targeting_expansion": true,
                    "auto_expansion_options": {
                        "interest_expansion_option": {
                            "enabled": true
                        },
                        "custom_audience_expansion_option": {
                            "enabled": true
                        }
                    }
                },
                "targeting_reach_status": "VALID",
                "placement": "SNAP_ADS",
                "billing_event": "IMPRESSION",
                "bid_micro": 10000,
                "auto_bid": false,
                "target_bid": false,
                "bid_strategy": "LOWEST_COST_WITH_MAX_BID",
                "daily_budget_micro": 50000000,
                "start_time": "2021-07-13T21:12:45.000Z",
                "optimization_goal": "PIXEL_PURCHASE",
                "conversion_window": "SWIPE_7DAY",
                "pixel_id": "5eda10b7-a5fe-4ac6-80f4-417e68d748fb",
                "delivery_constraint": "DAILY_BUDGET",
                "pacing_type": "STANDARD",
                "creation_state": "PUBLISHED",
                "delivery_status": [
                    "INVALID_EFFECTIVE_INVALID"
                ],
                "skadnetwork_properties": {
                    "status": "NEVER_ENROLLED"
                }
            }
        }
    ]
}

Creating an Ad Squad using the optimisation goal PIXEL_PURCHASE in combination with the delivery window SWIPE_7DAY , optimising delivery towards users that will click on the ad and convert within 7 days.

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.

Ad Squads that are delivering ads of multiple formats do not support frequency capping using the cap_and_exclusion_config if they are inside of Auction campaigns.

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

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

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
start_time O *
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

*start_time only updatable when date is in the future, the start_time of running Ad Squads cannot be updated

Targeting specs can now be updated regardless of whether the Ad Squad is live or paused. Updating the targeting of an Ad Squad will push the ads back into review and for live Ad Squads the delivery will be paused momentarily while the ads are re-reviewed and will resume once the ads are approved.

The field country within geos cannot be updated if the AdSquad is live.

HTTP Request

PUT https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads

Parameters

Parameter Default Description
campaign_id Campaign ID

Get All Ad Squads under a Campaign

curl "https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads?return_placement_v2=true" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b00b1500ff0476bcfb96faa20001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010b",
  "adsquads": [
    {
      "sub_request_status": "success",
      "adsquad": {
        "id": "0633e159-0f41-4675-a0ba-224fbd70ac4d",
        "updated_at": "2016-08-14T05:52:45.186Z",
        "created_at": "2016-08-14T05:52:45.186Z",
        "name": "Ad Squad Apples",
        "status": "PAUSED",
        "campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
        "type": "SNAP_ADS",
        "targeting": {
          "geos": [
            {
              "country_code": "us"
            }
          ]
        },
        "placement_v2": {
            "config": "AUTOMATIC"
        },
        "billing_event": "IMPRESSION",
        "auto_bid": true,
        "target_bid": false,
        "bid_strategy": "AUTO_BID",
        "daily_budget_micro": 1000000000,
        "start_time": "2016-08-11T22:03:58.869Z",
        "optimization_goal": "IMPRESSIONS"
      }
    },
    {
      "sub_request_status": "success",
      "adsquad": {
        "id": "23995202-bfbc-45a0-9702-dd6841af52fe",
        "updated_at": "2016-08-14T05:58:55.409Z",
        "created_at": "2016-08-14T05:58:55.409Z",
        "name": "Ad Squad Uno",
        "status": "ACTIVE",
        "campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
        "type": "SNAP_ADS",
        "targeting": {
          "geos": [
            {
              "country_code": "us"
            }
          ]
        },
        "placement_v2": {
            "config": "AUTOMATIC"
        },
        "billing_event": "IMPRESSION",
        "bid_micro": 1000000,
        "auto_bid": false,
        "target_bid": true,
        "bid_strategy": "TARGET_COST",
        "daily_budget_micro": 1000000000,
        "start_time": "2016-08-11T22:03:58.869Z",
        "optimization_goal": "IMPRESSIONS"
      }
    }
  ]
}

This endpoint retrieves all ad squads within a specified campaign.

HTTP Request

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

Parameters

Parameter Default Description
campaign_id Campaign ID
return_placement_v2 true optional parameter for retrieving placement_v2 attribute

Get All Ad Squads under an Ad Account

curl "https://adsapi.snapchat.com/v1/adaccounts/8cf88872-048b-4447-95d1-eb48231788be/adsquads?return_placement_v2=true" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b00b1500ff0476bcfb96faa20001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010b",
  "adsquads": [
    {
      "sub_request_status": "success",
      "adsquad": {
        "id": "0633e159-0f41-4675-a0ba-224fbd70ac4d",
        "updated_at": "2016-08-14T05:52:45.186Z",
        "created_at": "2016-08-14T05:52:45.186Z",
        "name": "Ad Squad Apples",
        "status": "PAUSED",
        "campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
        "type": "SNAP_ADS",
        "targeting": {
          "geos": [
            {
              "country_code": "us"
            }
          ]
        },
        "placement_v2": {
            "config": "AUTOMATIC"
        },
        "billing_event": "IMPRESSION",
        "auto_bid": true,
        "target_bid": false,
        "bid_strategy": "AUTO_BID",
        "daily_budget_micro": 1000000000,
        "start_time": "2016-08-11T22:03:58.869Z",
        "optimization_goal": "IMPRESSIONS"
      }
    },
    {
      "sub_request_status": "success",
      "adsquad": {
        "id": "23995202-bfbc-45a0-9702-dd6841af52fe",
        "updated_at": "2016-08-14T05:58:55.409Z",
        "created_at": "2016-08-14T05:58:55.409Z",
        "name": "Ad Squad Uno",
        "status": "ACTIVE",
        "campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
        "type": "SNAP_ADS",
        "targeting": {
          "geos": [
            {
              "country_code": "us"
            }
          ]
        },
        "placement_v2": {
            "config": "AUTOMATIC"
        },
        "billing_event": "IMPRESSION",
        "bid_micro": 1000000,
        "auto_bid": false,
        "target_bid": true,
        "bid_strategy": "TARGET_COST",
        "daily_budget_micro": 1000000000,
        "start_time": "2016-08-11T22:03:58.869Z",
        "optimization_goal": "IMPRESSIONS"
      }
    }
  ]
}

This endpoint retrieves all ad squads within a specified ad account.

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID
return_placement_v2 true optional parameter for retrieving placement_v2 attribute
read_deleted_entities true optional parameter, this param will return the deleted attribute on deleted Ad Squad entities

Get a Specific Ad Squad

curl "https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe?return_placement_v2=true" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b00bd200ff0a1092e59e2ec90001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
  "adsquads": [
    {
      "sub_request_status": "success",
      "adsquad": {
        "id": "23995202-bfbc-45a0-9702-dd6841af52fe",
        "updated_at": "2016-08-14T05:58:55.409Z",
        "created_at": "2016-08-14T05:58:55.409Z",
        "name": "Ad Squad Uno",
        "status": "ACTIVE",
        "campaign_id": "6cf25572-048b-4447-95d1-eb48231751be",
        "type": "SNAP_ADS",
        "targeting": {
          "geos": [
            {
              "country_code": "us"
            }
          ]
        },
        "placement_v2": {
            "config": "AUTOMATIC"
        },
        "billing_event": "IMPRESSION",
        "bid_micro": 1000000,
        "auto_bid": false,
        "target_bid": true,
        "bid_strategy": "TARGET_COST",
        "daily_budget_micro": 1000000000,
        "start_time": "2016-08-11T22:03:58.869Z",
        "optimization_goal": "IMPRESSIONS"
      }
    }
  ]
}

This endpoint retrieves a specific ad squad.

HTTP Request

GET https://adsapi.snapchat.com/v1/adsquads/{ad_squad_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
read_deleted_entities true optional parameter, this param will return the deleted attribute on deleted Ad Squad entities

Delete an Ad Squad

curl -X DELETE "https://adsapi.snapchat.com/v1/adsquads/0633e159-0f41-4675-a0ba-224fbd70ac4d" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b00c6a00ff068aea0cfe17bd0001737e616473617069736300016275696c642d35396264653638322d312d31312d3700010109",
  "adsquads": []
}

This endpoint deletes a specific ad squad.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the adsquad to delete

Ads

Ad is a light weight entity that contains all the information needed to display the ad. It also contains a third party measurement URL if needed.

Attributes

Attribute Description Required Possible Values
ad_squad_id Ad Squad ID R
creative_id Creative ID R
name Ad name R max length: 375 characters
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_reasons 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, 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, COLLECTION, LEAD_GENERATION
delivery_status Delivery status Read-only See Delivery status
deleted Indicates whether the entity has been deleted or not, only shown when using the parameter read_deleted_entities Read-only true

Ad Type <-> Creative Type Mapping

Ad Type Allowed Creative Type
APP_INSTALL APP_INSTALL
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
LENS LENS
LENS_REMOTE_WEBPAGE LENS_WEB_VIEW
LENS_APP_INSTALL LENS_APP_INSTALL
LENS_DEEP_LINK LENS_DEEP_LINK
COLLECTION COLLECTION
LEAD_GENERATION LEAD_GENERATION

Create an Ad

curl -X POST \
  -d '{"ads":[{"ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe", "creative_id":"c1e6e929-acec-466f-b023-852b8cacc18f", "name": "Ad One", "type": "SNAP_AD", "status": "PAUSED"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads

The above command returns JSON structured like this:

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

This endpoint creates an Ad within an Ad Squad.

HTTP Request

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

Parameters

Parameter Default Description
ad_squad_id Ad Squad ID

Update an Ad

curl -X PUT \
  -d '{"ads":[{"id": "e8d6217f-32ab-400f-9e54-39a86a7963e4", "ad_squad_id": "23995202-bfbc-45a0-9702-dd6841af52fe", "creative_id":"c1e6e929-acec-466f-b023-852b8cacc18f", "name": "Ad One", "type": "SNAP_AD", "status": "ACTIVE"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/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 updates an Ad.

Attributes that can be updated

Attribute Description Required Possible Values
name Ad name R
status Ad status R ACTIVE, PAUSED
on_swipe_tracking_urls Third-party swipe-up tags O
third_party_tracking_urls Third-party impression tags O

HTTP Request

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

Parameters

Parameter Default Description
ad_squad_id Ad Squad ID

Get All Ads under an Ad Squad

curl "https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/ads" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

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

This endpoint retrieves all ads within a specified ad squad.

HTTP Request

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

Parameters

Parameter Default Description
ad_squad_id Ad Squad ID

Get All Ads under a Campaign

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

The above command returns JSON structured like this:

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

This endpoint retrieves all Ads under a specified Campaign.

HTTP Request

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

Parameters

Parameter Default Description
campaign_id Campaign ID

Get All Ads under an Ad Account

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

The above command returns JSON structured like this:

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

This endpoint retrieves all Ads under a specified Ad account.

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID
read_deleted_entities true optional parameter, this param will return the deleted attribute on deleted Ad entities

Get a Specific Ad

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

The above command returns JSON structured like this:

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

This endpoint retrieves a specific ad.

HTTP Request

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

URL Parameters

Parameter Default Description
ad_id Ad ID
read_deleted_entities true optional parameter, this param will return the deleted attribute on deleted Ad entities

Delete an Ad

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

The above command returns JSON structured like this:

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

This endpoint deletes a specific ad.

HTTP Request

DELETE https://adsapi.snapchat.com/v1/ads/{ad_id}

URL Parameters

Parameter Description
ID The ID of the ad to delete

Third-Party Tracking Tags

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

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

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

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

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

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

The above command returns JSON structured like this:

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

Additional Ad Attributes

Attribute Description Required
third_party_on_swipe_tracking_urls Third-party swipe tags, executed on swipe of attachment O
third_party_paid_impression_tracking_urls Third-party impression tags, executed on ad impression O
on_swipe_tracking_urls DEPRECATED, Use attribute third_party_on_swipe_tracking_urls -
third_party_tracking_urls DEPRECATED, Use attribute third_party_paid_impression_tracking_urls -

Approved Third Party Tracking URL domains

URL Description
secure-gl.imrworldwide.com
ad.doubleclick.net
pixel.adsafeprotected.com
sn.moatads.com DEPRECATED, Use AdSquad level tracking activation

How to get tags

Notes

URL Macros

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

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

Media

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

Attributes

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

Create Media

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

The above command returns JSON structured like this:

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

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Upload Media - Video

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

Parameters

Parameter Default Description
media_id Media ID

Upload Media - Image

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

Name Description Dimensions File size File type
Top Snap Image Used as Top Snap in Snap Ads, IMAGE type top snaps are converted into 5 sec videos and rendered on the client as videos, Top Snap specs min 1080 x 1920 px 5 MB max size PNG, JPG
App Icon (Snap Ads) Icon used for Snap Ad with App Install attachment or Deep Link attachment, 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
App Icon (Lens) Icon used specifically for the Lens Creatives LENS_APP_INSTALL and LENS_DEEP_LINK, image shouldn’t have any borders or padding 256 x 256 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

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

curl "https://adsapi.snapchat.com/v1/media/a7bee653-1865-41cf-8cee-8ab85a205837" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

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

This endpoint retrieves a specific media entity.

HTTP Request

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

URL Parameters

Parameter Description
ID The ID of the media to retrieve

Get Preview for a Specific Media

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

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

Get Thumbnail for a Specific Media

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

The above command returns JSON structured like this:

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

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

HTTP Request

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

URL Parameters

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

Creatives

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

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

Attributes

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
brand_name Brand Name R max length: 32 characters
call_to_action Call to Action O Please refer to the Creative type to CTA mapping table
headline Headline (displayed under brand name) R max length: 34 characters
shareable Allow Users to Share with Friends O true (default), false
name Creative name R max length: 375 characters
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, WEB_VIEW, DEEP_LINK, AD_TO_LENS, AD_TO_CALL, AD_TO_MESSAGE, PREVIEW, COMPOSITE, LENS, LENS_WEB_VIEW, LENS_APP_INSTALL, LENS_DEEP_LINK, COLLECTION, LEAD_GENERATION
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)
ad_product Type of Ad Product Required only for R&F creatives SNAP_AD (default), LENS, FILTER
profile_properties Contains the profile ID to be associated with the creative R { profile_id: 72cf5c50-8343-48d3-a0a7-3ed45b75faaa }

** 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, 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 See section on Lens creatives for specs and references

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

Creative Type to Call To Actions Mapping

Creative type Call To Actions
APP_INSTALL BOOK_NOW, DONATE, DOWNLOAD, GET_NOW, INSTALL_NOW, ORDER_NOW, PLAY, SHOP_NOW, SIGN_UP, TRY, USE_APP, WATCH, VOTE, DIRECTIONS, PLAY_GAME
LENS_APP_INSTALL BOOK_NOW, DONATE, DOWNLOAD, GET_NOW, INSTALL_NOW, ORDER_NOW, PLAY, SHOP_NOW, SIGN_UP, TRY, USE_APP, WATCH, PLAY_GAME
DEEP_LINK DONATE, PLAY, SHOP_NOW, SIGN_UP, USE_APP, MORE, OPEN_APP, TRY, WATCH, VIEW_PROFILE, VOTE, DIRECTIONS, PRE_REGISTER, PLAY_GAME, DOWNLOAD
LEAD_GENERATION APPLY_NOW, MORE, BOOK_NOW, GET_NOW, SIGN_UP, TEST_DRIVE, REQUEST_APPOINTMENT, REQUEST_QUOTE, FREE_TRIAL, CLAIM_SAMPLE, GET_COUPON
LENS_DEEP_LINK DONATE, PLAY, SHOP_NOW, SIGN_UP, USE_APP, MORE, OPEN_APP, TRY, WATCH, VIEW_PROFILE, VOTE, DIRECTIONS, VIEW_MENU, PRE_REGISTER, PLAY_GAME
WEB_VIEW APPLY_NOW, MORE, ORDER_NOW, PLAY, READ, SHOP_NOW, SHOW, SIGN_UP, VIEW, SHOW, WATCH, DONATE, DOWNLOAD, APPLY_NOW, ORDER_NOW, RESPOND, BUY_TICKETS, SHOWTIMES, BOOK_NOW, GET_NOW, LISTEN, TRY, VOTE, VIEW_MENU, PRE_REGISTER, PLAY_GAME
LENS_WEB_VIEW APPLY_NOW, MORE, ORDER_NOW, PLAY, READ, SHOP_NOW, SHOW, SIGN_UP, VIEW, SHOW, WATCH, DONATE, DOWNLOAD, APPLY_NOW, ORDER_NOW, RESPOND, BUY_TICKETS, SHOWTIMES, BOOK_NOW, GET_NOW, LISTEN, TRY, VOTE, DIRECTIONS, VIEW_MENU, PRE_REGISTER, PLAY_GAME
AD_TO_LENS PLAY, TRY, SHOP_NOW, VOTE
AD_TO_MESSAGE MESSAGE_NOW, OPEN_APP
AD_TO_CALL CALL_NOW, OPEN_APP
AD_TO_PLACE SEE_PLACE, DIRECTIONS, VIEW_MENU

Attachments

Name Creative type Description
Lead Generation attachment LEAD_GENERATION Creative requires lead_generation_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 32 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 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 32 characters max
call_to_action Call to Action O Please refer to the Creative type to CTA mapping table
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 30 characters max
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
product_page_id Custom product page ID from iOS App Store. Only set when using a Custom Product Page O 45812c9b-c296-43d3-c6a0-c5a02f74bf6e

Icon Media specifications

Mobile Measurement Partners - Setup Details

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

The above command returns JSON structured like this:

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

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Create a Snap Ad with Web View attachment

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

Attributes

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
brand_name Brand Name R 32 characters max
call_to_action Call to Action O Please refer to the Creative type to CTA mapping table
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 The following macros are supported:
  • {{campaign.name}}
  • {{campaign.id}}
  • {{adSet.name}}
  • {{adSet.id}}
  • {{ad.id}}
  • {{creative.name}}
  • {{creative.headline}}
  • {{site_source_name}}
max length: 2048 characters
block_preload Block Snapchat from preloading the web page O true/false (default)
curl -X POST \
  -d '{"creatives": [{"ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74", "top_snap_media_id": "a7bee653-1865-41cf-8cee-8ab85a205837", "name": "Creative WV", "type": "WEB_VIEW", "shareable": true, "call_to_action": "VIEW", "web_view_properties": {"url": "http://snapchat.com/ads"}}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/creatives

The above command returns JSON structured like this:

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

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

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

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

Attributes

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
brand_name Brand Name R 32 characters max
call_to_action Call to Action O Please refer to the Creative type to CTA mapping table
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 Possible Values
deep_link_uri Deep Link URL R
app_name App name R 30 characters max
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 APP_INSTALL (default), WEB_SITE
web_view_fallback_url Fallback web url to be used O
product_page_id Custom product page ID from iOS App Store. Only set when using a Custom Product Page O

Icon Media specifications

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

The above command returns JSON structured like this:

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

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Create a Snap Ad with Lens attachment

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

Attributes

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
brand_name Brand Name R 32 characters max
call_to_action Call to Action O Please refer to the Creative type to CTA mapping table
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.

This type of Ad is currently only available in the United States, France, Qatar, Saudi Arabia, Egypt, Kuwait and the United Arab Emirates.

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 32 characters max
call_to_action Call to Action O Please refer to the Creative type to CTA mapping table
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 32 characters max
call_to_action Call to Action O Please refer to the Creative type to CTA mapping table
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

The Story Ad Creative comes in two different variants, the full variant includes a Preview Creative and a Composite Creative, this type of Story Ad can run in the Stories Tab and also in between User stories and Curated stories.

The second variant of the Story Ad Creative uses only a Composite Creative, this type of Story Ad Creative can only run between User stories and Curated stories.

The Preview Creative is used to display the thumbnail within the Stories tab of the app, the Composite Creative is used to define the individual Snap Ads that make up the story. When the Story Ad runs in between User stories and Curated stories the Preview Creative is not used.

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 and DEEP_LINK are supported

Composite creation guidelines - Story Ad Creatives use 1-20 individual 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, "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,
                "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
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",
                        "deep_link_urls": [],
                        "block_preload": false
                    }
                }
            }
        }
    ]
}

Update a Creative

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",
            "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,
        "profile_properties":
        {
            "profile_id": "62cf5c50-8343-48d3-a0a7-3ed45b75fa10"
        }
    }]
}' \
  -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",
                    "deep_link_urls": [],
                    "block_preload": true
                },
                "ad_product": "SNAP_AD",
                "profile_properties":
                {
                    "profile_id": "62cf5c50-8343-48d3-a0a7-3ed45b75fa10"
                }
            }
        }
    ]
}

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
block_preload R
app_install_properties Required
app_name R
ios_app_id R
android_app_url R
icon_media_id R
product_page_id O
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
product_page_id O
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

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

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/{creative_id}

URL Parameters

Parameter Description
creative_id The ID of the creative to retrieve

Get Snapcode preview for a Creative

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

The above command returns JSON structured like this:

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

This endpoint generates a snapcode preview for a specific creative, the lifetime of the snapcode is 7 days. The attribute expires_at defines the time that the snapcode will stop functioning.

HTTP Request

GET https://adsapi.snapchat.com/v1/creatives/{creative_id}/snapcode

URL Parameters

Parameter Description
creative_id The ID of the creative to retrieve

Associate Public Profiles with Creatives

To associate Public Profiles you can include the profile_properties property to the creative during create or update. Then use the Sharing Policies API on the Business API to list all shared Public Profiles for an ad account or external organization.

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  'https://adsapi.snapchat.com/v1/adaccounts/12325ba6-7559-4000-9663-bace8adff5f2/creatives' \
  -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",
            "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,
          "profile_properties":
          {
            "profile_id": "62cf5c50-8343-48d3-a0a7-3ed45b75fa10"
          }
        }]
    }'

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",
                "deep_link_urls": [],
                "block_preload": true
            },
            "ad_product": "SNAP_AD",
            "profile_properties":
            {
                "profile_id": "62cf5c50-8343-48d3-a0a7-3ed45b75fa10"
            }
        }
    }]
}

HTTP Request

You can associate a profile during create or update

POST/PUT https://adsapi.snapchat.com/v1/creatives/{creative_id}/snapcode

URL Parameters

Parameter Description
creative_id The ID of the creative to retrieve

HTTP Request

You can associate a profile during create or update

POST/PUT https://adsapi.snapchat.com/v1/creatives/{creative_id}/snapcode

URL Parameters

Parameter Description
creative_id The ID of the creative to retrieve

HTTP Request

You can associate a profile during create or update

POST/PUT https://adsapi.snapchat.com/v1/creatives/{creative_id}/snapcode

URL Parameters

Parameter Description
creative_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 it will automatically run as a commercial within that content.

Commercials can currently target the following countries: AE, AU, AT, BH, CA, CH, DE, DK, FR, IQ, IE, JO, KW, NL, NZ, NO, OM, QA, SA, SE, UK, US.

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 and AR Lens.

Creative attribute Value
type AD_TO_LENS, 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, 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, SNAP_AD, WEB_VIEW FULL_DURATION The full length of the video will be unskippable
7 seconds or longer AD_TO_LENS, 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 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: ae, au, at, bh, ca, ch, de, dk, fr, iq, ie, jo, kw, nl, nz, no, om, qa, sa, se, uk, us.

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

placement_v2 attribute Value
config CUSTOM
platforms SNAPCHAT
snapchat_positions INSTREAM
inclusion premium_content_bundle_ids

Premium Content Bundles

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

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 geo targeting country_code attribute is restricted to the following countries: ae, au, at, bh, ca, ch, de, dk, fr, iq, ie, jo, kw, nl, nz, no, om, qa, sa, se, uk, us

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
product_page_id Custom product page ID from iOS App Store. Only set when using a Custom Product Page O

Create a Creative Element

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

The above command returns JSON structured like this:

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

Create Multiple Creative Elements

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

The above command returns JSON structured like this:

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

Create an Interaction Zone

Attributes

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
name Creative Element name R
headline Headline for the interaction zone R Same as all allowed call_to_action values for Web View Creative
creative_elements Array of Creative Element IDs R Must have at least 4 creative elements.
curl -X POST  \
  -d '{"interaction_zones": [{"name": "First Interaction Zone", "creative_element_ids": ["d28427e5-0604-406c-8f23-167b211a3317","dc80a56f-800c-499b-846b-78e74bd39a9d","75a98c65-1e62-4507-97fe-50cbc523523a","faefe7cd-567d-4647-bb1d-b918fb0ac98a", "f63bb5f5-471c-404f-8f0d-e5c1a003e4d9"], "headline":"MORE"}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/8adc3db7-8148-4fbf-999c-8d2266369d74/interaction_zones

The above command returns JSON structured like this:

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

Targeting

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

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

Targeting Spec

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

Attribute Description Required Note
app_install_states Defines whether targeted user has App installed or not O For usage see App Install states
demographics List of Demographic Targets O Required when using Multi-country targeting
devices List of Device Targets O
geos List of Geo/Location Targets R Multi-country targeting is allowed from 1st April 2020, each country needs to be placed in a geos entry, a targeting spec that uses multi-country targeting needs to also include a demographics entry that incorporates a single languages entry
interests List of Interest Targets O
locations List of Location categories/Circles O
regulated_content Flag to mark content within the Ad Squad as Regulated Content O FALSE (default), TRUE
segments List of Customer List segment targets O
auto_expansion_options This option allows Snapchat to expand the targeting based on selected interest targeting and/or selected custom audiences, by default both of these options are enabled on creation O For usage see Targeting auto-expansion

General Guidance

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

Targeting Inclusion / Exclusion

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

Targeting auto-expansion

The auto_expansion_options object contains two attribures that will expand the targeting of the Ad Squad based on similar qualities and characteristics used in the existing targeting. These two attributes are both enabled by default on creation of the Ad Squad.

Ad Squads that form part of a Campaign advertising Housing, Credit or Employment, should always have auto-expansion disabled.

Name Description Possible Values
interest_expansion_option.enabled Expands targeting based on interest targeting true (default),false
custom_audience_expansion_option.enabled Expands targeting based on selected custom audiences true (default),false

Targeting auto-expansion usage examples

Example 1

Example 1 - Expand targeting based both on interest and custom audiences:

"auto_expansion_options":
  {
    "interest_expansion_option":
      {
        "enabled": true
      },
    "custom_audience_expansion_option":
      {
        "enabled": true
      }
  }

This configuration will expand the targeting based both on interest and custom audiences.

Example 2

Example 2 - Expand targeting based on interest targeting only:

"auto_expansion_options":
  {
    "interest_expansion_option":
      {
        "enabled": true
      },
    "custom_audience_expansion_option":
      {
        "enabled": false
      }
  }

This configuration will expand the targeting based on interest targeting only.

Example 3 - Housing, Credit or Employment

Example 3 - Do not expand targeting:

"auto_expansion_options":
  {
    "interest_expansion_option":
      {
        "enabled": false
      },
    "custom_audience_expansion_option":
      {
        "enabled": false
      }
  }

No targeting expansion, this configuration should be used for Campaigns advertising Housing, Credit or Employment.

App Install states

App Install states targeting can be used with the Creative types APP_INSTALL and DEEP_LINK and allows you to target a user given the user’s install state for a specific App that you own. Using App Install state targeting comes with two prerequisites:

App Install state targeting can be applied in two different scenarios:

App Install state / Optimization Goals

Ad type Install state Optimization goals Description
APP_INSTALL NOT_INSTALLED IMPRESSIONS, SWIPES, APP_INSTALL, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGNUP Targets users that don’t have the app installed
DEEP_LINK INSTALLED IMPRESSIONS, SWIPES, APP_REENGAGE_OPEN, APP_REENGAGE_PURCHASE Targets users that have the app installed
DEEP_LINK NOT_INSTALLED IMPRESSIONS, SWIPES, APP_INSTALLS, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGN_UP Targets users that don’t have the app installed
DEEP_LINK ALL IMPRESSIONS, SWIPES All users targeted

App Install state / Product Audience

Ad type Product Audience Install state Optimization goals
APP_INSTALL Prospecting NOT_INSTALLED IMPRESSIONS, SWIPES, APP_INSTALL, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGNUP
DEEP_LINK Retargeting INSTALLED IMPRESSIONS, SWIPES, APP_REENGAGE_OPEN, APP_REENGAGE_PURCHASE
DEEP_LINK Prospecting NOT_INSTALLED IMPRESSIONS, SWIPES, APP_INSTALLS, APP_PURCHASE, APP_ADD_TO_CART, APP_SIGN_UP
DEEP_LINK Prospecting ALL IMPRESSIONS, SWIPES

Targeting Dimensions

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

Targeting Type Support by Country

curl "https://adsapi.snapchat.com/v1/targeting/v1/options?country_code=us" \
  -H "Authorization: Bearer  meowmeowmeow"

The above command returns JSON structured like this:

 {
  "request_status": "SUCCESS",
  "request_id": "86fd4602-89cd-46d4-a843-05d45dab484f",
  "targeting_option": {
    "snap_ads": [
            "demographics:advanced_demographics",
            "demographics:age_groups",
            "demographics:age_min_max",
            "demographics:gender",
            "demographics:languages",
            "devices:carrier",
            "devices:connection_type",
            "devices:marketing_name",
            "devices:os_type",
            "geos:country",
            "geos:electoral",
            "geos:metro",
            "geos:postal_code",
            "geos:region",
            "interests:dlxc",
            "interests:dlxs",
            "interests:i360",
            "interests:nln",
            "interests:plc",
            "interests:slc",
            "interests:tgst",
            "interests:vac",
            "locations:chain_packages",
            "locations:circles",
            "locations:lois",
            "regulated_content",
            "segments:ab_segments",
            "segments:engagement",
            "segments:first_party",
            "segments:fti",
            "segments:lookalike",
            "segments:mobile",
            "segments:pixel"
    ]
  }
}

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

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting/v1/options

Parameters

Parameter Required Possible values Description
country_code R ISO ALPHA-2 Country Code (lowercase)
is_intl_vac_enabled O true, false (default) This parameter should be used to produce valid VAC options for countries outside of the US

Example #1 Targeting Support for Germany

curl "https://adsapi.snapchat.com/v1/targeting/v1/options?country_code=de&is_intl_vac_enabled=true" \
  -H "Authorization: Bearer  meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "f41d20fa-5ec2-45c9-8afd-a90efaaf764c",
    "targeting_option": {
        "snap_ads": [
            "demographics:age_groups",
            "demographics:age_min_max",
            "demographics:gender",
            "demographics:languages",
            "devices:carrier",
            "devices:connection_type",
            "devices:marketing_name",
            "devices:os_type",
            "geos:country",
            "geos:metro",
            "geos:postal_code",
            "geos:region",
            "interests:slc",
            "interests:vac",
            "locations:chain_packages",
            "locations:circles",
            "regulated_content",
            "segments:ab_segments",
            "segments:engagement",
            "segments:first_party",
            "segments:fti",
            "segments:lookalike",
            "segments:mobile",
            "segments:pixel"
        ]
    }
}

This example retrieves all targeting options available for Germany.

Demographics

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

Demographics - Age Groups

Get Age Group Targeting Options

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

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

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

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

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

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

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

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

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

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

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

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

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 , Oracle Datalogix (DLX) Interests, Placed Visitation Segments and Snap Visitation Segments.

The availability of interest targeting will vary from country to country, you should also take into account if the Campaign is targeting Housing, Credit or Employment in which case the interest categories may look different.

Interests - Snap Lifestyle Categories

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

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "490744c7-a663-4e9c-95b9-edc947cb6ce6",
    "paging": {},
    "targeting_dimensions": [
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_1",
                "name": "Adventure Seekers",
                "path": "/Adventure Seekers",
                "parent_id": "SLC_0",
                "source": "SNAPCHAT"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_10",
                "name": "Do-It-Yourselfers",
                "path": "/Do-It-Yourselfers",
                "parent_id": "SLC_0",
                "source": "SNAPCHAT"
            }
        },
        <<snip>>
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_97",
                "name": "Cricket Fans",
                "path": "/Sports Fans/Cricket Fans",
                "parent_id": "SLC_67",
                "source": "SNAPCHAT"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_98",
                "name": "Crime & Mystery Genre Fans",
                "path": "/Film & TV Fans/Crime & Mystery Genre Fans",
                "parent_id": "SLC_12",
                "source": "SNAPCHAT"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_99",
                "name": "Indie & Foreign Film Fans",
                "path": "/Film & TV Fans/Indie & Foreign Film Fans",
                "parent_id": "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/v1/interests/scls

Parameters

Parameter Default Description
country_code ISO ALPHA-2 Country Code (lowercase)
is_hec true optional parameter, returns interest targeting that is safe to use when advertising Housing, Credit and Employment
limit integer, min 50, max 1000

Interests - SCLS example

curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/scls?country_code=us&is_hec=true"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "40b06393-59de-46e7-b84a-f01d0708d3c6",
    "paging": {},
    "targeting_dimensions": [
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_10002",
                "name": "Arts & Culture Mavens - HEC",
                "path": "/Arts & Culture Mavens - HEC",
                "parent_id": "SLC_0",
                "source": "SNAPCHAT",
                "is_hec": true
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_10004",
                "name": "Beachgoers & Surfers - HEC",
                "path": "/Beachgoers & Surfers - HEC",
                "parent_id": "SLC_0",
                "source": "SNAPCHAT",
                "is_hec": true
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_10009",
                "name": "Comics & Animation Fans - HEC",
                "path": "/Comics & Animation Fans - HEC",
                "parent_id": "SLC_0",
                "source": "SNAPCHAT",
                "is_hec": true
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_10012",
                "name": "Film & TV Fans - HEC",
                "path": "/Film & TV Fans - HEC",
                "parent_id": "SLC_0",
                "source": "SNAPCHAT",
                "is_hec": true
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_10015",
                "name": "Cordcutters - HEC",
                "path": "/Film & TV Fans - HEC/Cordcutters - HEC",
                "parent_id": "SLC_10012",
                "source": "SNAPCHAT",
                "is_hec": true
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_10016",
                "name": "Drama Genre Fans - HEC",
                "path": "/Film & TV Fans - HEC/Drama Genre Fans - HEC",
                "parent_id": "SLC_10012",
                "source": "SNAPCHAT",
                "is_hec": true
            }
        },
        <<snip>>
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_10220",
                "name": "Console Gamers - HEC",
                "path": "/Gamers - HEC/Console Gamers - HEC",
                "parent_id": "SLC_10033",
                "source": "SNAPCHAT",
                "is_hec": true
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "scls": {
                "id": "SLC_10221",
                "name": "PC Gamers - HEC",
                "path": "/Gamers - HEC/PC Gamers - HEC",
                "parent_id": "SLC_10033",
                "source": "SNAPCHAT",
                "is_hec": true
            }
        }
    ]
}

Example of retrieving Snap Lifestyle Categories for use a campaign promoting Housing, Credit or Employment.

Interests - First Party Visitation Segments

Interest targeting based on visitation segments that are provided by Snap.

Get First Party Visitation Segments

curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/vac?country_code=us"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "cc492ca5-33cd-4c23-949d-b869d6e0e2d5",
    "paging": {},
    "targeting_dimensions": [
        {
            "sub_request_status": "SUCCESS",
            "vac": {
                "id": "VAC_1",
                "name": "Arts & Entertainment",
                "path": "/Arts & Entertainment",
                "parent_id": "VAC_0",
                "source": "SNAPCHAT"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "vac": {
                "id": "VAC_100",
                "name": "Chipotle Restaurants",
                "path": "/Dining & Nightlife/Fast Casual Restaurants/Chipotle Restaurants",
                "parent_id": "VAC_99",
                "source": "SNAPCHAT"
            }
        },
        <snip>
        {
            "sub_request_status": "SUCCESS",
            "vac": {
                "id": "VAC_97",
                "name": "Ice Cream Shops",
                "path": "/Dining & Nightlife/Sweet & Dessert Shops/Ice Cream Shops",
                "parent_id": "VAC_96",
                "source": "SNAPCHAT"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "vac": {
                "id": "VAC_99",
                "name": "Fast Casual Restaurants",
                "path": "/Dining & Nightlife/Fast Casual Restaurants",
                "parent_id": "VAC_53",
                "source": "SNAPCHAT"
            }
        }
    ]
}

This endpoint retrieves a list of targeting options for First Party Visitation Segments.

HTTP Request

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

Parameters

Parameter Possible values Description
country_code ISO ALPHA-2 Country Code (lowercase)
is_hec true, false (default) optional parameter, returns interest targeting that is safe to use when advertising Housing, Credit and Employment (only available for US)
limit integer, min 50, max 1000

Interests - VAC example #1 United States

curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/vac?is_hec=true&country_code=us"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "913bdce1-8dbf-4dce-a224-cf7ca1edc538",
    "paging": {},
    "targeting_dimensions": [
        {
            "sub_request_status": "SUCCESS",
            "vac": {
                "id": "VAC_10001",
                "name": "Arts & Entertainment - HEC",
                "path": "/Arts & Entertainment - HEC",
                "parent_id": "VAC_0",
                "source": "SNAPCHAT",
                "is_hec": true
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "vac": {
                "id": "VAC_10008",
                "name": "Movie Theaters - HEC",
                "path": "/Arts & Entertainment - HEC/Movie Theaters - HEC",
                "parent_id": "VAC_10001",
                "source": "SNAPCHAT",
                "is_hec": true
            }
        },
        <snip>
        {
            "sub_request_status": "SUCCESS",
            "vac": {
                "id": "VAC_10291",
                "name": "Theme Parks - HEC",
                "path": "/Travel - HEC/Theme Parks - HEC",
                "parent_id": "VAC_10265",
                "source": "SNAPCHAT",
                "is_hec": true
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "vac": {
                "id": "VAC_10292",
                "name": "Disney Parks and Hotels - HEC",
                "path": "/Travel - HEC/Theme Parks - HEC/Disney Parks and Hotels - HEC",
                "parent_id": "VAC_10291",
                "source": "SNAPCHAT",
                "is_hec": true
            }
        }
    ]
}

Example of retrieving First Party Visitation Segments for use with an Ad Set promoting Housing, Credit or Employment, targeting the United States.

Interests - VAC example #2 Germany

curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/vac?country_code=de"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "8a22cbcd-8f4b-423b-87d0-f0528399ffb7",
    "paging": {},
    "targeting_dimensions": [
        {
            "sub_request_status": "SUCCESS",
            "vac": {
                "id": "VAC_1",
                "name": "Arts & Entertainment",
                "path": "/Arts & Entertainment",
                "parent_id": "VAC_0",
                "source": "SNAPCHAT"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "vac": {
                "id": "VAC_100",
                "name": "Chipotle Restaurants",
                "path": "/Dining & Nightlife/Fast Casual Restaurants/Chipotle Restaurants",
                "parent_id": "VAC_99",
                "source": "SNAPCHAT"
            }
        },
        <snip>
        {
            "sub_request_status": "SUCCESS",
            "vac": {
                "id": "VAC_97",
                "name": "Ice Cream Shops",
                "path": "/Dining & Nightlife/Sweet & Dessert Shops/Ice Cream Shops",
                "parent_id": "VAC_96",
                "source": "SNAPCHAT"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "vac": {
                "id": "VAC_99",
                "name": "Fast Casual Restaurants",
                "path": "/Dining & Nightlife/Fast Casual Restaurants",
                "parent_id": "VAC_53",
                "source": "SNAPCHAT"
            }
        }
    ]
}

Example of retrieving First Party Visitation Segments for use with an Ad Set targeting Germany.

Interests - First Party Shopper Segments

Interest targeting based on shopper segments that are provided by Snap.

Get First Party Shopper Segments

curl "https://adsapi.snapchat.com/v1/targeting/v1/interests/shp?country_code=us&limit=50"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "576f7f3a-c58b-407d-bdbf-21802c8b61b9",
    "paging": {},
    "targeting_dimensions": [
        {
            "sub_request_status": "SUCCESS",
            "shp": {
                "id": "SHP_73",
                "name": "Amusement Parks Buyers",
                "path": "/Amusement Parks Buyers",
                "parentId": "SHP_0",
                "source": "SNAPCHAT"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "shp": {
                "id": "SHP_99",
                "name": "Disney Parks",
                "path": "/Amusement Parks Buyers/Disney Parks",
                "parentId": "SHP_73",
                "source": "SNAPCHAT"
            }
        },
        <snip>
        {
            "sub_request_status": "SUCCESS",
            "shp": {
                "id": "SHP_37",
                "name": "Hotel & Motel Buyers",
                "path": "/Travel Services Buyers/Hotel & Motel Buyers",
                "parentId": "SHP_15",
                "source": "SNAPCHAT"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "shp": {
                "id": "SHP_122",
                "name": "eCommerce Buyers",
                "path": "/eCommerce Buyers",
                "parentId": "SHP_0",
                "source": "SNAPCHAT"
            }
        }
    ]
}

This endpoint retrieves a list of targeting options for First Party Shopper Segments.

HTTP Request

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

Parameters

Parameter Default Description Possible values
country_code ISO ALPHA-2 Country Code (lowercase) us
limit integer, min 50, max 1000

Interests - Oracle Datalogix (DLX)

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

Get Oracle Datalogix DLXS Interest Targeting Options

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

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

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

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

Location

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

Location - Categories

Get Location Categories Targeting Options

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

Targeting Specs - Greater than 500 rows

Any Ad Squad that contains more than 500 targeting criteria will have its targeting specifications broken out into a separate sub resource called targeting_specs and will be replaced by a property called separated_types. Any further updates or reads to the targeting spec will need to be performed on the new targeting_spec sub resource and not in the Ad Squad resource. This new resource is also described below.

Please note that before the deprecation date, you can use the below query parameter to test and build against the changes. targeting_spec_response_scope=AD_SQUAD_ONLY

Create Ad Squad

The create API call remains mostly the same, except if it contains more than 500 targeting criteria, in which case the targeting will be broken out into a new targeting sub resource. The response will contain the new separated_types attribute, indicating that this breakout has been performed.

HTTP Request

POST https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{
    "adsquads": [
        {
            "name": "Badger Supplies 2000 US Postcode Targeting",
            "status": "ACTIVE",
            "campaign_id": "51334977-d500-4f6a-bb5c-e6d4c2e00067",
            "type": "SNAP_ADS",
            "targeting":
            {
                "regulated_content": false,
                "geos": [
                    {
                        "country_code": "us",
                        "postal_code": [
                            "20001"
                        ],
                        "operation": "INCLUDE"
                    },
                    {
                        "country_code": "us",
                        "postal_code": [
                            "20009"
                        ],
                        "operation": "INCLUDE"
                    },
                    ...
                },
                {
                    "country_code": "us",
                    "postal_code": [
                        "08903"
                    ],
                    "operation": "INCLUDE"
                },
                {
                    "country_code": "us",
                    "postal_code": [
                        "08906"
                    ],
                    "operation": "INCLUDE"
                }
            ],
            "devices": [
            {}],
            "auto_expansion_options":
            {
                "interest_expansion_option":
                {
                    "enabled": true
                },
                "custom_audience_expansion_option":
                {
                    "enabled": true
                }
            }
        },
        "billing_event": "IMPRESSION",
        "auto_bid": true,
        "target_bid": false,
        "bid_strategy": "AUTO_BID",
        "daily_budget_micro": 50000000,
        "start_time": "2021-09-16T11:22:31.894Z",
        "optimization_goal": "SWIPES",
        "delivery_constraint": "DAILY_BUDGET",
        "pacing_type": "STANDARD"
    }
]
}' \
   "https://adsapi.snapchat.com/v1/campaigns/51334977-d500-4f6a-bb5c-e6d4c2e00067/adsquads"

The above command returns JSON structured like this:

Response:
{
    "request_status": "SUCCESS",
    "request_id": "616edbf700ff0cbfe2f0d990390001737e7465616d6b6f363139000161646d616e616765722d6170693a6b702d726176360001010f",
    "adsquads": [
    {
        "sub_request_status": "SUCCESS",
        "adsquad":
        {
            "id": "a4a40858-c794-432b-aaca-71314e019a86",
            "updated_at": "2021-10-19T14:53:56.773Z",
            "created_at": "2021-10-19T14:53:56.270Z",
            "effective_status": "PAUSED",
            "name": "Badger Supplies 2000 US Postcode Targeting",
            "status": "ACTIVE",
            "campaign_id": "51334977-d500-4f6a-bb5c-e6d4c2e00067",
            "type": "SNAP_ADS",
            "targeting":
            {
                "regulated_content": false,
                "separated_types": [
                    "GEO"
                ],
                "devices": [
                {}],
                "auto_expansion_options":
                {
                    "interest_expansion_option":
                    {
                        "enabled": true
                    },
                    "custom_audience_expansion_option":
                    {
                        "enabled": true
                    }
                }
            },
            "targeting_reach_status": "VALID",
            "placement": "SNAP_ADS",
            "billing_event": "IMPRESSION",
            "auto_bid": true,
            "target_bid": false,
            "bid_strategy": "AUTO_BID",
            "daily_budget_micro": 50000000,
            "start_time": "2021-09-16T11:22:31.894Z",
            "optimization_goal": "SWIPES",
            "delivery_constraint": "DAILY_BUDGET",
            "pacing_type": "STANDARD",
            "creation_state": "PUBLISHED",
            "delivery_status": [
                "INVALID_EFFECTIVE_INVALID",
                "INVALID_NOT_EFFECTIVE_ACTIVE"
            ],
            "skadnetwork_properties":
            {
                "status": "NEVER_ENROLLED"
            }
        }
    }]
}

GET Ad Squad:

The GET endpoint remains the same, except in the case that there are more than 500 targeting criteria, in which case it will not return any targeting spec in the response and will return a separated_types property. To retrieve the targeting spec you must call the targeting sub resource.

HTTP Request

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

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
   "https://adsapi.snapchat.com/v1/adsquads/a4a40858-c794-432b-aaca-71314e019a86?return_placement_v2=true"

The above command returns JSON structured like this:

Response:
{
    "request_status": "SUCCESS",
    "request_id": "616ee96a00ff06b0b1557b48670001737e7465616d6b6f363139000161646d616e616765722d6170693a6b702d7261763600010131",
    "adsquads": [
    {
        "sub_request_status": "SUCCESS",
        "adsquad":
        {
            "id": "a4a40858-c794-432b-aaca-71314e019a86",
            "updated_at": "2021-10-19T14:53:56.773Z",
            "created_at": "2021-10-19T14:53:56.270Z",
            "effective_status": "PAUSED",
            "name": "Badger Supplies US Post Code Targeting II",
            "status": "ACTIVE",
            "campaign_id": "51334977-d500-4f6a-bb5c-e6d4c2e00067",
            "type": "SNAP_ADS",
            "targeting":
            {
                "regulated_content": false,
                "separated_types": [
                    "GEO"
                ],
                "devices": [
                {}],
                "auto_expansion_options":
                {
                    "interest_expansion_option":
                    {
                        "enabled": true
                    },
                    "custom_audience_expansion_option":
                    {
                        "enabled": true
                    }
                }
            },
            "targeting_reach_status": "VALID",
            "placement_v2":
            {
                "config": "CUSTOM",
                "platforms": [
                    "SNAPCHAT"
                ],
                "snapchat_positions": [
                    "INTERSTITIAL_USER",
                    "INTERSTITIAL_CONTENT",
                    "INSTREAM"
                ]
            },
            "billing_event": "IMPRESSION",
            "auto_bid": true,
            "target_bid": false,
            "bid_strategy": "AUTO_BID",
            "daily_budget_micro": 50000000,
            "start_time": "2021-09-16T11:22:31.894Z",
            "optimization_goal": "SWIPES",
            "delivery_constraint": "DAILY_BUDGET",
            "pacing_type": "STANDARD",
            "creation_state": "PUBLISHED",
            "delivery_status": [
                "INVALID_EFFECTIVE_INVALID",
                "INVALID_NOT_EFFECTIVE_ACTIVE"
            ],
            "skadnetwork_properties":
            {
                "status": "NEVER_ENROLLED"
            }
        }
    }]
}

Update Ad Squad

The update will work the same, except in the situation where there are more than 500 targeting criteria. In this case you can no longer use the Ad Squad endpoint to update the targeting criteria and doing so will return an error. You may continue to use the Ad Squad endpoint to update other fields. To update the targeting criteria, you must use the targeting resource.

HTTP Request

PUT https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{
    "adsquads": [
    {
        "id": "a4a40858-c794-432b-aaca-71314e019a86",
        "updated_at": "2021-10-19T14:53:56.773Z",
        "created_at": "2021-10-19T14:53:56.270Z",
        "effective_status": "PAUSED",
        "name": "Badger Supplies US Postcode Targeting",
        "status": "ACTIVE",
        "campaign_id": "51334977-d500-4f6a-bb5c-e6d4c2e00067",
        "type": "SNAP_ADS",
        "targeting":
        {
            "regulated_content": false,
            "geos": [
                {
                    "country_code": "us",
                    "postal_code": [
                        "20001"
                    ],
                    "operation": "INCLUDE"
                },
                {
                    "country_code": "us",
                    "postal_code": [
                        "20009"
                    ],
                    "operation": "INCLUDE"
                },
                ...
                {
                    "country_code": "us",
                    "postal_code": [
                        "08903"
                    ],
                    "operation": "INCLUDE"
                },
                {
                    "country_code": "us",
                    "postal_code": [
                        "08906"
                    ],
                    "operation": "INCLUDE"
                },
                {
                    "country_code": "ca",
                    "operation": "INCLUDE"
                }
            ],
            "devices": [
            {}],
            "auto_expansion_options":
            {
                "interest_expansion_option":
                {
                    "enabled": true
                },
                "custom_audience_expansion_option":
                {
                    "enabled": true
                }
            }
        },
        "targeting_reach_status": "VALID",
        "placement_v2":
        {
            "config": "CUSTOM",
            "platforms": [
                "SNAPCHAT"
            ],
            "snapchat_positions": [
                "INTERSTITIAL_USER",
                "INTERSTITIAL_CONTENT",
                "INSTREAM"
            ]
        },
        "billing_event": "IMPRESSION",
        "auto_bid": true,
        "target_bid": false,
        "bid_strategy": "AUTO_BID",
        "daily_budget_micro": 50000000,
        "start_time": "2021-09-16T11:22:31.894Z",
        "optimization_goal": "SWIPES"
    }]
}' \
   "https://adsapi.snapchat.com/v1/campaigns/51334977-d500-4f6a-bb5c-e6d4c2e00067/adsquads"

The above command returns JSON structured like this:

Response:
{
    "request_status": "SUCCESS",
    "request_id": "617035ff0000ff07f6b7ff00b0ef310001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d38393135316663392d312d3438382d3000010148",
    "adsquads": [
    {
        "sub_request_status": "SUCCESS",
        "adsquad":
        {
            "id": "a4a40858-c794-432b-aaca-71314e019a86",
            "updated_at": "2021-10-20T15:30:16.952Z",
            "created_at": "2021-10-19T14:53:56.270Z",
            "effective_status": "PAUSED",
            "name": "Badger Supplies US Postcode Targeting",
            "status": "ACTIVE",
            "campaign_id": "51334977-d500-4f6a-bb5c-e6d4c2e00067",
            "type": "SNAP_ADS",
            "targeting":
            {
                "regulated_content": false,
                "separated_types": [
                    "GEO"
                ],
                "devices": [
                {}],
                "auto_expansion_options":
                {
                    "interest_expansion_option":
                    {
                        "enabled": true
                    },
                    "custom_audience_expansion_option":
                    {
                        "enabled": true
                    }
                }
            },
            "targeting_reach_status": "VALID",
            "placement_v2":
            {
                "config": "CUSTOM",
                "platforms": [
                    "SNAPCHAT"
                ],
                "snapchat_positions": [
                    "INTERSTITIAL_USER",
                    "INTERSTITIAL_CONTENT",
                    "INSTREAM"
                ]
            },
            "billing_event": "IMPRESSION",
            "auto_bid": true,
            "target_bid": false,
            "bid_strategy": "AUTO_BID",
            "daily_budget_micro": 50000000,
            "start_time": "2021-09-16T11:22:31.894Z",
            "optimization_goal": "SWIPES",
            "delivery_constraint": "DAILY_BUDGET",
            "pacing_type": "STANDARD",
            "creation_state": "PUBLISHED",
            "delivery_status": [
                "INVALID_EFFECTIVE_INVALID",
                "INVALID_NOT_EFFECTIVE_ACTIVE"
            ],
            "skadnetwork_properties":
            {
                "status": "NEVER_ENROLLED"
            },
            "delivery_properties_version": 1634743816283
        }
    }]
}

GET all targeting specs under Ad Squad

This request retrieves all Targeting Specs under the specified Ad Squad, currently there can only be one Targeting Spec for an Ad Squad. If the response consists of an empty array it means the Ad Squad does not have an associated Targeting Spec.

HTTP Request

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

URL Parameters

Attribute Description
ad_squad_id The ID of the Ad Squad under which the Targeting Spec is being created
curl -X GET \
  -H "Authorization: Bearer meowmeowmeow" \
   "https://adsapi.snapchat.com/v1/adsquads/a4a40858-c794-432b-aaca-71314e019a86/targeting_specs"

The above command returns JSON structured like this:

Response:
{
    "request_status": "SUCCESS",
    "request_id": "6170522400ff065868237e7ebf0001737e7465616d6b6f363139000161646d616e616765722d6170693a776e75636b6f6c73746573740001012f",
    "paging":
    {},
    "targeting_specs": [
    {
        "sub_request_status": "SUCCESS",
        "targeting_spec":
        {
            "id": "7ba7b1f3-2eb7-471d-a143-dd9c4b60cda7",
            "updated_at": "2021-10-20T15:30:16.704Z",
            "created_at": "2021-10-19T14:53:57.161Z",
            "container_kind": "AdSquads",
            "container_id": "a4a40858-c794-432b-aaca-71314e019a86",
            "type": "GEO",
            "geos": [

                {
                    "country_code": "us",
                    "postal_code": [
                        "20001"
                    ],
                    "operation": "EXCLUDE"
                },
                {
                    "country_code": "us",
                    "postal_code": [
                        "20009"
                    ],
                    "operation": "EXCLUDE"
                },
                ...
                {
                    "country_code": "us",
                    "postal_code": [
                        "08903"
                    ],
                    "operation": "INCLUDE"
                },
                {
                    "country_code": "ca",
                    "postal_code": [
                        "08906"
                    ],
                    "operation": "INCLUDE"
                }
            ]
        }
    }]
}

GET a specific targeting spec

This request retrieves a specific Targeting Spec.

HTTP Request

GET https://adsapi.snapchat.com/v1/targeting_specs/{targeting_spec_id}

URL Parameters

Attribute Description
targeting_spec_id The ID of the Targeting Spec you wish to retrieve
curl -X GET \
  -H "Authorization: Bearer meowmeowmeow" \
   "https://adsapi.snapchat.com/v1/targeting_specs/{targeting_spec_id}"

The above command returns JSON structured like this:

Response:
{
    "request_status": "SUCCESS",
    "request_id": "617069bf00ff0a62999d01b8160001737e7465616d6b6f363139000161646d616e616765722d6170693a776e75636b6f6c737465737400010128",
    "targeting_specs": [
    {
        "sub_request_status": "SUCCESS",
        "targeting_spec":
        {
            "id": "7ba7b1f3-2eb7-471d-a143-dd9c4b60cda7",
            "updated_at": "2021-10-20T15:30:16.704Z",
            "created_at": "2021-10-19T14:53:57.161Z",
            "container_kind": "AdSquads",
            "container_id": "a4a40858-c794-432b-aaca-71314e019a86",
            "type": "GEO",
            "geos": [
                {
                    "country_code": "us",
                    "postal_code": [
                        "20001"
                    ],
                    "operation": "INCLUDE"
                },
                {
                    "country_code": "us",
                    "postal_code": [
                        "20009"
                    ],
                    "operation": "INCLUDE"
                },

                ...
                {
                    "country_code": "us",
                    "postal_code": [
                        "08903"
                    ],
                    "operation": "INCLUDE"
                },
                {
                    "country_code": "us",
                    "postal_code": [
                        "08906"
                    ],
                    "operation": "INCLUDE"
                },
                {
                    "country_code": "ca",
                    "operation": "INCLUDE"
                }
            ]
        }
    }]
}

Updating a Targeting Spec

This request will update a Targeting Spec, note that the Targeting Spec has a maximum limit of 4,000 targeting criteria.

HTTP Request

PUT https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/targeting_specs

URL Parameters

Attribute Description
ad_squad_id The ID of the Ad Squad under which the Targeting Spec is being created

Attributes

Attribute Description Required Possible Values
id The ID of the Targeting Spec you wish to update R
type The type of targeting, currently only GEO R GEO
geos An array containing a valid targeting spec for geos R
curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{
    "targeting_specs": [
    {
        "id": "7ba7b1f3-2eb7-471d-a143-dd9c4b60cda7",
        "type": "GEO",
        "geos": [
            {
                "country_code": "us",
                "postal_code": [
                    "20001"
                ],
                "operation": "INCLUDE"
            },
            {
                "country_code": "us",
                "postal_code": [
                    "20009"
                ],
                "operation": "INCLUDE"
            },
            ...
            {
                "country_code": "us",
                "postal_code": [
                    "08903"
                ],
                "operation": "INCLUDE"
            },
            {
                "country_code": "us",
                "postal_code": [
                    "08906"
                ],
                "operation": "INCLUDE"
            },
            {
                "country_code": "ca",
                "operation": "INCLUDE"
            },
            {
                "country_code": "ie",
                "operation": "INCLUDE"
            }
        ]
    }]
}' \
   "https://adsapi.snapchat.com/v1/adsquads/a4a40858-c794-432b-aaca-71314e019a86/targeting_specs"

The above command returns JSON structured like this:

Response:
{
    "request_status": "SUCCESS",
    "request_id": "61706cea00ff0bc60d6308beaf0001737e7465616d6b6f363139000161646d616e616765722d6170693a776e75636b6f6c737465737400010140",
    "targeting_specs": [
    {
        "sub_request_status": "SUCCESS",
        "targeting_spec":
        {
            "id": "7ba7b1f3-2eb7-471d-a143-dd9c4b60cda7",
            "updated_at": "2021-10-20T19:24:41.668Z",
            "created_at": "2021-10-19T14:53:57.161Z",
            "container_kind": "AdSquads",
            "container_id": "a4a40858-c794-432b-aaca-71314e019a86",
            "type": "GEO",
            "geos": [
                {
                    "country_code": "us",
                    "postal_code": [
                        "20001"
                    ],
                    "operation": "INCLUDE"
                },
                {
                    "country_code": "us",
                    "postal_code": [
                        "20009"
                    ],
                    "operation": "INCLUDE"
                },
                ...
                {
                    "country_code": "us",
                    "postal_code": [
                        "08903"
                    ],
                    "operation": "INCLUDE"
                },
                {
                    "country_code": "us",
                    "postal_code": [
                        "08906"
                    ],
                    "operation": "INCLUDE"
                },
                {
                    "country_code": "ca",
                    "operation": "INCLUDE"
                },
                {
                    "country_code": "ie",
                    "operation": "INCLUDE"
                }
            ]
        }
    }]
}

Customer Lists

Customer Lists allow 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 375 characters max
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

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 Customer List 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

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 Customer List 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

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 -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 Customer List 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 O
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

^This field is here for legacy reasons and should be skipped for new implmentations

HTTP Request

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

Parameters

Parameter Default Description
segment_id Segment ID

Normalizing & Hashing

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

Normalizing Identifiers

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

Hashing Identifiers

Hash raw identifiers with lowercase hex SHA256 format.

Adding Users (Single-Key)

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{"users":[{ "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 Customer List 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)

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 Customer List 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

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

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

Customer Lists - Lookalikes

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

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

Attributes

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

Creation Spec Details

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

Create an Lookalike Segment

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 Customer List 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",
    "operation": "INCLUDE"
  },
  {
    "country_code": "us",
    "region_id": ["3"],
    "operation": "EXCLUDE"
  },
  {
    "country_code": "us",
    "region_id": ["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 Customer List 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 Customer List segment ID “98765”

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

Example 10

United States, AT&T

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

Example 11

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

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

Example 12

United States, metros New York or Los Angeles only

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

Example 13

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

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

Example 14

Zipcode Targeting

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

Example 15

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

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

Example 16

Location Categories: Targeting Sports Arenas, Fitness Centers

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

Example 17

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

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

Example 18

Multi-country targeting: Targeting the US and Canada

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

Example 19

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

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

Example 20

App Install State targeting using a Snap App ID

{
  "app_install_states": [
      {
        "state": "INSTALLED",
        "snap_app_ids": [
          "85a0bfd4-2f0c-4797-bceb-b0a8375c5828"
        ]
      }
    ]
}

App Install State targeting is required for Ad Squads that use the optimization goal APP_REENGAGE_OPEN or APP_REENGAGE_PURCHASE.

Example 21

App Install State targeting - Prospecting Product Audience

App Install State targeting in use with Dynamic Product Ads of the type APP_INSTALL

{
  "product_audiences": [
    {
      "product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
      "event_type": "PAGE_VIEW",
      "retention_seconds": 1209600,
      "operation": "EXCLUDE"
    },
    {
      "product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
      "event_type": "ADD_CART",
      "retention_seconds": 1209600,
      "operation": "EXCLUDE"
    },
    {
      "product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
      "event_type": "PURCHASE",
      "retention_seconds": 1209600,
      "operation": "EXCLUDE"
    },
    {
      "product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
      "event_type": "VIEW_CONTENT",
      "retention_seconds": 1209600,
      "operation": "EXCLUDE"
    }
  ],
  "app_install_states": [
    {
      "state": "NOT_INSTALLED",
      "snap_app_ids": [
        "2e1154ae-35fc-4b9e-8c40-4816dfb42038"
      ]
    }
  ]
}

Example 22

App Install State targeting - Retargeting Product Audience

App Install State targeting in use with Dynamic Product Ads of the type DEEP_LINK

{
  "product_audiences": [
    {
      "product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
      "event_type": "PAGE_VIEW",
      "retention_seconds": 1209600,
      "operation": "INCLUDE"
    },
    {
      "product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
      "event_type": "ADD_CART",
      "retention_seconds": 1209600,
      "operation": "INCLUDE"
    },
    {
      "product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
      "event_type": "VIEW_CONTENT",
      "retention_seconds": 1209600,
      "operation": "INCLUDE"
    },
    {
      "product_set": "897cce5d-95c9-4c67-91e7-86ce8ea21f21",
      "event_type": "PURCHASE",
      "retention_seconds": 1209600,
      "operation": "EXCLUDE"
    }
  ],
  "app_install_states": [
      {
        "state": "INSTALLED",
        "snap_app_ids": [
          "85a0bfd4-2f0c-4797-bceb-b0a8375c5828"
        ]
      }
    ]
}

Example 23

Visitation Audience Segments: Targeting users in the US who visited an ice cream shop

In this example, we target users who have visited an ice cream shop by using the First Party Visitation Segment, “VAC_97”, which contains users who have visited an ice cream shop.

{
    "geos": [
        {
            "country_code": "us"
        }
    ],
    "interests": [
        {
            "category_id": [
                "VAC_97"
            ],
            "operation": "INCLUDE"
        }
    ]
}

Example 24

Household income targeting: Targeting users in the US who have a household income of $200,000 or more

Here, we target users by using the advanced_demographics audience “DMG_4”, which is a collection of users who have a household income of $200,000 or more.

{
    "demographics": [
        {
            "advanced_demographics": [
                "DMG_4"
            ]
        }
    ],
    "geos": [
        {
            "country_code": "us"
        }
    ]
}

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

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.

Bid Estimate is available for the following optimization goals.

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
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_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_PAGE_VIEW Target Cost Per PAGE_VIEW on web bid_micro is treated as a goal, not a maximum, and can be exceeded
PIXEL_PURCHASE Target Cost Per PURCHASE on web bid_micro is treated as a goal, not a maximum, and can be exceeded
PIXEL_SIGNUP Target Cost Per SIGNUP on web bid_micro is treated as a goal, not a maximum, and can be exceeded
APP_ADD_TO_CART Target Cost Per ADD_TO_CART on app bid_micro is treated as a goal, not a maximum, and can be exceeded
APP_PURCHASE Target Cost Per PURCHASE on app bid_micro is treated as a goal, not a maximum, and can be exceeded
APP_SIGNUP Target Cost Per PURCHASE on app bid_micro is treated as a goal, not a maximum, and can be exceeded
APP_REENGAGE_OPEN Target Cost Per App open bid_micro is treated as a goal, not a maximum, and can be exceeded
APP_REENGAGE_PURCHASE Target Cost Per App Purchase bid_micro is treated as a goal, not a maximum, and can be exceeded

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
INVALID_EFFECTIVE_DELETED Entity is effectively deleted, often due to parent
INVALID_EFFECTIVE_INVALID Entity is effectively invalid, often due to parent
INVALID_START_TIME_AFTER_END_TIME Effective start time is after effective end time
Organization NOT_ACTIVE_ORGANIZATION Organization state isn’t active
NOT_ENTERPRISE_ORGANIZATION Organization type isn’t enterprise
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
INVALID_CAMPAIGN_HAS_NO_ACTIVE_AD_SQUAD Campaign has no active ad squad
INVALID_TEST_ACCOUNT Test account is invalid
Ad Squad INVALID_TARGETING_REACH_STATUS AdSquad targeting reach status is invalid
INVALID_PENDING_TARGETING_REACH_STATUS AdSquad targeting reach status is pending
INVALID_AD_SQUAD_HAS_NO_ACTIVE_ADS AdSquad doesn’t have any active ad
INVALID_AD_SQUAD_WIREOBJECT Failed to convert ad squad entity to wire object
INVALID_INTERNAL_PLACEMENT AdSquad has invalid internal placement v2 and non-empty ads
INVALID_AD_SQUAD_HAS_UNSUPPORTED_AD_TYPE AdSquad has unsupported ad type
INVALID_UNSUPPORTED_AD_SQUAD_TYPE AdSquad has an unsupported type
INVALID_AD_SQUAD_LIFETIME_SPEND_CAP Ad squad has invalid lifetime spend cap
INVALID_OVER_BUDGET_AD_SQUAD_FINALIZED_LIFETIME_SPEND Ad squad finalized lifetime spend exceeds lifetime spend cap
INVALID_OVER_BUDGET_AD_SQUAD_REALTIME_LIFETIME_SPEND Ad squad realtime lifetime spend exceeds lifetime spend cap
INVALID_AD_SQUAD_DAILY_SPEND_CAP Ad squad has invalid daily spend cap
INVALID_OVER_BUDGET_AD_SQUAD_DAILY_SPEND Ad squad daily spend exceeds daily spend cap
INVALID_AD_SQUAD_RESERVED_STATUS_NOT_ACTIVE Ad Squad reserved_status is non-ACTIVE
LEARNING PHASE Ad Squad is in learning phase.
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
INVALID_NO_CREATIVE_EFFECTIVE_ACTIVE Ad has no effectively active Creative
INVALID_DYNAMIC_FILTER Dynamic fields in Filter creator in Ads Manager have errors. Eg “Time of Day” or “Day of Week”. Filter Ad will not be published
INVALID_CREATIVE_PACKAGING_STATUS Processsing of image/video asset failed
INVALID_SKOV_REQUIRES_SKAN SKAN must be enabled on ad set if using SKOverlay

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
            }
          }
          ....
          {
            "start_time": "2016-08-06T16:00:00.000-07:00",
            "end_time": "2016-08-06T17:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          },
          {
            "start_time": "2016-08-06T17:00:00.000-07:00",
            "end_time": "2016-08-06T18:00:00.000-07:00",
            "stats": {
              "impressions": 0,
              "swipes": 0,
              "spend": 0,
              "quartile_1": 0,
              "quartile_2": 0,
              "quartile_3": 0,
              "view_completion": 0,
              "screen_time_millis": 0
            }
          }
        ]
      }
    }
  ]
}

Request Parameters

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

** offline conversion data source ( conversion_source_types=offline ) and impression based conversions ( action_report_time=impression ) are available from 1 May 2020 onwards.
*** 28_DAY view_attribution_window is deprecated, legacy data is available up until 1 March 2021

Response Parameters & Finalization

Attribute Description
finalized_data_end_time This attribute defines the time up until when non-conversion 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.
conversion_data_processed_end_time This attribute defines the time up until when conversion metrics are finalized, for any time after the conversion_data_processed_end_time the conversion metrics are still undergoing processing and may change accordingly. Note that this attribute only covers conversion by time of conversion.
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

See the Metrics and supported granularities table for a breakdown of the reporting granularities available per Ad type. 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
profile_clicks Any # of times users tapped the logo in the upper corner taking them to the profile page
position_impressions STORY # the impression number 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
paid_impressions LENS, FILTER, AD_TO_LENS The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter’s viewing session
earned_impressions LENS, FILTER, AD_TO_LENS The number of times your ad was viewed after being shared by a Snapchatter via Chat or Stories
total_impressions LENS The total number of impressions (Paid and Earned)
play_time_millis LENS The total amount of time in where Snapchatters interacted with your Lens in the camera (milliseconds)
total_reach LENS The number of unique Snapchatters who viewed your Lens ad, either by receiving a Paid or Earned Impression.
earned_reach LENS, FILTER, AD_TO_LENS The number of unique Snapchatters who viewed the filter/lens
native_leads LEAD_GENERATION Total number of Snapchat users that swipe up, fill out the required fields, and hit ‘Submit’ on Lead Form attachments. If a user swipes down or cancels before hitting ‘Submit,’ this action is not counted

Apple Transparent Tracking (ATT) Reporting

All the users whose activity is tracked using the attribution and measurement services will be split into two categories. Please note that only conversion metrics are affected by the ATT updates.

User Category Description User groups in category
Fully Tracked group These user groups are fully supported for the features listed below. Android, iOS opted-in users
Partially tracked group These user groups are partially supported. Snap Pixel, iOS opted out users and users reported via Conversions API

Below is the list of all the reporting fields and API fields that are affected for each group.

Dimension/Granularity Conversion Sources
Fully Tracked Group -
Android (in-app), iOS (opt-in)
Partially tracked Group -
Snap Pixel, iOS (opt-out), Conversion API
Time of Conversion
action_report_time=conversion
Supported Supported
Time of Exposure
action_report_time=impression
Supported Supported
Event Source
(web/app/offline)
Supported Supported
Entity
(campaign/ad set/ad)
Supported Supported
Age Supported Supported
Gender Supported Supported
Age, Gender Supported Supported
Country Supported Supported
OS Supported Supported
Platform (on/off snapchat) Supported Supported
Region (US Only) NOT Supported NOT Supported
DMA (US Only) NOT Supported NOT Supported
Device Make NOT Supported NOT Supported
SLC (lifestyle category) NOT Supported NOT Supported
Product NOT Supported NOT Supported
Hourly Conversions Supported NOT Supported
Daily, Total, Lifetime Conversion Supported Supported
Swipe Up Window:
1_DAY, 7_DAY, 28_DAY
View Thru Window:
1_DAY, 7_DAY
Supported Supported
View Through Window:
1_HOUR, 3_HOUR, 6_HOUR
Supported Supported
View Through Window: 28_DAY* NOT Supported NOT Supported

*This field is now effectively deprecated.

SKAd Network Reporting

Due to the attribution methodology of Apple’s SKAdNetwork there are some limitations when fetching reporting for Ad serving entities that are opted into SKAdNetwork tracking.

SKAd Network Conversion Metrics

Conversion metrics for the SKAd Network are broken out by Swipe conversions, View conversions, and the total number of conversions.

SKAd Network Swipe Conversion Metrics

The following metrics return the SKAd Network SWIPE (click) conversions.

Name Description
conversion_total_installs_sk_ad_network Total App Installs tracked via SKAd Network
conversion_ios_installs_sk_ad_network Exact same metric as conversion_total_installs_sk_ad_network
conversion_purchases_sk_ad_network
conversion_save_sk_ad_network
conversion_start_checkout_sk_ad_network
conversion_add_cart_sk_ad_network
conversion_view_content_sk_ad_network
conversion_add_billing_sk_ad_network
conversion_sign_ups_sk_ad_network
conversion_searches_sk_ad_network
conversion_level_completes_sk_ad_network
conversion_app_opens_sk_ad_network
conversion_page_views_sk_ad_network
conversion_subscribe_sk_ad_network
conversion_ad_click_sk_ad_network
conversion_ad_view_sk_ad_network
conversion_complete_tutorial_sk_ad_network
conversion_invite_sk_ad_network
conversion_login_sk_ad_network
conversion_share_sk_ad_network
conversion_reserve_sk_ad_network
conversion_achievement_unlocked_sk_ad_network
conversion_add_to_wishlist_sk_ad_network
conversion_spend_credits_sk_ad_network
conversion_rate_sk_ad_network
conversion_start_trial_sk_ad_network
conversion_list_view_sk_ad_network
custom_event_1_sk_ad_network
custom_event_2_sk_ad_network
custom_event_3_sk_ad_network
custom_event_4_sk_ad_network
custom_event_5_sk_ad_network
unknown_sk_ad_network SkAdNetwork conversion events with unknown Conversion Values.
conversion_assist_install_sk_ad_network The number of times the SKAdNetwork campaign drove an App Install, but was not the last touch before the App Install occurred.
conversion_null_sk_ad_network The number of SKAdNetwork conversion events with “null” Conversion Values. This indicates the campaign did not generate enough daily SKAdNetwork conversions to pass Apple’s privacy threshold.

SKAd Network View Conversion Metrics

The following metrics return the SKAd Network VIEW conversions.

Name Description
conversion_total_installs_sk_ad_network_view Total App Installs tracked via SKAd Network
conversion_ios_installs_sk_ad_network_view Exact same metric as conversion_total_installs_sk_ad_network_view
conversion_purchases_sk_ad_network_view
conversion_save_sk_ad_network_view
conversion_start_checkout_sk_ad_network_view
conversion_add_cart_sk_ad_network_view
conversion_view_content_sk_ad_network_view
conversion_add_billing_sk_ad_network_view
conversion_sign_ups_sk_ad_network_view
conversion_searches_sk_ad_network_view
conversion_level_completes_sk_ad_network_view
conversion_app_opens_sk_ad_network_view
conversion_page_views_sk_ad_network_view
conversion_subscribe_sk_ad_network_view
conversion_ad_click_sk_ad_network_view
conversion_ad_view_sk_ad_network_view
conversion_complete_tutorial_sk_ad_network_view
conversion_invite_sk_ad_network_view
conversion_login_sk_ad_network_view
conversion_share_sk_ad_network_view
conversion_reserve_sk_ad_network_view
conversion_achievement_unlocked_sk_ad_network_view
conversion_add_to_wishlist_sk_ad_network_view
conversion_spend_credits_sk_ad_network_view
conversion_rate_sk_ad_network_view
conversion_start_trial_sk_ad_network_view
conversion_list_view_sk_ad_network_view
custom_event_1_sk_ad_network_view
custom_event_2_sk_ad_network_view
custom_event_3_sk_ad_network_view
custom_event_4_sk_ad_network_view
custom_event_5_sk_ad_network_view
unknown_sk_ad_network_view SkAdNetwork conversion events with unknown Conversion Values.
conversion_assist_install_sk_ad_network_view The number of times the SKAdNetwork campaign drove an App Install, but was not the last touch before the App Install occurred.
conversion_null_sk_ad_network_view The number of SKAdNetwork conversion events with “null” Conversion Values. This indicates the campaign did not generate enough daily SKAdNetwork conversions to pass Apple’s privacy threshold.

SKAd Network Total Conversion Metrics

The following metrics return the total sum of the SKAd Network SWIPE and VIEW conversions.

Name Description
conversion_total_installs_sk_ad_network_total Total App Installs tracked via SKAd Network
conversion_ios_installs_sk_ad_network_total Exact same metric as conversion_total_installs_sk_ad_network_total
conversion_purchases_sk_ad_network_total
conversion_save_sk_ad_network_total
conversion_start_checkout_sk_ad_network_total
conversion_add_cart_sk_ad_network_total
conversion_view_content_sk_ad_network_total
conversion_add_billing_sk_ad_network_total
conversion_sign_ups_sk_ad_network_total
conversion_searches_sk_ad_network_total
conversion_level_completes_sk_ad_network_total
conversion_app_opens_sk_ad_network_total
conversion_page_views_sk_ad_network_total
conversion_subscribe_sk_ad_network_total
conversion_ad_click_sk_ad_network_total
conversion_ad_view_sk_ad_network_total
conversion_complete_tutorial_sk_ad_network_total
conversion_invite_sk_ad_network_total
conversion_login_sk_ad_network_total
conversion_share_sk_ad_network_total
conversion_reserve_sk_ad_network_total
conversion_achievement_unlocked_sk_ad_network_total
conversion_add_to_wishlist_sk_ad_network_total
conversion_spend_credits_sk_ad_network_total
conversion_rate_sk_ad_network_total
conversion_start_trial_sk_ad_network_total
conversion_list_view_sk_ad_network_total
custom_event_1_sk_ad_network_total
custom_event_2_sk_ad_network_total
custom_event_3_sk_ad_network_total
custom_event_4_sk_ad_network_total
custom_event_5_sk_ad_network_total
unknown_sk_ad_network_total SkAdNetwork conversion events with unknown Conversion Values.
conversion_assist_install_sk_ad_network_total The number of times the SKAdNetwork campaign drove an App Install, but was not the last touch before the App Install occurred.
conversion_null_sk_ad_network_total The number of SKAdNetwork conversion events with “null” Conversion Values. This indicates the campaign did not generate enough daily SKAdNetwork conversions to pass Apple’s privacy threshold.

SKAd Network Conversion Example

curl "https://adsapi.snapchat.com/v1/campaigns/5b483328-dfab-4321-be60-8ad2dfd63d35/stats?granularity=TOTAL&start_time=2021-01-21T00:00:00.000&end_time=2021-01-25T00:00:00.000&fields=impressions,spend,swipes,conversion_total_installs_sk_ad_network,conversion_purchases_sk_ad_network,conversion_add_cart_sk_ad_network"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "601d83ee00ff06ea9762c9c4f20001737e616473617069736300016275696c642d31323762373738342d312d3432302d3000010161",
    "total_stats": [
        {
            "sub_request_status": "SUCCESS",
            "total_stat": {
                "id": "5b483328-dfab-4321-be60-8ad2dfd63d35",
                "type": "CAMPAIGN",
                "granularity": "TOTAL",
                "stats": {
                    "impressions": 61295,
                    "swipes": 4528,
                    "spend": 407129814,
                    "conversion_total_installs_sk_ad_network": 1199,
                    "conversion_purchases_sk_ad_network": 6637,
                    "conversion_add_cart_sk_ad_network": 7212
                },
                "start_time": "2021-01-20T16:00:00.000-08:00",
                "end_time": "2021-01-24T16:00:00.000-08:00",
                "finalized_data_end_time": "2021-02-05T03:00:00.000-08:00"
            }
        }
    ]
}

This example fetches three specific SKAd Network conversion metrics.

Conversion Reporting

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

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

Conversion Event Stats

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

Fields Granularity Description
conversion_purchases Any # of attributed “PURCHASE” conversion events
conversion_purchases_value Any Value of attributed “PURCHASE” conversion events (microcurrency in Ad Account’s currency)
conversion_save Any # of attributed “SAVE” conversion events
conversion_save_value Any Value of attributed “SAVE” conversion events (microcurrency in Ad Account’s currency)
conversion_start_checkout Any # of attributed “START_CHECKOUT” conversion events
conversion_start_checkout_value Any Value of attributed “START_CHECKOUT” conversion events (microcurrency in Ad Account’s currency)
conversion_add_cart Any # of attributed “ADD_CART” conversion events
conversion_add_cart_value Any Value of attributed “ADD_CART” conversion events (microcurrency in Ad Account’s currency)
conversion_view_content Any # of attributed “VIEW_CONTENT” conversion events
conversion_view_content_value Any Value of attributed “VIEW_CONTENT” conversion events (microcurrency in Ad Account’s currency)
conversion_add_billing Any # of attributed “ADD_BILLING” conversion events
conversion_add_billing_value Any Value of attributed “ADD_BILLING” conversion events (microcurrency in Ad Account’s currency)
conversion_sign_ups Any # of attributed “SIGN_UP” conversion events
conversion_sign_ups_value Any Value of attributed “SIGN_UP” conversion events (microcurrency in Ad Account’s currency)
conversion_searches Any # of attributed “SEARCH” conversion events
conversion_searches_value Any Value of attributed “SEARCH” conversion events (microcurrency in Ad Account’s currency)
conversion_level_completes Any # of attributed “LEVEL_COMPLETE” conversion events
conversion_level_completes_value Any Value of attributed “LEVEL_COMPLETE” conversion events (microcurrency in Ad Account’s currency)
conversion_app_opens Any # of attributed “APP_OPEN” conversion events
conversion_app_opens_value Any Value of attributed “APP_OPEN” conversion events (microcurrency in Ad Account’s currency)
conversion_page_views Any # of attributed “PAGE_VIEW” conversion events
conversion_page_views_value Any Value of attributed “PAGE_VIEW” conversion events (microcurrency in Ad Account’s currency)
conversion_subscribe Any # of attributed “SUBSCRIBE” conversion events
conversion_subscribe_value Any Value of attributed “SUBSCRIBE” conversion events (microcurrency in Ad Account’s currency)
conversion_ad_click Any # of attributed “AD_CLICK” conversion events
conversion_ad_click_value Any Value of attributed “AD_CLICK” conversion events (microcurrency in Ad Account’s currency)
conversion_ad_view Any # of attributed “AD_VIEW” conversion events
conversion_ad_view_value Any Value of attributed “AD_VIEW” conversion events (microcurrency in Ad Account’s currency)
conversion_complete_tutorial Any # of attributed “COMPLETE_TUTORIAL” conversion events
conversion_complete_tutorial_value Any Value of attributed “COMPLETE_TUTORIAL” conversion events (microcurrency in Ad Account’s currency)
conversion_invite Any # of attributed “INVITE” conversion events
conversion_invite_value Any Value of attributed “INVITE” conversion events (microcurrency in Ad Account’s currency)
conversion_login Any # of attributed “LOGIN” conversion events
conversion_login_value Any Value of attributed “LOGIN” conversion events (microcurrency in Ad Account’s currency)
conversion_share Any # of attributed “SHARE” conversion events
conversion_share_value Any Value of attributed “SHARE” conversion events (microcurrency in Ad Account’s currency)
conversion_reserve Any # of attributed “RESERVE” conversion events
conversion_reserve_value Any Value of attributed “RESERVE” conversion events (microcurrency in Ad Account’s currency)
conversion_achievement_unlocked Any # of attributed “ACHIEVEMENT_UNLOCKED” conversion events
conversion_achievement_unlocked_value Any Value of attributed “ACHIEVEMENT_UNLOCKED” conversion events (microcurrency in Ad Account’s currency)
conversion_add_to_wishlist Any # of attributed “ADD_TO_WISHLIST” conversion events
conversion_add_to_wishlist_value Any Value of attributed “ADD_TO_WISHLIST” conversion events (microcurrency in Ad Account’s currency)
conversion_spend_credits Any # of attributed “SPENT_CREDITS” conversion events
conversion_spend_credits_value Any Value of attributed “SPENT_CREDITS” conversion events (microcurrency in Ad Account’s currency)
conversion_rate Any # of attributed “RATE” conversion events
conversion_rate_value Any Value of attributed “RATE” conversion events (microcurrency in Ad Account’s currency)
conversion_start_trial Any # of attributed “START_TRIAL” conversion events
conversion_start_trial_value Any Value of attributed “START_TRIAL” conversion events (microcurrency in Ad Account’s currency)
conversion_list_view Any # of attributed “LIST_VIEW” conversion events
conversion_list_view_value Any Value of attributed “LIST_VIEW” conversion events (microcurrency in Ad Account’s currency)
conversion_visit Any # of attributed “VISIT” conversion events
conversion_visit_value Any Value of attributed “VISIT” conversion events (microcurrency in Ad Account’s currency)
custom_event_1 Any # of attributed “CUSTOM_EVENT_1” conversion events
custom_event_1_value Any Value of attributed “CUSTOM_EVENT_1” conversion events (microcurrency in Ad Account’s currency)
custom_event_2 Any # of attributed “CUSTOM_EVENT_2” conversion events
custom_event_2_value Any Value of attributed “CUSTOM_EVENT_2” conversion events (microcurrency in Ad Account’s currency)
custom_event_3 Any # of attributed “CUSTOM_EVENT_3” conversion events
custom_event_3_value Any Value of attributed “CUSTOM_EVENT_3” conversion events (microcurrency in Ad Account’s currency)
custom_event_4 Any # of attributed “CUSTOM_EVENT_4” conversion events
custom_event_4_value Any Value of attributed “CUSTOM_EVENT_4” conversion events (microcurrency in Ad Account’s currency)
custom_event_5 Any # of attributed “CUSTOM_EVENT_5” conversion events
custom_event_5_value Any Value of attributed “CUSTOM_EVENT_5” conversion events (microcurrency in Ad Account’s currency)

Conversion breakout

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

Parameter Description
total All conversion events
web Events reported via the Snap Pixel SDK
app Events reported within an App
offline Events reported from an offline source (in-store)
total The combined events reported for web, app, offline, and on platform (Stores and Profiles)
total_off_platform The combined events reported for web, app, and offline
total_on_platform Events reported from a Snap platform source (Stores and Profiles)

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
paid_impressions
earned_impressions
total_impressions
play_time_millis
profile_clicks
shares
saves
native_leads
conversion_purchases
conversion_purchases_value
conversion_save
conversion_save_value
conversion_start_checkout
conversion_start_checkout_value
conversion_add_cart
conversion_add_cart_value
conversion_view_content
conversion_view_content_value
conversion_add_billing
conversion_add_billing_value
conversion_signups
conversion_signups_value
conversion_searches
conversion_searches_value
conversion_level_completes
conversion_level_completes_value
conversion_app_opens
conversion_app_opens_value
conversion_page_views
conversion_page_views_value
conversion_subscribe
conversion_subscribe_value
conversion_ad_click
conversion_ad_click_value
conversion_ad_view
conversion_ad_view_value
conversion_complete_tutorial
conversion_complete_tutorial_value
conversion_invite
conversion_invite_value
conversion_login
conversion_login_value
conversion_share
conversion_share_value
conversion_reserve
conversion_reserve_value
conversion_achievement_unlocked
conversion_achievement_unlocked_value
conversion_add_to_wishlist
conversion_add_to_wishlist_value
conversion_spend_credits
conversion_spend_credits_value
conversion_rate
conversion_rate_value
conversion_start_trial
conversion_start_trial_value
conversion_list_view
conversion_list_view_value
custom_event_1
custom_event_1_value
custom_event_2
custom_event_2_value
custom_event_3
custom_event_3_value
custom_event_4
custom_event_4_value
custom_event_5
custom_event_5_value
attachment_frequency YES NO YES YES. Available from 1st January 2021 YES
attachment_uniques
frequency
uniques
total_reach
earned_reach

Example for All Metrics

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

curl "https://adsapi.snapchat.com/v1/campaigns/92e1c28a-a331-45b4-8c26-fd3e0eea8c39/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b24d9c00ff0d85622341e7c60001737e616473617069736300016275696c642d34326333636139312d312d31312d390001010d",
  "total_stats": [
    {
      "sub_request_status": "success",
      "total_stat": {
        "id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
        "type": "CAMPAIGN",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 0,
          "swipes": 0,
          "spend": 0,
          "quartile_1": 0,
          "quartile_2": 0,
          "quartile_3": 0,
          "view_completion": 0,
          "screen_time_millis": 0
        }
      }
    }
  ]
}

This endpoint retrieves stats for the specified Campaign.

HTTP Request

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

Parameters

Parameter Default Description
campaign_id Campaign ID

Get Ad Squad Stats

curl "https://adsapi.snapchat.com/v1/adsquads/23995202-bfbc-45a0-9702-dd6841af52fe/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b24e5200ff0225cdf221e6c90001737e616473617069736300016275696c642d34326333636139312d312d31312d3900010106",
  "total_stats": [
    {
      "sub_request_status": "success",
      "total_stat": {
        "id": "23995202-bfbc-45a0-9702-dd6841af52fe",
        "type": "AD_SQUAD",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 0,
          "swipes": 0,
          "spend": 0,
          "quartile_1": 0,
          "quartile_2": 0,
          "quartile_3": 0,
          "view_completion": 0,
          "screen_time_millis": 0
        }
      }
    }
  ]
}

This endpoint retrieves stats for the specified Ad Squad.

HTTP Request

GET https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/stats

Parameters

Parameter Default Description
adsquad_id Ad Squad ID

Get Ad Stats

curl "https://adsapi.snapchat.com/v1/ads/e8d6217f-32ab-400f-9e54-39a86a7963e4/stats?granularity=TOTAL&fields=impressions,swipes,screen_time_millis,quartile_1,quartile_2,quartile_3,view_completion,spend"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b24ec400ff0b0a2104182f430001737e616473617069736300016275696c642d34326333636139312d312d31312d390001010f",
  "total_stats": [
    {
      "sub_request_status": "success",
      "total_stat": {
        "id": "e8d6217f-32ab-400f-9e54-39a86a7963e4",
        "type": "AD",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 0,
          "swipes": 0,
          "spend": 0,
          "quartile_1": 0,
          "quartile_2": 0,
          "quartile_3": 0,
          "view_completion": 0,
          "screen_time_millis": 0
        }
      }
    }
  ]
}

This endpoint retrieves stats for the specified Ad.

HTTP Request

GET https://adsapi.snapchat.com/v1/ads/{ad_id}/stats

Parameters

Parameter Default Description
ad_id Ad ID

Reporting Insights and Dimensions

Delivery Insights can help you understand who viewed, engaged, and took action on your ads. These insights across demographic, location, device, and interest categories can help inform optimization and increase overall campaign efficiency. Insights can be pulled for specific campaigns, ad squads, or ads; insights can also use breakdowns for multiple campaigns, ad squads, or ads at once.

Dimensions

You can get reporting insights based on different geographic, demographic, interest-based, and device-based dimensions. You can only query one dimension at a time unless you are querying age & gender which may be combined. Some of the dimensions (region/dma/make) only support Delivery metrics, for these dimensions it’s not possible to fetch conversion metrics.

Using the ​report_dimension ​query string parameter you can see Snapchat metrics based on a number of new dimensions

Category API Dimension (report_dimension) Conditions Metrics availability
Geo country Metrics broken down by ISO country code Delivery/Conversion
country,os Metrics broken down by ISO country code and Device Operating System* Delivery
region Metrics broken down by ISO country code (US only) Delivery
dma Metrics broken down by ISO country code (US only) Delivery
Demographic gender Metrics broken down by gender Delivery/Conversion
age Metrics broken down by age buckets Delivery/Conversion
age,gender Metrics broken down by age and gender Delivery/Conversion
Device os Device Operating System Delivery/Conversion
os,country Metrics broken down by Device Operating System and ISO country code (US only)* Delivery
make Device Make Delivery
Interest lifestyle_category Metrics broken down by interest category (Snapchat Lifestyle Category) Delivery

*Country/OS metrics breakdown is available from 24 October 2022

Metrics

You may pass these metrics as a comma separated list for the fields query parameter. Conversion metrics support attribution windows, swipe/view variants, and value metrics in local microcents. Note that conversion metrics are not available for the dimensions lifestyle_category, region,dma or make.

Delivery Metrics

Metric API field Description
Paid Impressions impressions Impression Count
Swipe Ups swipes Swipe-Up Count
25% Quartile quartile_1 Video Views to 25%
50% Quartile quartile_2 Video Views to 50%
75% Quartile quartile_3 Video Views to 75%
Completions view_completion Video Views to completion
Spend spend Amount Spent (micro-currency)
Video Views video_views The total number of impressions that meet the qualifying video view criteria of at least 2 seconds of consecutive watch time or a swipe up action on the Top Snap
25% Attachment Quartile attachment_quartile_1 Long Form Video Views to 25%
50% Attachment Quartile attachment_quartile_2 Long Form Video Views to 50%
75% Attachment Quartile attachment_quartile_3 Long Form Video Views to 75%
Attachment Completions attachment_view_completion Long Form Video Views to completion
Attachment View Time attachment_total_view_time_millis Total Attachment View Time (milli-seconds)
Attachment Video Views attachment_video_views Long Form Video Attachment Views
Story Opens story_opens # of times users tapped on the ad tile in the feed to view the Story Ad
Story Completes story_completes # of times users viewed through to the last Snap of your Story Ad
Shares shares # of times lens/filter was shared in a Chat or Story
Saves saves # of times lens/filter was saved to Memories

Conversion Metrics

Metric API field Description
Installs total_installs Total # of App Installs
Purchases conversion_purchases # of attributed “PURCHASE” conversion events**
Purchase Value conversion_purchases_value Value of attributed “PURCHASE” conversion events (microcurrency in Ad Account’s currency)**
Saves conversion_save # of attributed “SAVE” conversion events**
Start Checkout conversion_start_checkout # of attributed “START_CHECKOUT” conversion events**
Add To Cart conversion_add_cart # of attributed “ADD_CART” conversion events**
View Content conversion_view_content # of attributed “VIEW_CONTENT” conversion events**
Add Billing conversion_add_billing # of attributed “ADD_BILLING” conversion events**
Sign Ups conversion_sign_ups # of attributed “SIGN_UP” conversion events**
Searches conversion_searches # of attributed “SEARCH” conversion events**
Level Completes conversion_level_completes # of attributed “LEVEL_COMPLETE” conversion events**
App Opens conversion_app_opens # of attributed “APP_OPEN” conversion events**
Page Views conversion_page_views # of attributed “PAGE_VIEW” conversion events**
Subscribes conversion_subscribe # of attributed “SUBSCRIBE” conversion events++
Ad Clicks conversion_ad_click # of attributed “CONVERSION_AD_CLICK” conversion events++
Ad Views conversion_ad_view # of attributed “CONVERSION_AD_VIEW” conversion events++
Completed Tutorials conversion_complete_tutorial # of attributed “CONVERSION_COMPLETE_TUTORIAL” conversion events++
Invites Sent conversion_invite # of attributed “CONVERSION_INVITE” conversion events++
Logins conversion_login # of attributed “CONVERSION_LOGIN” conversion events++
Shares conversion_share # of attributed “CONVERSION_SHARE” conversion events++
Reservations conversion_reserve # of attributed “CONVERSION_RESERVE” conversion events++
Achievements Unlocked conversion_achievement_unlocked # of attributed “CONVERSION_ACHIEVEMENT_UNLOCKED” conversion events++
Adds to Wishlist conversion_add_to_wishlist # of attributed “CONVERSION_ADD_TO_WISHLIST” conversion events++
Credits Spent conversion_spend_credits # of attributed “CONVERSION_SPEND_CREDITS” conversion events++
Rates Submitted conversion_rate # of attributed “CONVERSION_RATE” conversion events++
Trial Starts conversion_start_trial # of attributed “CONVERSION_START_TRIAL” conversion events++
Lists Viewed conversion_list_view # of attributed “LIST_VIEW” conversion events++
Store Visits conversion_visit # of attributed “VISIT” conversion events++
Custom Event 1 custom_event_1 # of attributed “CUSTOM_EVENT_1” conversion events++
Custom Event 2 custom_event_2 # of attributed “CUSTOM_EVENT_2” conversion events++
Custom Event 3 custom_event_3 # of attributed “CUSTOM_EVENT_3” conversion events++
Custom Event 4 custom_event_4 # of attributed “CUSTOM_EVENT_4” conversion events++
Custom Event 5 custom_event_5 # of attributed “CUSTOM_EVENT_5” conversion events++

** This conversion metric is available from 1st January 2020 when using action_report_time=conversion and 1st May 2020 when using action_report_time=impression ++ This conversion metric is available from 1st of May 2020 for both action_report_time=conversion and action_report_time=impression

Insights by GEO

curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/stats/?granularity=TOTAL&breakdown=campaign&fields=impressions,swipes,conversion_purchases&report_dimension=country&start_time=2020-01-25T00:00:00-08:00&end_time=2020-01-26T00:00:00-08:00&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5e6bee5400ff0aaf11217b24900001737e616473617069736300016275696c642d31636430373832652d312d3333342d3000010128",
    "total_stats": [
        {
            "sub_request_status": "SUCCESS",
            "total_stat": {
                "id": "22225ba6-7559-4000-9663-bace8adff5f2",
                "type": "AD_ACCOUNT",
                "granularity": "TOTAL",
                "swipe_up_attribution_window": "28_DAY",
                "view_attribution_window": "1_DAY",
                "start_time": "2020-01-25T00:00:00.000-08:00",
                "end_time": "2020-01-26T00:00:00.000-08:00",
                "finalized_data_end_time": "2020-03-13T00:00:00.000-07:00",
                "breakdown_stats": {
                    "campaign": [
                        {
                            "id": "88821981-14be-4315-9832-278b27004d68",
                            "type": "CAMPAIGN",
                            "granularity": "TOTAL",
                            "start_time": "2020-01-25T00:00:00.000-08:00",
                            "end_time": "2020-01-26T00:00:00.000-08:00",
                            "dimension_stats": [
                                {
                                    "impressions": 23433,
                                    "swipes": 141,
                                    "country": "au",
                                    "conversion_purchases": 3
                                }
                            ]
                        },
                        {
                            "id": "8079bbff-8a7b-4548-8556-d726461da248",
                            "type": "CAMPAIGN",
                            "granularity": "TOTAL",
                            "start_time": "2020-01-25T00:00:00.000-08:00",
                            "end_time": "2020-01-26T00:00:00.000-08:00",
                            "dimension_stats": [
                                {
                                    "impressions": 19970,
                                    "swipes": 488,
                                    "country": "us",
                                    "conversion_purchases": 4
                                }
                            ]
                        },
                        {
                            "id": "828f739c-7f32-4013-9a92-58c6495e9438",
                            "type": "CAMPAIGN",
                            "granularity": "TOTAL",
                            "start_time": "2020-01-25T00:00:00.000-08:00",
                            "end_time": "2020-01-26T00:00:00.000-08:00",
                            "dimension_stats": [
                                {
                                    "impressions": 46068,
                                    "swipes": 74,
                                    "country": "fr",
                                    "conversion_purchases": 5
                                }
                            ]
                        }
                    ]
                },
                "split_results": []
            }
        }
    ]
}

This retrieves insights for country broken down to Campaign level using report_dimension=country.

HTTP Request

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

Parameters

Parameter Default Description
ad-account-id Ad ID
report_dimension The desired Report Dimension

Insights by DEMO

curl "https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/stats/?granularity=TOTAL&breakdown=campaign&fields=impressions,swipes,conversion_purchases&report_dimension=gender,age&start_time=2020-01-25T00:00:00-08:00&end_time=2020-01-28T00:00:00-08:00&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5e6bf19f00ff068ca7c50849650001737e616473617069736300016275696c642d31636430373832652d312d3333342d3000010121",
    "total_stats": [
        {
            "sub_request_status": "SUCCESS",
            "total_stat": {
                "id": "22225ba6-7559-4000-9663-bace8adff5f2",
                "type": "AD_ACCOUNT",
                "granularity": "TOTAL",
                "swipe_up_attribution_window": "28_DAY",
                "view_attribution_window": "1_DAY",
                "start_time": "2020-01-25T00:00:00.000-08:00",
                "end_time": "2020-01-28T00:00:00.000-08:00",
                "finalized_data_end_time": "2020-03-13T00:00:00.000-07:00",
                "breakdown_stats": {
                    "campaign": [
                        {
                            "id": "88921981-14be-4315-9832-278b27004d68",
                            "type": "CAMPAIGN",
                            "granularity": "TOTAL",
                            "start_time": "2020-01-25T00:00:00.000-08:00",
                            "end_time": "2020-01-28T00:00:00.000-08:00",
                            "dimension_stats": [
                                {
                                    "impressions": 18719,
                                    "swipes": 63,
                                    "age_bucket": "18-20",
                                    "gender": "male",
                                    "conversion_purchases": 1
                                },
                                {
                                    "impressions": 12184,
                                    "swipes": 37,
                                    "age_bucket": "21-24",
                                    "gender": "male",
                                    "conversion_purchases": 0
                                },
                                {
                                    "impressions": 25197,
                                    "swipes": 113,
                                    "age_bucket": "25-34",
                                    "gender": "male",
                                    "conversion_purchases": 1
                                },
                                {
                                    "impressions": 12363,
                                    "swipes": 147,
                                    "age_bucket": "35+",
                                    "gender": "male",
                                    "conversion_purchases": 1
                                }
                            ]
                        },
                        {
                            "id": "82d35332-00e3-4414-a125-922053d2c358",
                            "type": "CAMPAIGN",
                            "granularity": "TOTAL",
                            "start_time": "2020-01-25T00:00:00.000-08:00",
                            "end_time": "2020-01-28T00:00:00.000-08:00",
                            "dimension_stats": [
                                {
                                    "impressions": 12438,
                                    "swipes": 11,
                                    "age_bucket": "18-20",
                                    "gender": "male",
                                    "conversion_purchases": 0
                                },
                                {
                                    "impressions": 23894,
                                    "swipes": 21,
                                    "age_bucket": "21-24",
                                    "gender": "male",
                                    "conversion_purchases": 0
                                },
                                {
                                    "impressions": 31837,
                                    "swipes": 51,
                                    "age_bucket": "25-34",
                                    "gender": "male",
                                    "conversion_purchases": 0
                                },
                                {
                                    "impressions": 5277,
                                    "swipes": 24,
                                    "age_bucket": "35+",
                                    "gender": "male",
                                    "conversion_purchases": 0
                                }
                            ]
                        },
                        {
                            "id": "82c7b838-c084-4c3e-91ae-f96aa4e89008",
                            "type": "CAMPAIGN",
                            "granularity": "TOTAL",
                            "start_time": "2020-01-25T00:00:00.000-08:00",
                            "end_time": "2020-01-28T00:00:00.000-08:00",
                            "dimension_stats": [
                                {
                                    "impressions": 27826,
                                    "swipes": 44,
                                    "age_bucket": "18-20",
                                    "gender": "male",
                                    "conversion_purchases": 1
                                },
                                {
                                    "impressions": 24745,
                                    "swipes": 64,
                                    "age_bucket": "21-24",
                                    "gender": "male",
                                    "conversion_purchases": 3
                                },
                                {
                                    "impressions": 31849,
                                    "swipes": 163,
                                    "age_bucket": "25-34",
                                    "gender": "male",
                                    "conversion_purchases": 1
                                },
                                {
                                    "impressions": 23918,
                                    "swipes": 212,
                                    "age_bucket": "35+",
                                    "gender": "male",
                                    "conversion_purchases": 2
                                }
                            ]
                        }
                    ]
                },
                "split_results": []
            }
        }
    ]
}

This retrieves insights for gender and age broken down to Campaign level, using report_dimension=gender,age.

HTTP Request

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

Parameters

Parameter Default Description
ad-account-id Ad ID
report_dimension The desired Report Dimension

Reporting Insights: Dimension and Pivots

On the 20th of March 2020 we announced the deprecation of the dimension and pivots parameters, please ensure that you have switched to using report_dimension by the 20th of June 2020. After the deprecation you will still be able to use dimension and pivots to retrieve data finalized prior to the 20th June 2020.

The new parameter report_dimension is described in Reporting Insights and Dimensions.

Dimension and Pivots

You can get reporting insights based on different dimensions like GEO, DEMO, INTEREST and DEVICE by using the parameters dimension and pivots. Within each dimension, data can be broken down by different pivots. You can only query one dimension at a time. For insights breakdown, only LIFETIME granularity is supported.

Dimension Pivot Required/Optional Conditions
GEO country Yes None
region No dma has to be queried with region
dma No dma has to be queried with region
DEMO gender No At least one of gender or age_bucket has to be specified if dimension is DEMO
age_bucket No At least one of gender or age_bucket has to be specified if dimension is DEMO
INTEREST interest_category_id Yes None
interest_category_name No None
DEVICE operating_system Yes None
make No model has to be queried with make
model No model has to be queried with make

The fields that can be broken down by dimenssion and pivots are:

Field Description
impressions Impression Count
impression_composition The percent of impressions served to the insights category
uniques # of unique impressions
unique_composition The percent of uniques served to the insights category
spend Amount spent (microcurrency)
swipes Swipe up Count

Attribution windows

Attribution window is the time period in which a conversion will be counted after a user sees an ad. By default, Snap’s attribution windows are 28 days post-swipe and 1 day post-view.

Metrics and their variants

Metric Swipe variant View variant
total_installs total_installs_swipe_up total_installs_view
android_installs android_installs_swipe_up android_installs_view
ios_installs ios_installs_swipe_up ios_installs_view
conversion_purchases conversion_purchases_swipe_up conversion_purchases_view
conversion_purchases_value conversion_purchases_value_swipe_up conversion_purchases_value_view
conversion_save conversion_save_swipe_up conversion_save_view
conversion_start_checkout conversion_start_checkout_swipe_up conversion_start_checkout_view
conversion_add_cart conversion_add_cart_swipe_up conversion_add_cart_view
conversion_view_content conversion_view_content_swipe_up conversion_view_content_view
conversion_add_billing conversion_add_billing_swipe_up conversion_add_billing_view
conversion_sign_ups conversion_sign_ups_swipe_up conversion_sign_ups_view
conversion_searches conversion_searches_swipe_up conversion_searches_view
conversion_level_completes conversion_level_completes_swipe_up conversion_level_completes_view
conversion_app_opens conversion_app_opens_swipe_up conversion_app_opens_view
conversion_page_views conversion_page_views_swipe_up conversion_page_views_view
conversion_subscribe conversion_subscribe_swipe_up conversion_subscribe_view
conversion_ad_click conversion_ad_click_swipe_up conversion_ad_click_view
conversion_ad_view conversion_ad_view_swipe_up conversion_ad_view_view
conversion_complete_tutorial conversion_complete_tutorial_swipe_up conversion_complete_tutorial_view
conversion_invite conversion_invite_swipe_up conversion_invite_view
conversion_login conversion_login_swipe_up conversion_login_view
conversion_share conversion_share_swipe_up conversion_share_view
conversion_reserve conversion_reserve_swipe_up conversion_reserve_view
conversion_achievement_unlocked conversion_achievement_unlocked_swipe_up conversion_achievement_unlocked_view
conversion_add_to_wishlist conversion_add_to_wishlist_swipe_up conversion_add_to_wishlist_view
conversion_spend_credits conversion_spend_credits_swipe_up conversion_spend_credits_view
conversion_rate conversion_rate_swipe_up conversion_rate_view
conversion_start_trial conversion_start_trial_swipe_up conversion_start_trial_view
conversion_list_view conversion_list_view_swipe_up conversion_list_view_view
custom_event_1 custom_event_1_swipe_up custom_event_1_view
custom_event_2 custom_event_2_swipe_up custom_event_2_view
custom_event_3 custom_event_3_swipe_up custom_event_3_view
custom_event_4 custom_event_4_swipe_up custom_event_4_view
custom_event_5 custom_event_5_swipe_up custom_event_5_view

Allowed combinations of attribution windows

View window Swipe window 1_DAY Swipe window 7_DAY Swipe window 28_DAY
None Allowed Allowed Allowed
1_HOUR Allowed Allowed Allowed
3_HOUR Allowed Allowed Allowed
6_HOUR Allowed Allowed Allowed
1_DAY Allowed Allowed Allowed
7_DAY Not Allowed Allowed Allowed
28_DAY Not Allowed Not Allowed Allowed

Attribution windows example

curl "https://adsapi.snapchat.com/v1/campaigns/04dd5e26-7156-4e07-b2b8-2911ae3aaccc/stats?granularity=DAY&fields=impressions,spend,conversion_add_cart,conversion_add_cart_swipe_up,conversion_add_cart_view,conversion_purchases,conversion_purchases_swipe_up,conversion_purchases_view&swipe_up_attribution_window=28_DAY&view_attribution_window=7_DAY&start_time=2017-11-10T00:00:00-08:00&end_time=2017-11-12T00:00:00-08:00"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5a1e176f00ff09ef429913ea970001737e616473617069736300016275696c642d65336335336136322d312d3132312d31",
    "timeseries_stats": [
        {
            "sub_request_status": "SUCCESS",
            "timeseries_stat": {
                "id": "04dd5e26-7156-4e07-b2b8-2911ae3aaccc",
                "type": "CAMPAIGN",
                "granularity": "DAY",
                "swipe_up_attribution_window": "28_DAY",
                "view_attribution_window": "7_DAY",
                "start_time": "2017-11-10T00:00:00.000-08:00",
                "end_time": "2017-11-12T00:00:00.000-08:00",
                "finalized_data_end_time": "2017-11-27T00:00:00.000-08:00",
                "timeseries": [
                    {
                        "start_time": "2017-11-10T00:00:00.000-08:00",
                        "end_time": "2017-11-11T00:00:00.000-08:00",
                        "stats": {
                            "impressions": 63027,
                            "spend": 190136020,
                            "conversion_purchases": 13,
                            "conversion_purchases_swipe_up": 6,
                            "conversion_purchases_view": 7,
                            "conversion_add_cart": 20,
                            "conversion_add_cart_swipe_up": 8,
                            "conversion_add_cart_view": 12
                        }
                    },
                    {
                        "start_time": "2017-11-11T00:00:00.000-08:00",
                        "end_time": "2017-11-12T00:00:00.000-08:00",
                        "stats": {
                            "impressions": 74153,
                            "spend": 200905774,
                            "conversion_purchases": 10,
                            "conversion_purchases_swipe_up": 3,
                            "conversion_purchases_view": 7,
                            "conversion_add_cart": 20,
                            "conversion_add_cart_swipe_up": 5,
                            "conversion_add_cart_view": 15
                        }
                    }
                ]
            }
        }
    ]
}

This retrieves insights broken down by specified attribution windows.

Reporting for Dynamic Product Ads (DPA)

Snapchat now offers a reporting API endpoint so that advertisers can retrieve product-level reporting for Dynamic Product Ads. This report allows advertisers to understand how their campaigns, ad squads, ads delivered & performed for individual products. Reports can only be pulled with a 1 day date range for TOTAL granularity. There are two types of reports that can be retrieved. These are the full reports using the async API and the top-k report using the regular API.

Supported Breakdowns

Supported Metrics

Report Requirements

Full reports for DPA (Async)

Due to the size of reports, DPA reporting runs on Snapchat’s asynchronous API and returns a file for the full DPA breakdown. The API call to the stats endpoint for a DPA report returns a report run ID. This run ID can be used to make a subsequent call to the stats_report endpoint to check its status. Upon completion, a signed URL is generated to download the report as a CSV; this CSV has a time to live of 24 hours.

Stats request - Step 1

curl "https://adsapi.snapchat.com/v1/adaccounts/<ad_acct_id>/stats?breakdown=campaign&granularity=TOTAL&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY&start_time=2020-03-17T00:00:00-07:00&end_time=2020-03-25T00:00:00-07:00&fields=product_impressions,swipes,spend,total_installs,conversion_purchases&position_stats=false&platform_stats=false&report_dimension=product&omit_empty=true&async=true&async_format=csv" -H "Authorization: Bearer meowmeowmeow"
{
  "request_status": "SUCCESS",
  "request_id": "<ID>",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6"
      }
    }
  ]
}

Additional Request Parameters

These are the specific request parameters necessary to call the DPA Async report API

Attribute Values
report_dimension product
async true
async_format csv

Response - async_stats_report Object

Attribute Description Values
report_run_id the ID of your reporting task eg: “ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6”
async_status The current status of the reporting task. Once this changes to COMPLETED, the result field will be populated with the URL for the report. RUNNING, COMPLETED
result This contains the URL of the report file eg: “https://data-transfer.snapads.com/async-report/dpa_full/ASYNC_STATS:0efa41e1-5087-48af-8dbc-2cf8aefasdf66e6/4a6csdf1-3234-484b-b2cf-eeb6f1a63c3f.csv”

CSV request - Step 2

curl "https://adsapi.snapchat.com/v1/adaccounts/<ad_acct_id>/stats_report?report_run_id=ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6" -H "Authorization: Bearer  meowmeowmeow"

Report is running

{
  "request_status": "SUCCESS",
  "request_id": "<ID>",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6",
        "async_status": "RUNNING",
        "result": ""
      }
    }
  ]
}

Report is completed

{
  "request_status": "SUCCESS",
  "request_id": "<ID>",
  "async_stats_reports": [
    {
      "sub_request_status": "SUCCESS",
      "async_stats_report": {
        "report_run_id": "ASYNC_STATS:11111e-32222-48af-8dbc-2cf8a8904ee6",
        "async_status": "COMPLETED",
        "result": "https://data-transfer.snapads.com/async-report/dpa_full/ASYNC_STATS:0efa41e1-5087-48af-8dbc-2cf8aefasdf66e6/4a6csdf1-3234-484b-b2cf-eeb6f1a63c3f.csv"
      }
    }
  ]
}

Top-K report for DPA

To support UI reporting and understand the performance of DPA among products with the highest level of spend, Snapchat supports a Top-K report, which will return the top 50 products per entity by impression volume (Campaign, Ad Set, and Ad). This API is similar to the standard reporting API used for non DPA ads.

Additional Request Parameters

These are the specific request parameters necessary to call the DPA Async report API

Attribute Values
report_dimension product_topk
curl "https://adsapi.snapchat.com/v1/adaccounts/<ad_acct_id>/stats?breakdown=campaign&granularity=TOTAL&swipe_up_attribution_window=28_DAY&view_attribution_window=1_DAY&start_time=2020-03-17T00:00:00-07:00&end_time=2020-03-25T00:00:00-07:00&fields=product_impressions,swipes,spend,total_installs,conversion_purchases&position_stats=false&platform_stats=false&report_dimension=product_topk&omit_empty=true" -H "Authorization: Bearer meowmeowmeow"
{
    "request_status": "SUCCESS",
    "request_id": "5fb4467d00ff07d2b1b1968d810001737e616473617069736300016275696c642d36393939316436622d312d3430332d3100010142",
    "total_stats": [
        {
            "sub_request_status": "SUCCESS",
            "total_stat": {
                "id": "<ID>",
                "type": "AD_ACCOUNT",
                "granularity": "TOTAL",
                "swipe_up_attribution_window": "28_DAY",
                "view_attribution_window": "1_DAY",
                "start_time": "2020-10-27T00:00:00.000-07:00",
                "end_time": "2020-10-29T00:00:00.000-07:00",
                "finalized_data_end_time": "2020-11-17T00:00:00.000-08:00",
                "breakdown_stats": {
                    "campaign": [
                        {
                            "id": "<CAMPAIGN_ID>",
                            "type": "CAMPAIGN",
                            "granularity": "TOTAL",
                            "start_time": "2020-10-27T00:00:00.000-07:00",
                            "end_time": "2020-10-29T00:00:00.000-07:00",
                            "dimension_stats": [
                                {
                                    "product_id": "56e39d8f1b0dd675f10e0131",
                                    "product_impressions": 84051
                                },
                                {
                                    "product_id": "577dfc15dac4a378150ebab0",
                                    "product_impressions": 55271
                                },
                                {
                                    "product_id": "5694f07db06a78118dd2bbae",
                                    "product_impressions": 47643
                                },
                                {
                                    "product_id": "56dff400cec25a1a9e1271cd",
                                    "product_impressions": 26599
                                },
                                {
                                    "product_id": "56eebe757505925c618e9807",
                                    "product_impressions": 23737
                                },
                                {
                                    "product_id": "569cbb6f16805211bb1f7750",
                                    "product_impressions": 21171
                                },
                                {
                                    "product_id": "57a6fad104e0d075a6084059",
                                    "product_impressions": 19274
                                },
                                {
                                    "product_id": "57ab01b93999d9602c743b8e",
                                    "product_impressions": 12256
                                },
                                {
                                    "product_id": "57ad3c3fd227704b8bab09dc",
                                    "product_impressions": 12248
                                },
                                {
                                    "product_id": "57a6c97c5bd8ec7787ea328f",
                                    "product_impressions": 11340
                                },
                                {
                                    "product_id": "569f56793fe3625b0cf56bd9",
                                    "product_impressions": 7433
                                },
                                {
                                    "product_id": "56e14676ae8c93398a13a7d3",
                                    "product_impressions": 6597
                                },
                                {
                                    "product_id": "56f24379f5f899740ec4c0b5",
                                    "product_impressions": 6438
                                },
                                {
                                    "product_id": "575645a524a8f27640d3d40c",
                                    "product_impressions": 6419
                                },
                                {
                                    "product_id": "5700b35e5581e05ce0b4adc3",
                                    "product_impressions": 6056
                                },
                                {
                                    "product_id": "576130685d3faf6218fd8dac",
                                    "product_impressions": 5701
                                },
                                {
                                    "product_id": "579eba20a037085566e39683",
                                    "product_impressions": 1980
                                },
                                {
                                    "product_id": "57adae01b1ce26244dd4012c",
                                    "product_impressions": 1707
                                },
                                {
                                    "product_id": "57a02216e3ada7734f02b275",
                                    "product_impressions": 1185
                                },
                                {
                                    "product_id": "579b220904af45576fae20a3",
                                    "product_impressions": 1083
                                },
                                {
                                    "product_id": "56b1adcdac5bc550738df9fb",
                                    "product_impressions": 857
                                },
                                {
                                    "product_id": "57623c6d823409625004be5e",
                                    "product_impressions": 736
                                },
                                {
                                    "product_id": "57b14c09689ce95b71558fff",
                                    "product_impressions": 671
                                },
                                {
                                    "product_id": "5779ced99bfad279a9783889",
                                    "product_impressions": 573
                                },
                                {
                                    "product_id": "56c29339a3537416ae4b7822",
                                    "product_impressions": 556
                                }
                                ...
                            ]
                        }
                    ]
                },
                "split_results": []
            }
        }
    ]
}

Viewability Metrics

Viewability Metrics are available given the following criteria;

Metrics

Metric API field Description
Viewable Impressions viewable_impressions Number of impressions that were 100% viewable on a user’s screen for 1 second for display ads or 2 seconds for video ads.
Non-Viewable Impressions non_viewable_impressions Number of impressions that did not meet the criteria for a viewable impression
Viewable Rate viewable_rate The percentage of the time that your paid Snap Ad impression met the qualifying viewable impression criteria
Measured Impressions measured_impressions Number of impressions that were measured for viewability
Gross Impressions gross_impressions Total impressions delivered, this includes invalid traffic which is excluded from spend & all other delivery metrics.
Paid Impressions paid_impressions The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter’s viewing session. These impressions are net of invalid traffic.

Audience filters

Audience filters were deprecated on 1 February 2023, this reporting information is preserved for Audience Filters created prior to the deprecation.

Field Description Availability
paid_impressions The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter’s viewing session Real Time
earned_impressions The number of times your ad was viewed after being shared by a Snapchatter via Chat or Stories Within 24 hours
shares The number of times your ad was shared via Chat or Stories Real Time
saves The number of times your ad was saved to Memories Real Time
spend The total spend delivered in microcurrency Real Time
uniques The number of unique paid impressions Within 24 hours

Stats are available at the Ad, Ad Squad and Campaign levels and are supported for all granularities: HOUR, DAY, TOTAL and LIFETIME.

curl "https://adsapi.snapchat.com/v1/adsquads/419d41d7-e4d4-4c13-803c-55e140a0ec1c/stats?granularity=LIFETIME&fields=paid_impressions,shares,saves,spend,uniques,earned_impressions"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "59b9cde600ff04b518a3c18db20001737e616473617069736300016275696c642d31386433356533662d312d3130302d3100010148",
    "lifetime_stats": [
        {
            "sub_request_status": "SUCCESS",
            "lifetime_stat": {
                "id": "419d41d7-e4d4-4c13-803c-55e140a0eb1c",
                "type": "AD_SQUAD",
                "granularity": "LIFETIME",
                "stats": {
                    "uniques": 186219,
                    "spend": 247184000,
                    "earned_impressions": 196140,
                    "paid_impressions": 199290,
                    "shares": 5762,
                    "saves": 799
                },
                "start_time": "2016-09-26T00:00:00.000-07:00",
                "end_time": "2017-09-13T00:00:00.000-07:00",
                "finalized_data_end_time": "2017-09-13T00:00:00.000-07:00"
            }
        }
    ]
}

HTTP Request

GET https://adsapi.snapchat.com/v1/adsquads/{adsquad-id}/stats

Parameters

Parameter Description
adsquad-id Audience filter Ad squad ID

Create Lead Gen Report

This request initiates a lead gen report for an Ad Account given the selected start time and end time, the request returns a Report id in the form of report_run_id which is then used to retrieve the report itself.

Data collected via Lead Gen Ads is not stored for more than 30 days, this also means that the start time can’t be more than 30 days in the past.

curl -X POST  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/leads_report?async_format=csv&start_time=2021-12-01T00:00:00-07:00&end_time=2021-12-14T00:00:00-07:00

The above command returns a report_run_id:

{
   "request_status": "SUCCESS",
   "request_id": "61b8c10a00ff08449824e366290001737e616473617069736300016275696c642d38333537336364642d312d3530332d3000010159",
   "async_stats_reports": [
       {
           "sub_request_status": "SUCCESS",
           "async_stats_report": {
               "report_run_id": "ASYNC_STATS:2e480f4f-0c2a-463c-a883-841f88175449",
               "async_status": "STARTED"
           }
       }
   ]
}

HTTP Request

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

Parameters

Parameter Default value Description
async_format csv
start_time Start time in ISO format
end_time End time in ISO format

Fetch Lead Gen Report

This request uses the report_run_id in order to fetch the status of a report.

If the report is ready the request returns the URL of a list of leads in CSV format, the async_status indicates whether the report is completed and ready to be downloaded. If the report is ready the value of the async_status is COMPLETED, if the report is still running the async_status will be RUNNING.

When a report is completed the url for downloading the data is found in the result attribute. This URL is valid for 48 hours.

curl "https://adsapi.snapchat.comv1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/leads_report?report_run_id=ASYNC_STATS:7766eab2-643e-4117-8b58-c9ee3fe854f3" \
  -H "Authorization: Bearer meowmeowmeow"

Example #1 - Report in progress

{
   "request_status": "SUCCESS",
   "request_id": "61b8bf2d00ff07c8f092caf50b0001737e616473617069736300016275696c642d38333537336364642d312d3530332d3000010142",
   "async_stats_reports": [
       {
           "sub_request_status": "SUCCESS",
           "async_stats_report": {
               "report_run_id": "ASYNC_STATS:7766eae2-643e-4117-8b58-c9ee3fe854f3",
               "async_status": "RUNNING"
           }
       }
   ]
}
curl "https://adsapi.snapchat.comv1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/leads_report?report_run_id=ASYNC_STATS:7766eeb2-643e-4117-8b58-c9ee3fe854f3" \
  -H "Authorization: Bearer meowmeowmeow"

Example #2 - Completed report

{
   "request_status": "SUCCESS",
   "request_id": "61b8bf2d00ff07c8f092caf50b0001737e616473617069736300016275696c642d38333537336364642d312d3530332d3000010142",
   "async_stats_reports": [
       {
           "sub_request_status": "SUCCESS",
           "async_stats_report": {
               "report_run_id": "ASYNC_STATS:7766eeb2-643e-4117-8b58-c9ee3fe854f3",
               "async_status": "COMPLETED",
               "result": "https://data-transfer.snapads.com/async-report/native_lead/ASYNC_STATS:7766eeb2-643e-4117-8b58-c9ee3fe854f3/00ea875b-1645-4fe8-8825-aa7a351b260b.csv"
           }
       }
   ]
}

HTTP Request

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

Parameters

Parameter Default value Description
report_run_id Report id The Report id returned by API request to initiate a report

Lead Gen Report

This is a list of fields in the Lead Gen Report and their properties.

Field Name Type Max Length Required? Description Example
Date Datetime 17 Yes Date that lead was submitted. The timestamp is truncated to the beginning of the local day and the time is always “00:00:00”
Format: “yyyy-MM-dd 00:00:00”
2022-05-11 00:00:00
Ad Account Id String 36 Yes Ad account ID associated with the ad that generated the lead. Hyphen separated UUID string. f0d4666f-9f60-4df7-94c8-423ca55b2a17
Campaign Id String 36 Yes Campaign ID associated with ad that generated the lead. Hyphen separated UUID string. 033fe5aa-59b4-423d-8ab5-b7a7cf6c5242
Ad Set Id String 36 Yes Ad Set ID associated with ad that generated the lead. Hyphen separated UUID string. ebad6081-f387-4bce-b6dc-9ea4d2cbefbc
Ad Id String 36 Yes Ad ID associated with ad that generated the lead. Hyphen separated UUID string. ca72035c-9f8d-409b-abee-5e2e0c943f9c
First Name String Yes First name of Snapchat User Jane
Last Name String Yes Last name of Snapchat User Smith
Phone Number String Yes (Either Email Address or Phone Number) ex: 818-555-1234, +13105558765
*Not all formatted the same
818-555-1234
+13105558765
Email Address String Yes (Either Email Address or Phone Number) Email address of Snapchat user johndoe@gmail.com
Address Line 1 String No Address of Snapchat user, Line 1 19330 25th Ave
Address Line 2 String No Address of Snapchat user, Line 2 Unit 3
Address Level 1 String No Address city or town Seattle
Address Level 2 String No Address state, province, or region WA
Postal Code String No Postal code of Snapchat user 94012
Birthday Date 10 No Snapchat user’s birthdate. Formatted “MM/DD/YYYY” 05/20/1998
Job Title String No Job title Marketing Manager
Company Name String No Company name Snap, Inc.
Custom Field 1 String No Can be one of the following based on the type of Custom Question:
Single-select: key-value object that contains the answer that the user selected and “true”: {answer:true}
Multi-select: key-value object that contains all of the answers that the user selected and “true”: {answer1:true, answer2: true, answer3: true, answer4:true}
Short Answer: String that contains the answer that the user entered into the form.
Date Widget: The date that the user entered in the format “MM/DD/YYYY”
{Pizza:true}
{Pizza:true, Sushi:true, Hamburgers:true}
This is what I entered into the form
01/02/2022
Custom Field 2 String No Can be one of the following based on the type of Custom Question:
Single-select: key-value object that contains the answer that the user selected and “true”: {answer:true}
Multi-select: key-value object that contains all of the answers that the user selected and “true”: {answer1:true, answer2: true, answer3: true, answer4:true}
Short Answer: String that contains the answer that the user entered into the form.
Date Widget: The date that the user entered in the format “MM/DD/YYYY”
{Pizza:true}
{Pizza:true, Sushi:true, Hamburgers:true}
This is what I entered into the form
01/02/2022
Custom Field 3 String No Can be one of the following based on the type of Custom Question:
Single-select: key-value object that contains the answer that the user selected and “true”: {answer:true}
Multi-select: key-value object that contains all of the answers that the user selected and “true”: {answer1:true, answer2: true, answer3: true, answer4:true}
Short Answer: String that contains the answer that the user entered into the form.
Date Widget: The date that the user entered in the format “MM/DD/YYYY”
{Pizza:true}
{Pizza:true, Sushi:true, Hamburgers:true}
This is what I entered into the form
01/02/2022
Consent 1 String Disclaimers: 80
Answer: 5
Total: 86
No Disclaimer in the consent section of the form and the user’s response. Data is a key-value string in the following format:
disclaimer:answer
“answer” will be “true” if the user consented and “false” if they did not consent.
do you consent?:true
https://www.example.com:false
Consent 2 String Disclaimers: 80
Answer: 5
Total: 86
No Disclaimer in the consent section of the form and the user’s response. Data is a key-value string in the following format:
disclaimer:answer
“answer” will be “true” if the user consented and “false” if they did not consent.
do you consent?:true
https://www.example.com:false

Example Lead Gen Report

Here is an example Lead Gen Report .csv file. All the sample data is made-up; no actual user data is included.

Audit Logs

For certain entities you can retrieve change logs which allows you to see all the changes made to the entity. You should always use pagination when fetching change logs for an entity.

Entities supported right now are Campaign, AdSquad, Ad, Creative and Dynamic Templates. Change logs are only availabe from the 16 July 2019 and onwards.

Fetch the change logs for a Campaign

curl "https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/external_changelogs?limit=50" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5d2f4a2e00ff0b2d2797e383a20001737e616473617069736300016275696c642d32613361333938642d312d3237332d3100010126",
    "paging": {},
    "changelogs": [
        {
            "sub_request_status": "SUCCESS",
            "changelog": {
                "id": "f9fd14cf-1bb0-4592-beeb-9d7e358e746b",
                "updated_at": "2019-07-17T16:17:30.194Z",
                "created_at": "2019-07-17T16:17:30.194Z",
                "name": "Badger Campaign - July 2019",
                "action": "UPDATED",
                "user_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
                "email": "honey.badger@hooli.com",
                "event_at": "2019-07-17T16:17:29.991Z",
                "app_id": "87947032-5fbd-46a7-ba60-073ca8efefbb",
                "app_name": "Honey badger App",
                "entity_id": "dcc3f407-7049-47aa-8300-6cce946ed04e",
                "entity_type": "CAMPAIGN",
                "update_value_records": {
                    "status": {
                        "before_value": "\"ACTIVE\"",
                        "after_value": "\"PAUSED\""
                    }
                }
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "changelog": {
                "id": "3cd457c6-077d-4d4b-9647-73a97045e709",
                "updated_at": "2019-07-17T15:54:59.955Z",
                "created_at": "2019-07-17T15:54:59.955Z",
                "name": "Badger Campaign - July 2019",
                "action": "UPDATED",
                "user_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
                "email": "honey.badger@hooli.com",
                "event_at": "2019-07-17T15:54:59.755Z",
                "app_id": "87947032-5fbd-46a7-ba60-073ca8efefbb",
                "app_name": "Honey badger App",
                "entity_id": "dcc3f407-7049-47aa-8300-6cce946ed04e",
                "entity_type": "CAMPAIGN",
                "update_value_records": {
                    "end_time": {
                        "after_value": "1563580491000"
                    }
                }
            }
        }
    ]
}

This endpoint retrieves the latest 50 changes to the Campaign entity.

HTTP Request

GET https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/external_changelogs?limit=50

Parameters

Parameter Default Description
campaign_id Campaign ID

Fetch the change logs for an AdSquad

curl "https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/external_changelogs?limit=50" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5d2f495400ff05e47e72eb0f710001737e616473617069736300016275696c642d32613361333938642d312d3237332d310001011a",
    "paging": {},
    "changelogs": [
        {
            "sub_request_status": "SUCCESS",
            "changelog": {
                "id": "ae2161fb-737a-4f3c-9a3d-e6c83d9c9e30",
                "updated_at": "2019-07-17T15:58:40.150Z",
                "created_at": "2019-07-17T15:58:40.150Z",
                "name": "Badger Ad Squad - July 2019",
                "action": "UPDATED",
                "user_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
                "email": "honey.badger@hooli.com",
                "event_at": "2019-07-17T15:58:39.872Z",
                "app_id": "e9bdc78d-81fa-4470-8f6b-2a3d6f0487b3",
                "app_name": "Honey badger App",
                "entity_id": "c478150d-b177-4ecb-938d-f5157375f937",
                "entity_type": "AD_SQUAD",
                "update_value_records": {
                    "bid_micro": {
                        "before_value": "868402",
                        "after_value": "876174"
                    }
                }
            }
        }
    ]
}

This endpoint retrieves the latest 50 changes to the AdSquad entity.

HTTP Request

GET https://adsapi.snapchat.com/v1/adsquads/{adsquad_id}/external_changelogs?limit=50

Parameters

Parameter Default Description
adsquad_id AdSquad ID

Fetch the change logs for an Ad

curl "https://adsapi.snapchat.com/v1/ads/{ad_id}/external_changelogs?limit=50" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5d39e22900ff08cd2599670abb0001737e616473617069736300016275696c642d30633939333234362d312d3237352d300001014c",
    "paging": {},
    "changelogs": [
        {
            "sub_request_status": "SUCCESS",
            "changelog": {
                "id": "36f4b88b-1c24-41f5-af86-24983795edd7",
                "updated_at": "2019-07-25T17:08:51.279Z",
                "created_at": "2019-07-25T17:08:51.279Z",
                "name": "Badger Holiday Ad 2019",
                "action": "UPDATED",
                "user_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
                "email": "honey.badger@hooli.com",
                "event_at": "2019-07-25T17:08:51.030Z",
                "app_id": "87947032-5fbd-46a7-ba60-073ca8efefbb",
                "app_name": "Honey badger App",
                "entity_id": "cd88b368-35a3-46f4-b37f-2f1a72db2692",
                "entity_type": "AD",
                "update_value_records": {
                    "status": {
                        "before_value": "\"ACTIVE\"",
                        "after_value": "\"PAUSED\""
                    }
                }
            }
        }
    ]
}

This endpoint retrieves the latest 50 changes to the Ad entity.

HTTP Request

GET https://adsapi.snapchat.com/v1/ads/{ad_id}/external_changelogs?limit=50

Parameters

Parameter Default Description
ad_id Ad ID

Fetch the change logs for a Creative

curl "https://adsapi.snapchat.com/v1/creatives/{creative_id}/external_changelogs?limit=50" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5d39de6000ff01c2268bd5c37b0001737e616473617069736300016275696c642d30633939333234362d312d3237352d300001010a",
    "paging": {},
    "changelogs": [
        {
            "sub_request_status": "SUCCESS",
            "changelog": {
                "id": "a94cb9ed-0171-402a-aee7-ffecae0ce7bc",
                "updated_at": "2019-07-17T16:27:00.717Z",
                "created_at": "2019-07-17T16:27:00.717Z",
                "name": "Badger Rush",
                "action": "UPDATED",
                "user_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
                "email": "honey.badger@hooli.com",
                "event_at": "2019-07-17T16:27:00.566Z",
                "app_id": "e9bdc78d-81fa-4470-8f6b-2a3d6f0487b3",
                "app_name": "Honey Badger App",
                "entity_id": "6475383b-cb70-4353-93b2-b227054169ae",
                "entity_type": "CREATIVE",
                "update_value_records": {
                    "call_to_action": {
                        "before_value": "\"MORE\"",
                        "after_value": "\"SIGN UP\""
                    }
                }
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "changelog": {
                "id": "72b18e3a-598a-4e29-a288-980613de3714",
                "updated_at": "2019-07-17T16:07:00.985Z",
                "created_at": "2019-07-17T16:07:00.985Z",
                "name": "Badger Rush",
                "action": "CREATED",
                "user_id": "a71cfcae-895d-4314-9460-e2ffd2515dd0",
                "email": "honey.badger@hooli.com",
                "event_at": "2019-07-17T16:07:00.629Z",
                "app_id": "e9bdc78d-81fa-4470-8f6b-2a3d6f0487b3",
                "app_name": "Honey Badger App",
                "entity_id": "6475383b-cb70-4353-93b2-b227054169ae",
                "entity_type": "CREATIVE"
            }
        }
    ]
}

This endpoint retrieves the latest 50 changes to the Creative entity.

HTTP Request

GET https://adsapi.snapchat.com/v1/creatives/{creative_id}/external_changelogs?limit=50

Parameters

Parameter Default Description
creative_id Creative ID

Fetch the change logs for a Dynamic Template

curl "https://adsapi.snapchat.com/v1/dynamic_templates/{dynamic_template_id}/external_changelogs?limit=50" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5d39e22900ff08cd2599670abb0001737e616473617069736300016275696c642d30633939333234362d312d3237352d300001014c",
    "paging": {},
    "changelogs": [
        {
            "sub_request_status": "SUCCESS",
            "changelog": {
                "id": "4f5f0eb1-92dd-4ae4-9d86-135ca516e696",
                "updated_at": "2023-10-17T19:28:18.445Z",
                "created_at": "2023-10-17T19:28:18.445Z",
                "name": "Badger template",
                "action": "CREATED",
                "email": "honey.badger@hooli.com",
                "event_at": "2023-10-17T19:28:17.912Z",
                "app_id": "e9bdc78d-81fa-4470-8f6b-2a3d6f0487b3",
                "app_name": "Honey badger App",
                "entity_id": "f0a30c08-7613-4d41-a5fa-d8a0382bcced",
                "entity_type": "DYNAMIC_TEMPLATE"
            }
        }
    ]
}

This endpoint retrieves the latest 50 changes to the Dynamic Template entity.

HTTP Request

GET https://adsapi.snapchat.com/v1/dynamic_templates/{dynamic_template_id}/external_changelogs?limit=50

Parameters

Parameter Default Description
dynamic_template_id Dynamic Template ID

Errors

The API uses the following error codes:

Error Code Meaning
400 Bad Request – Your request sucks
401 Unauthorized – Your API key is wrong
403 Forbidden – The kitten requested is hidden for administrators only
404 Not Found – The specified kitten could not be found
405 Method Not Allowed – You tried to access a kitten with an invalid method
406 Not Acceptable – You requested a format that isn’t json
410 Gone – The kitten requested has been removed from our servers
418 I’m a teapot
429 Too Many Requests – You’re requesting too many kittens! Slow down!
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarially offline for maintanance. Please try again later.

Version

The API is versioned (you’re welcome). The current version is v1.

Rate Limits

The Snapchat Marketing API implements rate limits to ensure infrastructure stability.

Rate limits are implemented both at App and Token level, the App is able to support an overall average volume of 20 requests/second, individual Access tokens issued by the App can make requests at an average of 10 requests/second.

429 Error Code

If you reach the rate limit, you will start receiving an HTTP 429 Too Many Requests response.

In a scenario where your application regularly generates HTTP 429 Too Many Requests responses, you need to lower the rate at which your App is sending requests to the API.

Lenses

Lens AR experiences are a powerful and memorable way to connect with consumers on a massive scale using augmented reality.

Lens Implementation Details

Create a Campaign

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{"campaigns": [{"name": "Lens Campaign", "ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1dab", "status": "ACTIVE", "start_time": "2016-08-11T22:00:00.000Z"}]}' \
   "https://adsapi.snapchat.com/v1/adaccounts/3b0fbace-04b4-4f04-a425-33b5e0af1dab/campaigns"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b002ad00ff07e1f50fd2267f0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
  "campaigns": [
    {
      "sub_request_status": "success",
      "campaign": {
        "id": "5b48880f-bf65-495c-9810-2f4763add4cb",
        "updated_at": "2020-02-04T05:33:33.876Z",
        "created_at": "2020-02-04T05:33:33.876Z",
        "name": "Lens Campaign",
        "ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1dab",
        "status": "ACTIVE",
        "start_time": "2020-02-01T22:00:00.000Z"
      }
    }
  ]
}

This will create a campaign within a specified ad account, note Ad Squads with the type LENS cannot be mixed with other types of Ad Squads (Snap Ads, Audience filters etc).

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Create a Lens Ad Squad

Attribute Description Required Possible Values
campaign_id Campaign ID R
name Ad Squad name R
billing_event Billing Event R IMPRESSION
bid_micro Max Bid (micro-currency) R
auto_bid Allow Snapchat to automatically set the bid to recommended amount O (One of auto_bid, target_bid or bid_micro must be set) true/false.
target_bid Allows Snapchat to adjust the bid aiming to keep your average CPA at or below the amount set by the ad set end date O (One of auto_bid, target_bid or bid_micro must be set) true/false.
pixel_id Pixel to be associated with the Ad Squad O
start_time Start time R
end_time End time R
optimization_goal Optimization Goal R IMPRESSIONS
placement_v2.config Placement R CUSTOM
placement_v2.platforms Placement R SNAPCHAT
placement_v2.snapchat_positions Placement R CAMERA
status Ad Squad status R ACTIVE, PAUSED
type Ad Squad Type R LENS
targeting Targeting spec R Any valid targeting options
curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{"adsquads": [{"name": "Lens adsquad","status": "ACTIVE","campaign_id": "5b48880f-bf65-495c-9810-2f4763add4cb","type": "LENS","placement_v2": {"config": "CUSTOM","platforms": ["SNAPCHAT"],"snapchat_positions": ["CAMERA"]},"billing_event": "IMPRESSION","bid_micro": "200000000","daily_budget_micro": "2000000000","start_time": "2020-08-15T12:16:17.444-07:00","end_time": "2020-08-19T12:16:17.444-07:00","optimization_goal": "IMPRESSIONS","targeting": {"regulated_content": "false","demographics": [{"min_age": "21","max_age": "24"}],"geos": [{"country_code": "us"}]}}]}' \
  https://adsapi.snapchat.com/v1/campaigns/5b48880f-bf65-495c-9810-2f4763add4cb/adsquads

The above request returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5e3c0a3d00ff077b3836beabb80001737e616473617069736300016275696c642d62343864336664332d312d3332332d3000010151",
    "adsquads": [
        {
            "sub_request_status": "SUCCESS",
            "adsquad": {
                "id": "caff7533-52e1-4412-9ef2-18232dbcd1ba",
                "updated_at": "2020-02-06T12:44:45.818Z",
                "created_at": "2020-02-06T12:44:45.818Z",
                "name": "Lens adsquad",
                "status": "ACTIVE",
                "campaign_id": "5b48880f-bf65-495c-9810-2f4763add4cb",
                "type": "LENS",
                "targeting": {
                    "regulated_content": false,
                    "demographics": [
                        {
                            "min_age": "21",
                            "max_age": "24"
                        }
                    ],
                    "geos": [
                        {
                            "country_code": "us"
                        }
                    ]
                },
                "targeting_reach_status": "VALID",
                "placement_v2": {
                    "config": "CUSTOM",
                    "platforms": [
                        "SNAPCHAT"
                    ],
                    "snapchat_positions": [
                        "CAMERA"
                    ]
                },
                "billing_event": "IMPRESSION",
                "bid_micro": 200000000,
                "auto_bid": false,
                "target_bid": false,
                "daily_budget_micro": 2000000000,
                "start_time": "2020-08-15T19:16:17.444Z",
                "end_time": "2020-08-19T19:16:17.444Z",
                "optimization_goal": "IMPRESSIONS",
                "delivery_constraint": "DAILY_BUDGET",
                "pacing_type": "STANDARD"
            }
        }
    ]
}

This creates an Ad Squad within a Campaign, note Ad Squads with the type LENS cannot be mixed with other types of Ad Squads (Snap Ads, Audience filters etc).

HTTP Request

POST https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads

Parameters

Parameter Default Description
campaign_id Campaign ID

Lens Media

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

Lens Media Attributes

These attributes are unique to the Media type LENS_PACKAGE

Attribute Description Possible Values
type The Media type LENS_PACKAGE
lens_package_metadata.lens_icon_media_id Media ID of the lens icon
lens_package_metadata.default_camera Default camera when lens opens BOTH, FACE, WORLD

Create the Creative - Lens

When a Lens is created in Snapchat Lens Studio, both the Media and the Creative will automatically be set up. You can however re-use the Lens media if you wish to set up a new Creative.

Attributes

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
name Creative name R
top_snap_media_id Media ID of type LENS_PACKAGE R
type Creative Type R LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_WEB_VIEW
ad_product Ad product R LENS
brand_name Brand Name R (required but not displayed) 25 characters max
headline Headline R (required but not displayed) 34 characters max
curl -X POST  \
  -d '{"creatives": [{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1","name" : "Honey Badger Lens","type": "LENS","top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01","ad_product": "LENS","headline": "Try the Honey Badger Lens","brand_name": "Honey Badger"}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/creatives

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5e3c5e7a00ff07ac2c051bd68e0001737e616473617069736300016275696c642d62343864336664332d312d3332332d3000010118",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "0091127a-1c58-4b0b-981d-d419d65cc87c",
                "updated_at": "2020-02-06T18:44:12.044Z",
                "created_at": "2020-02-06T18:44:12.044Z",
                "name": "Honey Badger Lens",
                "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
                "type": "LENS",
                "packaging_status": "SUCCESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "Try the Honey Badger Lens",
                "brand_name": "Honey Badger",
                "render_type": "STATIC",
                "top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01",
                "top_snap_crop_position": "MIDDLE",
                "ad_product": "LENS"
            }
        }
    ]
}

This creates a new Creative of the type LENS where the attribute top_snap_media_id is of the type LENS_PACKAGE.

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Create the Creative - Lens with App Install Attachment

When a Lens is created in Snapchat Lens Studio or Lens Web Builder, both the Media and the Creative will automatically be set up, you can however re-use the Lens media if you wish to set up a new Creative.

Attributes

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
name Creative name R
top_snap_media_id Media ID of type LENS_PACKAGE R
type Creative Type R LENS_APP_INSTALL
ad_product Ad product R LENS
brand_name Brand Name R (required but not displayed) 25 characters max
headline Headline R (required but not displayed) 34 characters max
call_to_action Call to Action R Please refer to the Creative type to CTA mapping table

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
product_page_id Custom product page ID from iOS App Store. O 45812c9b-c296-43d3-c6a0-c5a02f74bf6e
curl -X POST  \
  -d '{"creatives": [{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1","name" : "Honey Badger Lens with App Install Attachment","type": "LENS_APP_INSTALL","top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01","ad_product": "LENS","headline": "Try the Honey Badger Lens","brand_name": "Honey Badger","call_to_action": "INSTALL_NOW","app_install_properties": {"app_name": "Bitmoji - Your Personal Emoji","ios_app_id": "868077558","android_app_url": "com.bitstrips.imoji","icon_media_id": "73b5deb6-5b2c-43b4-b60d-983bc344a4a2"}}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/creatives

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5e42e3c700ff04d097d68c02810001737e616473617069736300016275696c642d63343664356339642d312d3332352d300001011a",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "1deb9eda-83bb-419d-a86c-67e2a7025385",
                "updated_at": "2020-02-11T17:26:32.402Z",
                "created_at": "2020-02-11T17:26:32.402Z",
                "name": "Honey Badger Lens with App Install Attachment",
                "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
                "type": "LENS_APP_INSTALL",
                "packaging_status": "SUCCESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "Try the Honey Badger Lens",
                "brand_name": "Honey Badger",
                "call_to_action": "INSTALL_NOW",
                "render_type": "STATIC",
                "top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01",
                "top_snap_crop_position": "MIDDLE",
                "app_install_properties": {
                    "app_name": "Bitmoji - Your Personal Emoji",
                    "ios_app_id": "868077558",
                    "android_app_url": "com.bitstrips.imoji",
                    "icon_media_id": "73b5deb6-5b2c-43b4-b60d-983bc344a4a2"
                },
                "ad_product": "LENS"
            }
        }
    ]
}

This creates a new Creative of the type LENS_APP_INSTALL where the attribute top_snap_media_id is of the type LENS_PACKAGE, and where the app_install_properties specify the attributes for the App Install Attachment.

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Attributes

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
name Creative name R
top_snap_media_id Media ID of type LENS_PACKAGE R
type Creative Type R LENS_DEEP_LINK
ad_product Ad product R LENS
brand_name Brand Name R (required but not displayed) 25 characters max
headline Headline R (required but not displayed) 34 characters max
call_to_action Call to Action R Please refer to the Creative type to CTA mapping table

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
product_page_id Custom Product Page ID on iOS App Store O
curl -X POST  \
  -d '{"creatives": [{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1","name" : "A new Lens with Deep Link Attachment","type": "LENS_DEEP_LINK","top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01","ad_product": "LENS","headline": "Try the Honey Badger Lens","brand_name": "Honey Badger","call_to_action": "TRY","deep_link_properties": {"deep_link_uri": "bitmoji://home","app_name": "Bitmoji - Your Personal Emoji","ios_app_id": "868077558","android_app_url": "com.bitstrips.imoji","icon_media_id": "73b5deb6-5b2c-43b4-b60d-983bc344a4a2","fallback_type": "APP_INSTALL"}}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/creatives

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5e42ff007200ff071b3da02f5e6c0001737e616473617069736300016275696c642d63343664356339642d312d3332352d3000010110",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "d1b888eb-8998-42e3-9e73-45b5b5e8938d",
                "updated_at": "2020-02-11T19:24:35.553Z",
                "created_at": "2020-02-11T19:24:35.553Z",
                "name": "A new Lens with Deep Link Attachment",
                "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
                "type": "LENS_DEEP_LINK",
                "packaging_status": "SUCCESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "Try the Honey Badger Lens",
                "brand_name": "Honey Badger",
                "call_to_action": "TRY",
                "render_type": "STATIC",
                "top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01",
                "top_snap_crop_position": "MIDDLE",
                "deep_link_properties": {
                    "deep_link_uri": "bitmoji://home",
                    "app_name": "Bitmoji - Your Personal Emoji",
                    "ios_app_id": "868077558",
                    "android_app_url": "com.bitstrips.imoji",
                    "icon_media_id": "73b5deb6-5b2c-43b4-b60d-983bc344a4a2",
                    "fallback_type": "APP_INSTALL"
                },
                "ad_product": "LENS"
            }
        }
    ]
}

This creates a new Creative of the type LENS_APP_INSTALL where the attribute top_snap_media_id is of the type LENS_PACKAGE, and where the deep_link_properties specify the attributes for the Deep link Attachment.

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Create Lens with Web View Attachment

Attributes

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
name Creative name R
top_snap_media_id Media ID of type LENS_PACKAGE R
type Creative Type R LENS_WEB_VIEW
ad_product Ad product R LENS
brand_name Brand Name R (required but not displayed) 25 characters max
headline Headline R (required but not displayed) 34 characters max
call_to_action Call to Action R Please refer to the Creative type to CTA mapping table

Additional Attributes

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

Attribute Description Required Possible Values
url Web view URL R
allow_snap_javascript_sdk Allow Snapchat Javascript SDK to autofill form fields O true/false
block_preload Block Snapchat from preloading the web page O true/false
curl -X POST  \
  -d '{"creatives": [{"ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1","name" : "A new Lens with Web View Attachment","type": "LENS_WEB_VIEW","top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01","ad_product": "LENS","headline": "Try the Honey Badger Lens","brand_name": "Honey Badger","call_to_action": "GET_NOW","web_view_properties": {"url": "http://www.example.com","allow_snap_javascript_sdk": "false","block_preload": "true"}}]}' \
  -H "Content-Type: application/json"  \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f1/creatives

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5e43d97400ff00ffe6fb1765c4350001737e616473617069736300016275696c642d63343664356339642d312d3332352d3000010119",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "b8f8dfb3-7738-4765-bd8e-ff312a34740d",
                "updated_at": "2020-02-12T10:54:45.363Z",
                "created_at": "2020-02-12T10:54:45.363Z",
                "name": "A new Lens with Web View Attachment",
                "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f1",
                "type": "LENS_WEB_VIEW",
                "packaging_status": "SUCCESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "Try the Honey Badger Lens",
                "brand_name": "Honey Badger",
                "call_to_action": "GET_NOW",
                "render_type": "STATIC",
                "top_snap_media_id": "4f8083d3-f82d-4235-aa7d-d0c2381e7a01",
                "top_snap_crop_position": "MIDDLE",
                "web_view_properties": {
                    "url": "http://www.example.com",
                    "allow_snap_javascript_sdk": false,
                    "use_immersive_mode": false,
                    "deep_link_urls": [],
                    "block_preload": true
                },
                "ad_product": "LENS"
            }
        }
    ]
}

This creates a new Creative of the type LENS_WEB_VIEW where the attribute top_snap_media_id is of the type LENS_PACKAGE, and where the web_view_properties specify the attributes for the Web View Attachment.

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Create the Ad

This endpoint creates an Ad within an Ad Squad, note that the type attribute should match the Creative type of the Lens.

Attributes

Attribute Description Required Possible Values
ad_squad_id Ad Squad ID R
creative_id Creative ID R
name Ad name R
type Ad type R LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_REMOTE_WEBPAGE
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

Ad Type <-> Creative Type Mapping

Ad Type Allowed Creative Lens Type
LENS LENS
LENS_REMOTE_WEBPAGE LENS_WEB_VIEW
LENS_APP_INSTALL LENS_APP_INSTALL
LENS_DEEP_LINK LENS_DEEP_LINK
curl -X POST \
  -d '{"ads":[{"ad_squad_id": "caff7533-52e1-4412-9ef2-18232dbcd1ba", "creative_id":"0091127a-1c58-4b0b-981d-d419d65cc87c", "name": "Honey Badger Ad - Lens", "type": "LENS", "status": "ACTIVE"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adsquads/caff7533-52e1-4412-9ef2-18232dbcd1ba/ads

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5e41982700ff0e64c8b9dcef490001737e616473617069736300016275696c642d66646632303364612d312d3332342d310001012a",
    "ads": [
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "1ab494d4-73e8-4986-8517-c2d313e63f6e",
                "updated_at": "2020-02-10T17:51:38.097Z",
                "created_at": "2020-02-10T17:51:38.097Z",
                "name": "Honey Badger Ad - Lens",
                "ad_squad_id": "caff7533-52e1-4412-9ef2-18232dbcd1ba",
                "creative_id": "0091127a-1c58-4b0b-981d-d419d65cc87c",
                "status": "ACTIVE",
                "type": "LENS"
            }
        }
    ]
}

This creates a new Ad of the type LENS.

HTTP Request

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

Parameters

Parameter Default Description
ad_squad_id Ad Squad ID

Reporting

Lens Metrics

Field Description Availability
paid_impressions The total number of times your ad was served to a Snapchatter. Tracked when the ad fully renders on a device for the first time during a Snapchatter’s viewing session Real Time
earned_impressions The number of times your ad was viewed after being shared by a Snapchatter via Chat or Stories Within 24 hours
total_impressions The total number of impressions (Paid and Earned) Within 24 hours
shares The number of times your Lens ad was shared via Chat or Stories Real Time
saves The number of times your Lens ad was saved to Memories Real Time
play_time_millis The total amount of time in where Snapchatters interacted with your Lens in the camera (milliseconds) Real Time
spend The total spend delivered in microcurrency Real Time
uniques The number of unique paid impressions Within 24 hours, LIFETIME only
total_reach The number of unique Snapchatters who viewed your Lens ad, either by receiving a Paid or Earned Impression. Within 24 hours, LIFETIME only

Stats are available at the Ad, Ad Squad and Campaign levels and are supported for all granularities: HOUR, DAY, TOTAL and LIFETIME. For lenses with attachments you can also request swipes and attachment specific metrics.

curl "https://adsapi.snapchat.com/v1/adsquads/21136912-6d1a-44ea-a171-8ac29cf4d75d/stats?granularity=LIFETIME&fields=spend,paid_impressions,earned_impressions,shares,saves,play_time_millis,total_impressions,total_reach,uniques"
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5e448f8200ff0a3c430fd301390001737e616473617069736300016275696c642d63343664356339642d312d3332352d300001011c",
    "lifetime_stats": [
        {
            "sub_request_status": "SUCCESS",
            "lifetime_stat": {
                "id": "21136912-6d1a-44ea-a171-8ac29cf4d75d",
                "type": "AD_SQUAD",
                "granularity": "LIFETIME",
                "stats": {
                    "uniques": 298861,
                    "spend": 7027120158,
                    "total_reach": 315925,
                    "total_impressions": 979631,
                    "earned_impressions": 29190,
                    "paid_impressions": 950441,
                    "shares": 7351,
                    "saves": 1784,
                    "play_time_millis": 6354875748
                },
                "start_time": "2016-09-26T08:00:00.000+01:00",
                "end_time": "2020-02-12T17:00:00.000Z",
                "finalized_data_end_time": "2020-02-12T17:00:00.000Z"
            }
        }
    ]
}

HTTP Request

GET https://adsapi.snapchat.com/v1/adsquads/{adsquad-id}/stats

Parameters

Parameter Description
adsquad-id Lens Ad squad ID

Snap Pixel

Snap Pixel provides an entity that advertisers can use to build a correlation between the ads that the users viewed and the conversions that happened on advertiser’s website.

Create a Pixel

You can create a Snap Pixel for your Ad Account on Ad Manager

Get the Pixel associated with an Ad Account

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

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5a0253c100ff013af0e5dd11d40001737e616473617069736300016275696c642d61306563656639392d312d3131392d3300010124",
    "pixels": [
        {
            "sub_request_status": "SUCCESS",
            "pixel": {
                "id": "6abc82ca-4a3a-4391-98ba-0317a8471234",
                "updated_at": "2017-03-15T18:19:08.576Z",
                "created_at": "2017-03-15T18:19:08.576Z",
                "effective_status": "ACTIVE",
                "name": "Test pixel",
                "ad_account_id": "3cb7c65d-a943-448b-90aa-bd6bac71dabc",
                "status": "ACTIVE",
                "pixel_javascript": "<!-- Snap Pixel Code -->\n<script type='text/javascript'>\n(function(e,t,n){if(e.snaptr)return;var a=e.snaptr=function()\n{a.handleRequest?a.handleRequest.apply(a,arguments):a.queue.push(arguments)};\na.queue=[];var s='script';r=t.createElement(s);r.async=!0;\nr.src=n;var u=t.getElementsByTagName(s)[0];\nu.parentNode.insertBefore(r,u);})(window,document,\n'https://sc-static.net/scevent.min.js');\n\nsnaptr('init', '6abc82ca-4a3a-4391-98ba-0317a8471234', {\n'user_email': '__INSERT_USER_EMAIL__'\n});\n\nsnaptr('track', 'PAGE_VIEW');\n\n</script>\n<!-- End Snap Pixel Code -->"
            }
        }
    ]
}

This endpoint retrieves the pixel associated with the specified Ad Account.

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Implementing the Snap Pixel

Please check Business Help Center for steps to implement the pixel on your website.

Get a Specific Pixel

curl "https://adsapi.snapchat.com/v1/pixels/sf6f3815-3527-49e3-a5a7-b9681b31daf4" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5a025dac00ff011af30b6a01d00001737e616473617069736300016275696c642d61306563656639392d312d3131392d3300010162",
    "pixels": [
        {
            "sub_request_status": "SUCCESS",
            "pixel": {
                "id": "sf6f3815-3527-49e3-a5a7-b9681b31daf4",
                "updated_at": "2017-03-15T18:19:08.576Z",
                "created_at": "2017-03-15T18:19:08.576Z",
                "effective_status": "ACTIVE",
                "name": "Test pixel",
                "ad_account_id": "3c42c65d-a943-448b-90aa-bd6bac71d2bc",
                "status": "ACTIVE",
                "pixel_javascript": "<!-- Snap Pixel Code -->\n<script type='text/javascript'>\n(function(e,t,n){if(e.snaptr)return;var a=e.snaptr=function()\n{a.handleRequest?a.handleRequest.apply(a,arguments):a.queue.push(arguments)};\na.queue=[];var s='script';r=t.createElement(s);r.async=!0;\nr.src=n;var u=t.getElementsByTagName(s)[0];\nu.parentNode.insertBefore(r,u);})(window,document,\n'https://sc-static.net/scevent.min.js');\n\nsnaptr('init', 'sf6f3815-3527-49e3-a5a7-b9681b31daf4', {\n'user_email': '__INSERT_USER_EMAIL__'\n});\n\nsnaptr('track', 'PAGE_VIEW');\n\n</script>\n<!-- End Snap Pixel Code -->"
            }
        }
    ]
}

This endpoint retrieves a pixel associated with a specific Ad Account.

HTTP Request

GET https://adsapi.snapchat.com/v1/pixels/<PIXEL_ID>

URL Parameters

Parameter Description
ID The ID of the Pixel to retrieve

Update a Pixel - Organization level

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"pixels":[{"id":"6eda10b7-a5fe-4ac6-80f4-417e68d748fb","name": "New pixel name","organization_id":"7fdeefec-f502-4ca8-9a84-6411e0a51053"}]}'
  https://adsapi.snapchat.com/v1/organizations/7fdeefec-f502-4ca8-9a84-6411e0a51053/pixels

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "589a3df500ff035b6c6fefa6340001737e616473617069736300016275696c642d62666138636139332d312d33392d3400010123",
  "pixels": [
    {
      "sub_request_status": "SUCCESS",
      "pixel": {
                "id": "6eda10b7-a5fe-4ac6-80f4-417e68d748fb",
                "updated_at": "2024-01-30T14:49:40.516Z",
                "created_at": "2018-10-15T07:08:15.742Z",
                "last_updated_by_app_id": "ff503f30-8e94-450b-abac-18e3e25a8da1",
                "last_updated_by_user": "82beca53-2402-45f6-bc0f-1244a2cb8936",
                "name": "New pixel name",
                "organization_id": "7fdeefec-f502-4ca8-9a84-6411e0a51053",
                "status": "ACTIVE",
                "pixel_javascript": "<!-- Snap Pixel Code -->\n<script type='text/javascript'>\n(function(e,t,n){if(e.snaptr)return;var a=e.snaptr=function()\n{a.handleRequest?a.handleRequest.apply(a,arguments):a.queue.push(arguments)};\na.queue=[];var s='script';r=t.createElement(s);r.async=!0;\nr.src=n;var u=t.getElementsByTagName(s)[0];\nu.parentNode.insertBefore(r,u);})(window,document,\n'https://sc-static.net/scevent.min.js');\n\nsnaptr('init', '6eda10b7-a5fe-4ac6-80f4-417e68d748fb', {\n'user_email': '__INSERT_USER_EMAIL__'\n});\n\nsnaptr('track', 'PAGE_VIEW');\n\n</script>\n<!-- End Snap Pixel Code -->",
                "visible_to": [
                    "AdAccountEntity_438cf09a-c829-41f9-bb08-89512a574682",
                    "AdAccountEntity_3dbf041c-f500-442a-89e3-cfd2311dbdd9",
                    "OrganizationEntity_7fdeefec-f502-4ca8-9a84-6411e0a51053",
                    "AdAccountEntity_88225ba6-7559-4000-9663-bace8adff5f2"
                ]
        }
    }
  ]
}

This endpoint retrieves a pixel associated with a specific Organization.

Attributes

Attribute Description Required Possible Values
id ID of the Pixel R
name Name of the Pixel R
organization_id Organization ID R

Attributes that can be updated

Attribute Description
name Name of the Pixel

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Update a Pixel - Ad Account level

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"pixels":[{"id":"6eda10b7-a5fe-4ac6-80f4-417e68d748fb","name": "New pixel name","ad_account_id":"88225ba6-7559-4000-9663-bace8adff5f2"}]}'
  https://adsapi.snapchat.com/v1/adaccounts/88225ba6-7559-4000-9663-bace8adff5f2/pixels

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "589a3df500ff035b6c6fefa6340001737e616473617069736300016275696c642d62666138636139332d312d33392d3400010123",
  "pixels": [
    {
      "sub_request_status": "SUCCESS",
      "pixel": {
                "id": "6eda10b7-a5fe-4ac6-80f4-417e68d748fb",
                "updated_at": "2024-01-30T14:46:58.636Z",
                "created_at": "2018-10-15T07:08:15.742Z",
                "last_updated_by_app_id": "ff503f30-8e94-450b-abac-18e3e25a8da1",
                "last_updated_by_user": "82beca53-2402-45f6-bc0f-1244a2cb8936",
                "name": "New pixel name",
                "organization_id": "7fdeefec-f502-4ca8-9a84-6411e0a51053",
                "ad_account_id": "88225ba6-7559-4000-9663-bace8adff5f2",
                "status": "ACTIVE",
                "pixel_javascript": "<!-- Snap Pixel Code -->\n<script type='text/javascript'>\n(function(e,t,n){if(e.snaptr)return;var a=e.snaptr=function()\n{a.handleRequest?a.handleRequest.apply(a,arguments):a.queue.push(arguments)};\na.queue=[];var s='script';r=t.createElement(s);r.async=!0;\nr.src=n;var u=t.getElementsByTagName(s)[0];\nu.parentNode.insertBefore(r,u);})(window,document,\n'https://sc-static.net/scevent.min.js');\n\nsnaptr('init', '6eda10b7-a5fe-4ac6-80f4-417e68d748fb', {\n'user_email': '__INSERT_USER_EMAIL__'\n});\n\nsnaptr('track', 'PAGE_VIEW');\n\n</script>\n<!-- End Snap Pixel Code -->"
                }
      }
  ]
}

This endpoint will update a specified pixel.

Attributes

Attribute Description Required Possible Values
id ID of the Pixel R
name Name of the Pixel R
ad_account_id Ad Account ID R

Attributes that can be updated

Attribute Description
name Name of the Pixel

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Associate a Pixel to an Ad Squad

To track conversions, the pixel_id parameter must be set in the Ad Squad creation call.

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{"adsquads": [{"name": "Ad Squad with Pixel", "status": "PAUSED", "campaign_id": "84dc65d7-2745-45c3-a2b7-2d616dbb7fff", "type": "SNAP_ADS", "placement": "SNAP_ADS", "billing_event": "IMPRESSION", "bid_micro": "5000000", "daily_budget_micro": "100000000", "start_time": "2017-03-31T15:00:00.444-07:00", "end_time": "2017-04-30T12:16:17.444-07:00", "optimization_goal": "IMPRESSIONS", "targeting": {"regulated_content": false, "geos": [{"country_code": "us"}]}, "pixel_id": "6c9d82ca-4a3a-4391-98ba-0317a8471233"}]}' \
  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": "58e8246700ff03be1041ca773d0001737e616473617069736300016275696c642d39663230313762372d312d35362d3300010111",
  "adsquads": [
    {
      "sub_request_status": "SUCCESS",
      "adsquad": {
        "id": "7fe85cf3-74c7-494e-bdf6-4db478dc4955",
        "updated_at": "2017-04-07T23:44:40.447Z",
        "created_at": "2017-04-07T23:44:40.447Z",
        "name": "Ad Squad with Pixel",
        "status": "PAUSED",
        "campaign_id": "84dc65d7-2745-45c3-a2b7-2d616dbb7fff",
        "type": "SNAP_ADS",
        "targeting": {
          "regulated_content": false,
          "geos": [
            {
              "country_code": "us"
            }
          ]
        },
        "placement": "SNAP_ADS",
        "billing_event": "IMPRESSION",
        "bid_micro": 5000000,
        "daily_budget_micro": 100000000,
        "start_time": "2017-03-31T22:00:00.444Z",
        "end_time": "2017-04-30T19:16:17.444Z",
        "optimization_goal": "IMPRESSIONS",
        "pixel_id": "6c9d82ca-4a3a-4391-98ba-0317a8471233"
      }
    }
  ]
}

Conversion Event Stats

The conversion event metrics available are listed here

Get Campaign Stats

curl "https://adsapi.snapchat.com/v1/campaigns/69d120bd-b319-4201-9a2a-0e64b2ee5411/stats?granularity=DAY&fields=impressions,swipes,conversion_purchases,conversion_save,conversion_start_checkout,conversion_add_cart,conversion_view_content,conversion_add_billing,conversion_sign_ups,conversion_searches,conversion_level_completes,conversion_app_opens,conversion_page_views&start_time=2017-04-28T07:00:00.000-00:00&end_time=2017-04-30T07:00:00.000-00:00" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5907c87e00ff00ffebe513c872800001737e616473617069736300016275696c642d62663930383438312d312d36322d3200010112",
  "timeseries_stats": [
    {
      "sub_request_status": "SUCCESS",
      "timeseries_stat": {
        "id": "69d120bd-b319-4201-9a2a-0e64b2ee5411",
        "type": "CAMPAIGN",
        "granularity": "DAY",
        "start_time": "2017-04-28T00:00:00.000-07:00",
        "end_time": "2017-04-30T00:00:00.000-07:00",
        "finalized_data_end_time": "2017-05-01T00:00:00.000-07:00",
        "timeseries": [
          {
            "start_time": "2017-04-28T00:00:00.000-07:00",
            "end_time": "2017-04-29T00:00:00.000-07:00",
            "stats": {
              "impressions": 7715,
              "swipes": 57,
              "conversion_purchases": 200,
              "conversion_save": 150,
              "conversion_start_checkout": 300,
              "conversion_add_cart": 500,
              "conversion_view_content": 785,
              "conversion_add_billing": 666,
              "conversion_sign_ups": 1000,
              "conversion_searches": 1500,
              "conversion_level_completes": 450,
              "conversion_app_opens": 800,
              "conversion_page_views": 1500
            }
          },
          {
            "start_time": "2017-04-29T00:00:00.000-07:00",
            "end_time": "2017-04-30T00:00:00.000-07:00",
            "stats": {
              "impressions": 7715,
              "swipes": 57,
              "conversion_purchases": 200,
              "conversion_save": 150,
              "conversion_start_checkout": 300,
              "conversion_add_cart": 500,
              "conversion_view_content": 785,
              "conversion_add_billing": 666,
              "conversion_sign_ups": 1000,
              "conversion_searches": 1500,
              "conversion_level_completes": 450,
              "conversion_app_opens": 800,
              "conversion_page_views": 1500
            }
          }
        ]
      }
    }
  ]
}

This endpoint retrieves stats for the specified Campaign.

HTTP Request

GET https://adsapi.snapchat.com/v1/campaigns/{campaign-id}/stats

Parameters

Parameter Default Description
campaign-id Campaign ID

Get Ad Squad Stats

curl "https://adsapi.snapchat.com/v1/adsquads/260ea29d-8380-4103-90cd-89a326090b01/stats?granularity=TOTAL&fields=impressions,swipes,conversion_purchase,conversion_save,conversion_start_checkout,conversion_add_cart,conversion_view_content,conversion_add_billing,conversion_sign_up,conversion_search,conversion_level_complete,conversion_app_open,conversion_page_view" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5907c1c300ff0724e2dea334690001737e616473617069736300016275696c642d62663930383438312d312d36322d3200010154",
  "total_stats": [
    {
      "sub_request_status": "SUCCESS",
      "total_stat": {
        "id": "260ea29d-8380-4103-90cd-89a326090b01",
        "type": "AD_SQUAD",
        "granularity": "TOTAL",
        "stats": {
          "impressions": 15430,
          "swipes": 114,
          "conversion_purchases": 400,
          "conversion_save": 300,
          "conversion_start_checkout": 600,
          "conversion_add_cart": 1000,
          "conversion_view_content": 1570,
          "conversion_add_billing": 1332,
          "conversion_sign_ups": 2000,
          "conversion_searches": 3000,
          "conversion_level_completes": 900,
          "conversion_app_opens": 1600,
          "conversion_page_views": 3000
        },
        "finalized_data_end_time": "2017-05-01T00:00:00.000-07:00"
      }
    }
  ]
}

This endpoint retrieves stats for the specified Ad Squad.

HTTP Request

GET https://adsapi.snapchat.com/v1/adsquads/{adsquad-id}/stats

Parameters

Parameter Default Description
adsquad-id Ad Squad ID

Get Ad Stats

curl "https://adsapi.snapchat.com/v1/ads/482fa116-95c1-43c9-8d17-5a6dc3330d41/stats?granularity=HOUR&fields=impressions,swipes,conversion_purchases,conversion_save,conversion_start_checkout,conversion_add_cart,conversion_view_content,conversion_add_billing,conversion_sign_ups,conversion_searches,conversion_level_completes,conversion_app_opens,conversion_page_views&start_time=2017-04-30T07:00:00.000-00:00&end_time=2017-04-30T10:00:00.000-00:00" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5907cec100ff0aef6f08499b460001737e616473617069736300016275696c642d62663930383438312d312d36322d3200010145",
  "timeseries_stats": [
    {
      "sub_request_status": "SUCCESS",
      "timeseries_stat": {
        "id": "482fa116-95c1-43c9-8d17-5a6dc3330d41",
        "type": "AD",
        "granularity": "HOUR",
        "start_time": "2017-04-30T00:00:00.000-07:00",
        "end_time": "2017-04-30T03:00:00.000-07:00",
        "finalized_data_end_time": "2017-05-01T00:00:00.000-07:00",
        "timeseries": [
          {
            "start_time": "2017-04-30T00:00:00.000-07:00",
            "end_time": "2017-04-30T01:00:00.000-07:00",
            "stats": {
              "impressions": 7715,
              "swipes": 57,
              "conversion_purchases": 200,
              "conversion_save": 150,
              "conversion_start_checkout": 300,
              "conversion_add_cart": 500,
              "conversion_view_content": 785,
              "conversion_add_billing": 666,
              "conversion_sign_ups": 1000,
              "conversion_searches": 1500,
              "conversion_level_completes": 450,
              "conversion_app_opens": 800,
              "conversion_page_views": 1500
            }
          },
          {
            "start_time": "2017-04-30T01:00:00.000-07:00",
            "end_time": "2017-04-30T02:00:00.000-07:00",
            "stats": {
              "impressions": 7715,
              "swipes": 57,
              "conversion_purchases": 200,
              "conversion_save": 150,
              "conversion_start_checkout": 300,
              "conversion_add_cart": 500,
              "conversion_view_content": 785,
              "conversion_add_billing": 666,
              "conversion_sign_ups": 1000,
              "conversion_searches": 1500,
              "conversion_level_completes": 450,
              "conversion_app_opens": 800,
              "conversion_page_views": 1500
            }
          },
          {
            "start_time": "2017-04-30T02:00:00.000-07:00",
            "end_time": "2017-04-30T03:00:00.000-07:00",
            "stats": {
              "impressions": 7715,
              "swipes": 57,
              "conversion_purchases": 200,
              "conversion_save": 150,
              "conversion_start_checkout": 300,
              "conversion_add_cart": 500,
              "conversion_view_content": 785,
              "conversion_add_billing": 666,
              "conversion_sign_ups": 1000,
              "conversion_searches": 1500,
              "conversion_level_completes": 450,
              "conversion_app_opens": 800,
              "conversion_page_views": 1500
            }
          }
        ]
      }
    }
  ]
}

This endpoint retrieves stats for the specified Ad.

HTTP Request

GET https://adsapi.snapchat.com/v1/ads/{ad-id}/stats

Parameters

Parameter Default Description
ad-id Ad ID

Get Pixel Domains

curl "https://adsapi.snapchat.com/v1/pixels/57ad1ad-600076e-58fa375-e19284/domains/stats" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "59b1e63000ff0aeee681bf3ac50001737e616473617069736300016275696c642d64333736306564362d312d39382d3100010123",
    "timeseries_stats": [
        {
            "sub_request_status": "SUCCESS",
            "timeseries_stat": {
                "id": "6c9d82ca-4a3a-4391-98ba-0317a8471296",
                "type": "PIXEL",
                "start_time": "2017-08-31T18:00:00.000-07:00",
                "end_time": "2017-09-07T18:00:00.000-07:00",
                "domains": [
                    {
                        "domain_name": "abc.snapchat.com",
                        "total_events": 30
                    },
                    {
                        "domain_name": "xyz.snapchat.com",
                        "total_events": 8
                    },
                    {
                        "domain_name": "snapchat.com",
                        "total_events": 180886
                    },
                    {
                        "domain_name": "www.snapchat.com",
                        "total_events": 9682034
                    }
                ]
            }
        }
    ]
}

This endpoint retrieves the domains that have fired the pixel in the past 7 days.

HTTP Request

GET https://adsapi.snapchat.com/v1/pixels/{pixel-id}/domains/stats

Parameters

Parameter Default Description
pixel-id Pixel ID

Get Pixel Stats for a specific domain

curl "https://adsapi.snapchat.com//v1/pixels/57ad1ad-600076e-58fa375-e19284/stats?start_time=2017-08-31T18:00:00.000-07:00&end_time=2017-09-07T18:00:00.000-07:00&granularity=DAY&domain=abc.snapchat.com&fields=event_type,os_type,browser_type" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "59b1eac600ff088c614606e13d0001737e616473617069736300016275696c642d64333736306564362d312d39382d3100010157",
    "timeseries_stats": [
        {
            "sub_request_status": "SUCCESS",
            "timeseries_stat": {
                "id": "6c9d82ca-4a3a-4391-98ba-0317a8471234",
                "type": "PIXEL",
                "granularity": "DAY",
                "start_time": "2017-08-31T18:00:00.000-07:00",
                "end_time": "2017-09-07T18:00:00.000-07:00",
                "timeseries": [
                    {
                        "start_time": "2017-08-31T00:00:00.000-07:00",
                        "end_time": "2017-09-01T00:00:00.000-07:00",
                        "total_events": 253926,
                        "event_type_breakdown": {
                            "VIEW_CONTENT": 13560,
                            "PAGE_VIEW": 240366
                        },
                        "os_type_breakdown": {
                            "MAC_OS_X": 1,
                            "IOS": 217753,
                            "ANDROID": 36170,
                            "LINUX": 2
                        },
                        "browser_type_breakdown": {
                            "FIREFOX": 4,
                            "BROWSER_TYPE_OTHER": 154,
                            "SAFARI": 217747,
                            "CHROME": 36021
                        }
                    },
                    {
                        "start_time": "2017-09-01T00:00:00.000-07:00",
                        "end_time": "2017-09-02T00:00:00.000-07:00",
                        "total_events": 873039,
                        "event_type_breakdown": {
                            "VIEW_CONTENT": 36094,
                            "PAGE_VIEW": 836945
                        },
                        "os_type_breakdown": {
                            "IOS": 738139,
                            "ANDROID": 134867,
                            "MAC_OS_X": 17,
                            "LINUX": 2,
                            "WINDOW": 14
                        },
                        "browser_type_breakdown": {
                            "BROWSER_TYPE_OTHER": 709,
                            "SAFARI": 738135,
                            "CHROME": 134163,
                            "FIREFOX": 22,
                            "INTERNET_EXPLORER": 4,
                            "OPERA": 5,
                            "EDGE": 1
                        }
                    },
                    [[snip]]
                    {
                        "start_time": "2017-09-07T00:00:00.000-07:00",
                        "end_time": "2017-09-08T00:00:00.000-07:00",
                        "total_events": 1675610,
                        "event_type_breakdown": {
                            "VIEW_CONTENT": 82831,
                            "PAGE_VIEW": 1592779
                        },
                        "os_type_breakdown": {
                            "IOS": 1363740,
                            "ANDROID": 311818,
                            "MAC_OS_X": 11,
                            "WINDOW": 40,
                            "LINUX": 1
                        },
                        "browser_type_breakdown": {
                            "BROWSER_TYPE_OTHER": 570,
                            "SAFARI": 1363719,
                            "CHROME": 311301,
                            "FIREFOX": 17,
                            "OPERA": 3
                        }
                    }
                ],
                "domain": "abc.snapchat.com"
            }
        }
    ]
}

This endpoint retrieves the pixel stats for a specified domain. You can retrieve stats for a specific domain looking back 7 days from current time.

HTTP Request

GET https://adsapi.snapchat.com/v1/pixels/{pixel-id}/stats

Parameters

Parameter Default Description
pixel-id Pixel ID

Query Paramters

Query Parameter Description Required Possible Values
start_time Start Time (ISO 8601) Yes
end_time End Time (ISO 8601) Yes
granularity Granularity for the data Yes DAY, HOUR
domain Domain name Yes Valid domain name
fields Comma-separated list of fields to retrieve Yes EVENT_TYPE, OS_TYPE, BROWSER_TYPE

Snap App ID

The Snap App ID is a unique ID set up by an advertiser to verify ownership of their apps, the Snap App ID maps to iOS and/or Android and is used for both App Install marketing and re-engagement via the Deep Link ad format.

Setting the Snap App ID

The Snap App ID is set up via Snap Business Manager using the App name and the app identifiers from the iOS Apple store (numerical value) and the Google Play Store (eg “com.x.y”), if you wish to share events with an MMP you can pick the MMP within the Snap App settings.

Once your Snap App ID has been set up via Snap Business Manager a Snap App entity will have been created under your Organization, it’s possible to fetch this entity via an API request.

Snap App entity attributes

Attribute Description Required Possible Values
id Snap App ID Read-only
name App name Read-only
ios_app_id iOS App ID Read-only numerical value from the Apple app store
ios_app_id_verified iOS verification status Read-only true
android_app_url Google Play store ID Read-only eg “com.x.y”
android_app_url_verified Android verification status Read-only true

Get all Snap Apps under an Organization

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

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "6005af2e00ff056460e3b8f73e0001737e616473617069736300016275696c642d34343839623532342d312d3431342d3000010142",
    "paging": {},
    "mobile_apps": [
        {
            "sub_request_status": "SUCCESS",
            "mobile_app": {
                "id": "07b517bb-9cdb-42ef-ba77-9dd9a9eb2dc8",
                "updated_at": "2020-05-28T12:17:48.744Z",
                "created_at": "2020-05-28T12:17:01.757Z",
                "container_kind": "Organizations",
                "container_id": "8fdeefec-f502-4ca8-9a84-6411e0a51098",
                "name": "The Kitty Cat App",
                "visible_to": [
                    "OrganizationEntity_8fdeefec-f502-4ca8-9a84-6411e0a51098",
                    "AdAccountEntity_82225ba6-7559-4000-9663-bace8adff5f8"
                ]
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "mobile_app": {
                "id": "9b5b83ec-c593-4a64-9c6d-a0eb9da0edb9",
                "updated_at": "2020-12-08T22:33:32.204Z",
                "created_at": "2020-09-29T22:33:48.661Z",
                "container_kind": "Organizations",
                "container_id": "8fdeefec-f502-4ca8-9a84-6411e0a51098",
                "name": "The Badger tunneling app",
                "visible_to": [
                    "OrganizationEntity_8fdeefec-f502-4ca8-9a84-6411e0a51098",
                    "AdAccountEntity_82225ba6-7559-4000-9663-bace8adff5f8"
                ],
                "ios_app_id": "444433333",
                "ios_app_id_verified": true,
                "android_app_url": "com.badgertunneling.android"
            }
        }
    ]
}

This endpoint retrieves all Mobile Apps under an Organization.

HTTP Request

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

Parameters

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

Get all Snap Apps under an Ad Account

curl "https://adsapi.snapchat.com/v1/adaccounts/7ebc489b-2120-47ed-95f8-3fe1b26ca997/mobile_apps" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "60abc6ea00ff0a33fdabf6a9c00001737e616473617069736300016275696c642d37356261303735372d312d3434392d3200010119",
    "paging": {},
    "mobile_apps": [
        {
            "sub_request_status": "SUCCESS",
            "mobile_app": {
                "id": "e1956376-a963-4000-8e54-84461bf59388",
                "updated_at": "2021-05-07T12:35:57.591Z",
                "created_at": "2021-04-23T13:01:46.816Z",
                "container_kind": "Organizations",
                "container_id": "7fdeefec-f502-4ca8-9a84-6411e0a51057",
                "name": "Badger Mates",
                "ios_app_id": "9876543210",
                "android_app_url": "com.badger",
                "mobile_measurement_partners": [
                    "ADJUST"
                ]
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "mobile_app": {
                "id": "8b5b83ec-c593-4a64-9c6d-a0eb9da0edba",
                "updated_at": "2021-03-19T07:45:53.009Z",
                "created_at": "2020-09-29T22:33:48.661Z",
                "container_kind": "Organizations",
                "container_id": "7fdeefec-f502-4ca8-9a84-6411e0a51058",
                "name": "Badger Timber Supplies",
                "ios_app_id": "1234567890",
                "ios_app_id_verified": true,
                "android_app_url": "com.badgerexample.android",
                "mobile_measurement_partners": [
                    "APPSFLYER",
                    "KOCHAVA"
                ]
            }
        }
    ]
}

This endpoint retrieves all Mobile Apps associated with an Ad Account.

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Get a specific Snap App

curl "https://adsapi.snapchat.com/v1/mobile_apps/9b5b83ec-c593-4a64-9c6d-a0eb9da0edb9" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "6005afef00ff00ff53c3310c98d70001737e616473617069736300016275696c642d34343839623532342d312d3431342d3000010147",
    "mobile_apps": [
        {
            "sub_request_status": "SUCCESS",
            "mobile_app": {
                "id": "9b5b83ec-c593-4a64-9c6d-a0eb9da0edb9",
                "updated_at": "2020-12-08T22:33:32.204Z",
                "created_at": "2020-09-29T22:33:48.661Z",
                "container_kind": "Organizations",
                "container_id": "8fdeefec-f502-4ca8-9a84-6411e0a51098",
                "name": "The Badger tunneling app",
                "visible_to": [
                    "OrganizationEntity_8fdeefec-f502-4ca8-9a84-6411e0a51098",
                    "AdAccountEntity_82225ba6-7559-4000-9663-bace8adff5f8"
                ],
                "ios_app_id": "444433333",
                "ios_app_id_verified": true,
                "android_app_url": "com.badgertunneling.android",
                "android_app_url_verified": true
            }
        }
    ]
}

This endpoint retrieves a specific Mobile App.

HTTP Request

GET https://adsapi.snapchat.com/v1/mobile_apps/{mobile_app_id}

Parameters

Parameter Default Description
snap_app_id Mobile App ID

Reach and Frequency Guide

Reach and Frequency buying allows advertisers to purchase reach-optimized campaigns via the API. This feature is currently in beta and available on a whitelist basis only. Please contact your Snap Account Manager to setup access.

Create R&F Campaign

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{"campaigns": [{"name": "Audience Filter Campaign", "ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1dab", "status": "ACTIVE", "start_time": "2018-08-11T22:00:00.000Z", "buy_model": "RESERVED", "objective": "BRAND_AWARENESS"}]}' \
   "https://adsapi.snapchat.com/v1/adaccounts/3b0fbace-04b4-4f04-a425-33b5e0af1dab/campaigns"

The above command returns JSON structured like this:

{
  "request_status": "success",
  "request_id": "57b002ad00ff07e1f50fd2267f0001737e616473617069736300016275696c642d35396264653638322d312d31312d370001010d",
  "campaigns": [
    {
      "sub_request_status": "success",
      "campaign": {
        "id": "92e1c28a-a331-45b4-8c26-fd3e0eea8c39",
        "updated_at": "2016-08-14T05:33:33.876Z",
        "created_at": "2016-08-14T05:33:33.876Z",
        "name": "Audience Filter Campaign",
        "ad_account_id": "3b0fbace-04b4-4f04-a425-33b5e0af1dab",
        "status": "ACTIVE",
        "start_time": "2018-08-11T22:00:00.000Z",
        "objective": "BRAND_AWARENESS",
        "buy_model": "RESERVED"
      }
    }
  ]
}

This will create a campaign within a specified ad account. Once a R&F campaign is booked we do not allow for edits to the campaign or ad squad. Edits, or a re-booking, is only allowed if the initial booking fails.

Re-booking is done only if your initial R&F Ad Squad booking request is FAILED. In addition, we reserve the right to remove any advertiser from the R&F program if we see an excessive number of cancellations.

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Create a Forecasting Request

Before creating the Reach & Frequency Ad Squad you will need to make a forecasting request using the Ad Squad with the placement, targeting spec and frequency cap that you wish to use.

The forecasting request will return a reach curve showing the estimated reach based on your targeting and which budget you need to apply for a certain estimated reach.

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{"placement_v2":{"config":"AUTOMATIC"},"targeting":{"geos":[{"country_code":"us"}],"demographics":[{"gender":"MALE"}]},"delivery_constraint":"REACH_AND_FREQUENCY","start_time":"2020-08-28T14:08:04+01:00","end_time":"2020-09-29T14:08:04+01:00","optimization_goal":"VIDEO_VIEWS","cap_and_exclusion_config":{"frequency_cap_config":[{"frequency_cap_count":1,"frequency_cap_type":"IMPRESSIONS","time_interval":7,"frequency_cap_interval":"DAYS"}]}}' \
   "https://adsapi.snapchat.com/v1/adaccounts/3b0fbace-04b4-4f04-a425-33b5e0af1dab/reserved_forecasting"

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5b3e5c9600ff0675dc615cb9090001737e616473617069736300016275696c642d31346237626365612d312d3138312d300001010b",
  "reach_frequency_curve": [
    {
      "impression": 254240,
      "reach": 250320,
       "budget_micro": 610557576
    },
    {
      "impression": 1300320,
      "reach": 1211840,
      "budget_micro": 3121198726
    },
    // snip
    {
      "impression": 102770081,
      "reach": 29095360,
      "budget_micro": 729561535468
    },
    {
      "impression": 104879041,
      "reach": 29445920,
      "budget_micro": 847933759640
    }
  ],
  "display_message": "",
  "debug_message": "",
  }
}

Required Ad Squad attributes - Forecasting request

Attribute Description Possible Values
placement_v2 Placement for the Ads Placement V2
targeting Targeting of the Ads Targeting Spec
delivery_constraint REACH_AND_FREQUENCY
start_time Start time
end_time End time
type Ad Squad type SNAP_ADS, LENS
optimization_goal Optimization Goal based on Ad Squad type For SNAP_ADS the optimization_goal has to be VIDEO_VIEWS, for LENS the optimization_goal has to be USES
cap_and_exclusion_config Frequency Cap Spec

HTTP Request

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

Parameters

Parameter Default Description
ad_account_id Ad Account ID

Create R&F Ad Squad

When creating the Reach & Frequency ad squad you should use the same Ad Squad values used in the Forecast request for Placement V2, targeting and frequency cap. Additionally you should also use the values impression, reach and budget_micro returned in the forecast.

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{"adsquads": [{"name": "Snap Ad, United States, All Genders, All Ages", "placement_v2": {"config": "AUTOMATIC"}, "start_time": "2018-07-08T15:13:36-07:00", "end_time": "2018-08-07T15:13:36-07:00", "delivery_constraint": "REACH_AND_FREQUENCY", "pixel_id": null, "campaign_id": "319bcd47-3d99-4d3b-a39a-33c3fbea470b", "daily_budget_micro": null, "targeting": {"geos": [{"country_code": "us"}]}, "cap_and_exclusion_config": {"frequency_cap_config": [{"frequency_cap_count": 2, "time_interval": 7, "frequency_cap_interval": "DAYS", "frequency_cap_type": "IMPRESSIONS"}]},"type": "SNAP_ADS", "conversion_window": null, "status": "ACTIVE", "auto_bid": false, "optimization_goal": "VIDEO_VIEWS", "reach_goal": 39084400, "impression_goal": 132528801, "lifetime_budget_micro": 484048584430, "reach_and_frequency_status": "PENDING"}]}' \
  https://adsapi.snapchat.com/v1/campaigns/a09f983a-06ac-4081-9659-7bc9e1cd6888/adsquads

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5b3e983d00ff059adbd17a39bd0001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d31623031633134632d312d3138322d3000010116",
  "adsquads": [
    {
      "sub_request_status": "SUCCESS",
      "adsquad": {
        "id": "5fd79efb-e544-4d43-9e59-9e6a88f8232e",
        "updated_at": "2018-07-05T22:14:21.824Z",
        "created_at": "2018-07-05T22:14:21.824Z",
        "name": "Snap Ad, United States, All Genders, All Ages",
        "status": "ACTIVE",
        "campaign_id": "319bcd47-3d99-4d3b-a39a-33c3fbea470b",
        "type": "SNAP_ADS",
        "targeting": {
          "regulated_content": false,
          "geos": [
            {
              "country_code": "us"
            }
          ]
        },
        "placement_v2": {
          "config": "AUTOMATIC"
        },
        "billing_event": "IMPRESSION",
        "auto_bid": false,
        "lifetime_budget_micro": 484048584430,
        "start_time": "2018-07-08T22:13:36.000Z",
        "end_time": "2018-08-07T22:13:36.000Z",
        "optimization_goal": "VIDEO_VIEWS",
        "impression_goal": 132528801,
        "reach_goal": 39084400,
        "cap_and_exclusion_config": {
          "frequency_cap_config": [
            {
              "frequency_cap_count": 2,
              "frequency_cap_type": "IMPRESSIONS",
              "time_interval": 7,
              "frequency_cap_interval": "DAYS"
            }
          ],
          "is_industry_exclusive": false,
          "is_industry_competitively_separated": false
        },
        "delivery_constraint": "REACH_AND_FREQUENCY",
        // Will automatically update to ACTIVE or FAILED
        "reach_and_frequency_status": "PENDING",
        "reach_and_frequency_rate_micro": 3652402
      }
    }
  ]
}

This creates an Ad Squad within a Campaign. For R&F Ad Squads there can only be one Ad Squad under a Campaign.

Attributes for R&F Ad Squad

Attribute Description Required Possible Values
campaign_id Campaign ID R
bid_micro Max Bid (micro-currency) Must not be included
billing_event Billing Event R IMPRESSION
daily_budget_micro Daily Budget (micro-currency) R Must be set to null
start_time Start time R Must be greater than or equal to 2 days and less than or equal to 90 days from current time
end_time End time R DIfference between end_time and start_time must be greater than or equal to 3 days and less than or equal to 90 days
name Ad Squad name R
optimization_goal Optimization Goal R Must be set to VIDEO_VIEWS (Optimizes for Reach and Frequency) for Snap Ads, or USES for Lenses
placement_v2 Placement R Json object containing advanced placement options See placement_v2
status Ad Squad status R Must be set to ACTIVE
targeting Targeting spec R
type Ad Squad Type R SNAP_ADS, LENS
included_content_types Content Type to be included O NEWS, ENTERTAINMENT, SCIENCE_TECHNOLOGY, BEAUTY_FASHION, MENS_LIFESTYLE, WOMENS_LIFESTYLE, GENERAL_LIFESTYLE, FOOD, SPORTS, YOUNG_BOLD
excluded_content_types Content Type to be excluded O NEWS, ENTERTAINMENT, SCIENCE_TECHNOLOGY, BEAUTY_FASHION, MENS_LIFESTYLE, WOMENS_LIFESTYLE, GENERAL_LIFESTYLE, FOOD, SPORTS, YOUNG_BOLD
cap_and_exclusion_config The frequency cap and exclusion spec R
lifetime_budget_micro Lifetime budget (micro-currency) R Must match the desired budget value defined as budget_micro in the forecasting request
reach_goal Reach goal as specified in the Forecasting request R Must match the reach value in the forecasting request
impression_goal Impression goal as specified in the Forecasting request R Must match the impression value in the forecasting request
ad_scheduling_config The schedule for running ads N/A Should not be set
auto_bid Allow Snapchat to automatically set the bid to recommended amount R Must be set to false
target_bid Allows Snapchat to adjust the bid aiming to keep your average CPA at or below the amount set by the ad set end date R Must be set to false
pixel_id Pixel to be associated with the Ad Squad O
delivery_constraint Type of delivery R REACH_AND_FREQUENCY
reach_and_frequency_status Status of the reach and frequency booking R Must be set to PENDING which automatically updates to ACTIVE or FAILED after booking

HTTP Request

POST https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads

Parameters

Parameter Default Description
campaign_id Campaign ID

Updating R&F Ad Squads and Rebooking

Once you create an AdSquad the reach_and_frequency_status will be PENDING. This will be automatically updated to ACTIVE or FAILED by our booking service within a minute. If it is FAILED, you can rebook with the same Ad Squad by doing an UPDATE on the AdSquad.

You would issue a new Forecasting Request and then update the Ad Squad, providing the ID, while setting the reach_and_frequency_status from FAILED to PENDING, passing new impression_goal, reach_goal, and lifetime_budget_micro values from the forecast.

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"adsquads": [{"id": "39df6afb-fbea-4a9d-8b5e-8899ab4f4890", "name": "Snap Ad, United States, All Genders, All Ages", "type": "SNAP_AD", "status": "ACTIVE", "campaign_id": "cfeb4b9c-8464-4498-9906-b4eb2d6c56ac", "placement_v2": {"config": "AUTOMATIC"}, "auto_bid": false, "lifetime_budget_micro": 200000000000, "optimization_goal": "VIDEO_VIEWS", "targeting": {"geos": [{"operation": "INCLUDE", "country_code": "us"}], "regulated_content": false}, "start_time": "2018-07-08T15:13:36-07:00", "end_time": "2018-08-07T15:13:36-07:00", "cap_and_exclusion_config": {"frequency_cap_config": [{"frequency_cap_count": 4, "time_interval": 7, "frequency_cap_interval": "DAYS", "frequency_cap_type": "IMPRESSIONS"}]}, "delivery_constraint": "REACH_AND_FREQUENCY", "reach_goal": 2263600, "lifetime_budget_micro": 200000000000, "impression_goal": 13975600, "reach_and_frequency_status": "PENDING"}]}'
  https://adsapi.snapchat.com/v1/campaigns/cfeb4b9c-8464-4498-9906-b4eb2d6c56ac/adsquads

The above command returns JSON structured like this:

{
  "request_status": "SUCCESS",
  "request_id": "5b3e983d00ff059adbd17a39bd0001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d31623031633134632d312d3138322d3000010116",
  "adsquads": [
    {
      "sub_request_status": "SUCCESS",
      "adsquad": {
        "id": "5fd79efb-e544-4d43-9e59-9e6a88f8232e",
        "updated_at": "2018-07-05T22:14:21.824Z",
        "created_at": "2018-07-05T22:14:21.824Z",
        "name": "Snap Ad, United States, All Genders, All Ages",
        "status": "ACTIVE",
        "campaign_id": "319bcd47-3d99-4d3b-a39a-33c3fbea470b",
        "type": "SNAP_ADS",
        "targeting": {
          "regulated_content": false,
          "geos": [
            {
              "country_code": "us"
            }
          ]
        },
        "placement_v2": {
          "config": "AUTOMATIC"
        },
        "billing_event": "IMPRESSION",
        "auto_bid": false,
        "lifetime_budget_micro": 200000000000,
        "start_time": "2018-07-08T22:13:36.000Z",
        "end_time": "2018-08-07T22:13:36.000Z",
        "optimization_goal": "VIDEO_VIEWS",
        "impression_goal": 13975600,
        "reach_goal": 2263600,
        "cap_and_exclusion_config": {
          "frequency_cap_config": [
            {
              "frequency_cap_count": 4,
              "frequency_cap_type": "IMPRESSIONS",
              "time_interval": 7,
              "frequency_cap_interval": "DAYS"
            }
          ],
          "is_industry_exclusive": false,
          "is_industry_competitively_separated": false
        },
        "delivery_constraint": "REACH_AND_FREQUENCY",
        // Will automatically update to ACTIVE or FAILED
        "reach_and_frequency_status": "PENDING",
        "reach_and_frequency_rate_micro": 3652402
      }
    }
  ]
}

This endpoint will update a specified ad squad.

Attributes that must be updated

Attribute Description
reach_and_frequency_status Must be set back to PENDING
impression_goal Must be set to new value from new forecasting request
reach_goal Must be set to new value from new forecasting request
lifetime_budget_micro Must be set to new value from new forecasting request

HTTP Request

PUT https://adsapi.snapchat.com/v1/campaigns/{campaign_id}/adsquads

Parameters

Parameter Default Description
campaign_id Campaign ID

Create the Ad

R&F can be used with creatives of type Snap Ads or type Lens. Ads follow the type of creative as explained here

Cancelling R&F booking

There are four ways to cancel a booking. Please be aware that cancelling bookings frequently will lead to removal from the R&F program.

  1. Updating the AdSquad status to PAUSED
  2. Deleting the AdSquad
  3. Updating the Campaign status to PAUSED
  4. Deleting the Campaign

Dynamic Product Ads Guide

Dynamic ads power personalized ad experiences in an automated way.

Product Catalog

A detailed spec of the Catalog and available file formats can be found in the following article, the current item limit of a Product Catalog is 10 million items. The permission Organization Admin is required to create, update or delete a Product Catalog.

Attributes

Attribute Description Required Possible Values
name R max 375 characters
organization_id Organization ID R
vertical R UNKNOWN_VERTICAL, COMMERCE, HOTELS, PLACES, FLIGHTS
source Indicates the source of Catalog, set automatically on creation Read-only BUSINESS_MANAGER, FEED, WOOCOMMERCE, SHOPIFY
default_product_set_id Default product set that includes all the products in the catalog Read-only
event_sources List of Pixel IDs and/or the Snap App IDs that reports events for the Catalog O [ {“id”: “aa1a11aa-a111-1a11-1a1a-a1aa1aa1aaa”,“type”: “MOBILE_APP”}, {“id”: “2bbb22b2-b22bb-2bb2-22b2-222b22b222bb”,“type”: “PIXEL”} ]

API Limits

Create a Catalog

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{"catalogs": [{"organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058","name": "Honeybear Catalog","vertical": "COMMERCE","event_sources": [{"id": "aa1a11aa-a111-1a11-1a1a-a1aa1aa1aaa","type": "PIXEL"},{"id": "2bbb22b2-b22bb-2bb2-22b2-222b22b222bb","type": "MOBILE_APP"}] }]}' \
   "https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/catalogs"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f73b68a00ff0e59830e4d95c80001737e616473617069736300016275696c642d63326234383933652d312d3338392d3000010129",
    "catalogs": [
        {
            "sub_request_status": "SUCCESS",
            "catalog": {
                "created_at": "2020-09-29T22:34:52.540013Z",
                "updated_at": "2020-09-29T22:34:52.540013Z",
                "id": "39ae292e-7ec7-4ed7-a0c4-7567731e9c78",
                "name": "Honeybear Catalog",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
                "event_sources": [
                    {
                        "id": "2bbb22b2-b22bb-2bb2-22b2-222b22b222bb",
                        "type": "MOBILE_APP"
                    },
                    {
                        "id": "aa1a11aa-a111-1a11-1a1a-a1aa1aa1aaa",
                        "type": "PIXEL"
                    }
                ],
                "default_product_set_id": "728912bf-4402-49d9-aa38-9b60fb98ee73",
                "vertical": "COMMERCE"
            }
        }
    ]
}

This creates a Catalog under the organization

HTTP Request

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

Parameters

Parameter Default Description
organization_id Organization ID

Update a Catalog

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"catalogs": [{"id":"39ae292e-7ec7-4ed7-a0c4-7567731e9c78","organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058","name": "Honeybear Catalog II","vertical": "COMMERCE","event_sources": [{"id": "aa1a11aa-a111-1a11-1a1a-a1aa1aa1aaa","type": "PIXEL" },{"id": "bb1b11bb-b111-1b11-1b1b-b1bb1bb1bbb","type": "PIXEL" },{ "id": "2bbb22b2-b22bb-2bb2-22b2-222b22b222bb", "type": "MOBILE_APP"}]}]}' 
  https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/catalogs

The above request updates the name of the Catalog and adds an additional PIXEL to the event_sources, it returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f73cddc00ff0167a5aa92d5900001737e616473617069736300016275696c642d63326234383933652d312d3338392d300001012c",
    "catalogs": [
        {
            "sub_request_status": "SUCCESS",
            "catalog": {
                "created_at": "2020-09-29T22:34:52.540013Z",
                "updated_at": "2020-09-30T00:14:20.491333Z",
                "id": "39ae292e-7ec7-4ed7-a0c4-7567731e9c78",
                "name": "Honeybear Catalog II",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
                "event_sources": [
                    {
                        "id": "aa1a11aa-a111-1a11-1a1a-a1aa1aa1aaa",
                        "type": "PIXEL"
                    },
                    {
                        "id": "bb1b11bb-b111-1b11-1b1b-b1bb1bb1bbb",
                        "type": "PIXEL"
                    },
                    {
                        "id": "2bbb22b2-b22bb-2bb2-22b2-222b22b222bb",
                        "type": "MOBILE_APP"
                    }
                ],
                "default_product_set_id": "728912bf-4402-49d9-aa38-9b60fb98ee73",
                "vertical": "COMMERCE"
            }
        }
    ]
}

This request updates the specified Catalog.

Attributes that can be updated

Attribute Description Required Possible Values
name End time R
event_sources The Pixel IDs and/or the Snap App IDs that reports events for the Catalog O {“id”: “aa1a11aa-a111-1a11-1a1a-a1aa1aa1aaa”,“type”: “MOBILE_APP”}, {“id”: “2bbb22b2-b22bb-2bb2-22b2-222b22b222bb”,“type”: “PIXEL”} ]

HTTP Request

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

Parameters

Parameter Default Description
organization_id Organization ID

Get All Catalogs

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

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5d6f282800ff099634a02909d20001737e7465616d6b6f363139000161646d616e616765722d6170693a6275696c642d36373633363336342d312d3238352d300001014e",
    "catalogs": [
        {
            "sub_request_status": "SUCCESS",
            "catalog": {
                "created_at": "2020-09-29T22:34:52.540013Z",
                "updated_at": "2020-09-30T00:14:20.491333Z",
                "id": "39ae292e-7ec7-4ed7-a0c4-7567731e9c78",
                "name": "Honeybear Catalog II",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
                "event_sources": [
                    {
                        "id": "aa1a11aa-a111-1a11-1a1a-a1aa1aa1aaa",
                        "type": "PIXEL"
                    },
                    {
                        "id": "fb5b83ec-c593-4a64-9c6d-a0eb9da0edba",
                        "type": "MOBILE_APP"
                    },
                    {
                        "id": "bb1b11bb-b111-1b11-1b1b-b1bb1bb1bbb",
                        "type": "PIXEL"
                    }
                ],
                "default_product_set_id": "728912bf-4402-49d9-aa38-9b60fb98ee73",
                "vertical": "COMMERCE"
            }
        },
        ...
        {
            "sub_request_status": "SUCCESS",
            "catalog": {
                "created_at": "2020-09-29T21:49:51.063514Z",
                "updated_at": "2020-09-29T21:49:51.063514Z",
                "id": "419f565a-ae00-40b5-b159-3c5b051f742a",
                "name": "Honeybear Catalog",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
                "default_product_set_id": "10e7d339-0ff1-434a-996a-94d34918c948",
                "vertical": "COMMERCE"
            }
        },

    ],
    "paging": {
        "next_link": "https://adsapi.snapchat.com/v1/organizations/8fdeefec-f502-4ca8-9a84-6411e0a51058/catalogs?cursor=def456&limit=100"
    }
}

This request will retrieve a list of all the catalogs within an organization

HTTP Request

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

Parameters

Parameter Default Description
organization_id Organization ID

Get a specific Catalog

curl
"https://adsapi.snapchat.com/v1/catalogs/0e854f6a-523a-4f9e-8b82-5a9071e023a6" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f7ef67500ff053956b806c94a0001737e616473617069736300016275696c642d31663731616139352d312d3339312d3100010118",
    "catalogs": [
        {
            "sub_request_status": "SUCCESS",
            "catalog": {
                "created_at": "2020-09-29T22:23:37.676100Z",
                "updated_at": "2020-09-29T22:23:37.676100Z",
                "id": "0e854f6a-523a-4f9e-8b82-5a9071e023a6",
                "name": "Honeybear Catalog",
                "organization_id": "8fdeefec-f502-4ca8-9a84-6411e0a51058",
                "event_sources": [
                    {
                        "id": "aa1a11aa-a111-1a11-1a1a-a1aa1aa1aaa",
                        "type": "PIXEL"
                    }
                ],
                "default_product_set_id": "b6d35541-d5b6-4e06-a400-03f9937392cc",
                "vertical": "COMMERCE"
            }
        }
    ]
}

This request retrieves a specific Catalog.

HTTP Request

GET https://adsapi.snapchat.com/v1/catalogs/{catalog_id}

Parameters

Parameter Default Description
catalog_id Catalog ID

Delete a Catalog

curl -X DELETE "https://adsapi.snapchat.com/v1/catalogs/bbe607b2-03ab-4387-9cb6-0cc6c2cc4b44" \
  -H "Authorization: Bearer meowmeowmeow"

The above request returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f74cc3a00ff02642c414049a30001737e616473617069736300016275696c642d63326234383933652d312d3338392d300001010f",
    "catalogs": []
}

This request deletes a specific Catalog.

HTTP Request

DELETE https://adsapi.snapchat.com/v1/catalogs/{catalog_id}

Parameters

Parameter Default Description
catalog_id Catalog ID

ERRORS

Error Cause
CAT_VALIDATION_ERROR_TOO_MANY_CATALOGS_IN_BATCH Thrown when there are too many catalogs in a batch
CAT_VALIDATION_ERROR_INVALID_PAGINATION_READ_LIMIT Thrown if the read limit specified by user is invalid
CAT_VALIDATION_ERROR_READ_LIMIT_MUST_BE_SPECIFIED Thrown if only pagination cursor is provided but not an explicit read limit
CAT_VALIDATION_ERROR_INVALID_CURSOR Thrown if the pagination cursor provided by the user is invalid
NOT_FOUND Thrown when catalog is not found
FORBIDDEN Thrown when catalog cannot be accessed by this user

Product Feed

The relationship between a Catalog and a Product feed is currently 1:1, there can only ever be one Product Feed under a Catalog.

Product Feed attributes

Attribute Description Required Possible Values
name R max 375 characters
catalog_id The Catalog ID R
status O ACTIVE (default)
default_currency The Currency used by the feed using the three letter ISO 4217 code R AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHE, CHF, CHW, CLF, CLP, CNY, COP, COU, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SOS, SRD, SSP, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USN, UYI, UYU, UYW, UZS, VES, VND, VUV, WST, XAF, XBC, XCD, XOF, XPF, XSU, XUA, YER, ZAR, ZMW, ZWL
schedule Json configuration which defines the schedule for fetching the product feed O See schedule attributes below

Sample schedule #1 - This schedule is set to fetch a non-password protected feed 15 minutes past every hour given the America/Los_Angeles timezone

"schedule": {
    "interval_type": "HOURLY",
    "timezone": "America/Los_Angeles",
    "minute": 15,
    "url": "https://example.com/product_feed.csv"
}

Sample schedule #2 - This schedule is set to fetch a non-password protected every Tuesday at 6 am given the Europe/Berlin timezone, since minute is left out it defaults to 0

"schedule": {
    "interval_type": "WEEKLY",
    "timezone": "Europe/Berlin",
    "hour": 6,
    "day_of_week": "TUESDAY",
    "url": "https://example.com/product_feed.csv"
}

Sample schedule #3 - This schedule is set to fetch a password protected FTP hosted feed on the 10th day of every month at 6:30 AM given the Europe/London timezone

"schedule": {
    "interval_type": "MONTHLY",
    "timezone": "Europe/London",
    "day_of_month": 10,
    "hour": 06,
    "minute": 30,
    "url": "ftp://example.com/product_feed.csv"
    "username": "H0neyBadger",
    "password": "BeezAreCool99"
}

Schedule attributes

The schedule attribute allows you to define how often Snap should fetch your Product Feed, the attributes you can use vary depending on the interval type that you pick.

Schedule attribute Description Required Possible Values
url The FTP/SFTP/HTTP/HTTPS URL including file name where the product feed is to be fetched from R
username The username to access the product feed O/Required if url is password protected
password The password to access the product feed O/Required if url is password protected
timezone The time zone used for the schedule, default timezone is UTC O
interval_type The interval by which the product feed will be fetched R HOURLY, DAILY, WEEKLY, MONTHLY
interval_count Specifies number of intervals between the feed being fetched See below table See below table
day_of_month Represents a day of the month See below table 1-31
day_of_week Represents a day of the week See below table MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY
hour Represents the hour setting See below table 00-23
minute Represents the minute setting See below table 00-59

interval_type required values

Different interval settings require different attributes, this table outlines which attributes that can be included.

interval_type day_of_month day_of_week hour minute interval_count interval_count value
MONTHLY R - R R - -
WEEKLY - R R R - -
DAILY - - R R O 1-31 , specifies the number of days in between each fetch
HOURLY - - - R O 1-23 , specifies the number of hours in between each fetch

Create a Product Feed

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{"product_feeds":[{"catalog_id":"419f565a-ae00-40b5-b159-3c5b051f742a","name":"Badger Burrow supplies","default_currency":"USD","status":"ACTIVE","schedule":{"url":"ftp://93.184.216.34/timber_product_feed.csv","username":"H0neyBadger","password":"BeezAreCool99","interval_type":"HOURLY","interval_count":"1","timezone":"PST","minute":"15"}}]}' \
  "https://adsapi.snapchat.com/v1/catalogs/419f565a-ae00-40b5-b159-3c5b051f742a/product_feeds"

The above request returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f74db4600ff0d85ee173e68b30001737e616473617069736300016275696c642d63326234383933652d312d3338392d3000010149",
    "product_feeds": [
        {
            "sub_request_status": "SUCCESS",
            "product_feed": {
                "created_at": "2020-09-30T19:23:51.441770Z",
                "updated_at": "2020-09-30T19:23:51.441770Z",
                "id": "63397464-b02e-4da5-93d7-fc00e4ac9a5b",
                "catalog_id": "419f565a-ae00-40b5-b159-3c5b051f742a",
                "name": "Badger Burrow supplies",
                "default_currency": "USD",
                "schedule": {
                    "interval_type": "HOURLY",
                    "timezone": "PST",
                    "minute": 15,
                    "interval_count": 1,
                    "url": "ftp://93.184.216.34/timber_product_feed.csv"
                }
            }
        }
    ]
}

This request creates a Product Feed, it allows for the option to specify a schedule and URL for retrieving an updated Product Feed.

HTTP Request

POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/product_feeds

Parameters

Parameter Default Description
feed_id Feed ID

Update a Product Feed

curl -X PUT \
  -d '{"product_feeds":[{"id":"b5139779-d001-4f12-ae33-d86a2faf05a6","catalog_id":"79ae292e-7ec7-4ed7-a0c4-7567731e9c78","name":"Badger Burrow supplies","default_currency":"GBP","status":"ACTIVE","schedule":{"url":"ftp://93.184.216.34/timber_product_feed.csv","username":"H0neyBadger","password":"BeezAreCool99","interval_type":"HOURLY","interval_count":"4","timezone":"PST","hour":"12","minute":"30"}}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/catalogs/39ae292e-7ec7-4ed7-a0c4-7567731e9c78/product_feeds

The above request returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f74bfb500ff05f08282c21d6d0001737e616473617069736300016275696c642d63326234383933652d312d3338392d300001012e",
    "product_feeds": [
        {
            "sub_request_status": "SUCCESS",
            "product_feed": {
                "created_at": "2020-09-30T16:09:20.748830Z",
                "updated_at": "2020-09-30T17:26:13.749843Z",
                "id": "b5139779-d001-4f12-ae33-d86a2faf05a6",
                "catalog_id": "79ae292e-7ec7-4ed7-a0c4-7567731e9c78",
                "name": "Badger Burrow supplies",
                "default_currency": "GBP",
                "schedule": {
                    "interval_type": "HOURLY",
                    "timezone": "PST",
                    "minute": 30,
                    "interval_count": 4,
                    "url": "ftp://93.184.216.34/timber_product_feed.csv"
                }
            }
        }
    ]
}

This request updates a specific Product Feed.

HTTP Request

PUT https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/product_feeds

Parameters

Parameter Default Description
feed_id Feed ID

Get all Product Feeds

curl
"https://adsapi.snapchat.com/v1/catalogs/19bc3acf-20ce-444f-9829-c3e635ead3a9/product_feeds" \
  -H "Authorization: Bearer meowmeowmeow"

The above request returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f74d7e000ff0ec7804b0e6f540001737e616473617069736300016275696c642d63326234383933652d312d3338392d3000010105",
    "product_feeds": [
        {
            "sub_request_status": "SUCCESS",
            "product_feed": {
                "created_at": "2020-09-30T18:49:46.429529Z",
                "updated_at": "2020-09-30T18:49:54.681827Z",
                "id": "72cffebf-b91b-4af7-a8b9-d2a91e51b456",
                "catalog_id": "19bc3acf-20ce-444f-9829-c3e635ead3a9",
                "name": "Badger Burrow supplies",
                "default_currency": "EUR",
                "schedule": {
                    "interval_type": "WEEKLY",
                    "timezone": "CET",
                    "hour": 6,
                    "interval_count": 1,
                    "day_of_week": "TUESDAY",
                    "url": "ftp://93.184.216.34/timber_product_feed.csv"
                }
            }
        }
    ]
}

This request lists all Product Feeds under the Catalog, at the moment there can only be one Product Feed under the catalog.

HTTP Request

GET https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/product_feeds

Parameters

Parameter Default Description
feed_id Feed ID

Get a specific Product Feed

curl
"https://adsapi.snapchat.com/v1/product_feeds/b5139779-d001-4f12-ae33-d86a2faf05a9" \
  -H "Authorization: Bearer meowmeowmeow"

The above request returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f74d7f300ff025b1dcfd518760001737e616473617069736300016275696c642d63326234383933652d312d3338392d3000010136",
    "product_feeds": [
        {
            "sub_request_status": "SUCCESS",
            "product_feed": {
                "created_at": "2020-09-30T16:09:20.748830Z",
                "updated_at": "2020-09-30T17:26:51.410921Z",
                "id": "b5139779-d001-4f12-ae33-d86a2faf05a9",
                "catalog_id": "39ae292e-7ec7-4ed7-a0c4-7567731e9c78",
                "name": "Badger Burrow Supplies",
                "default_currency": "GBP",
                "schedule": {
                    "interval_type": "HOURLY",
                    "timezone": "PST",
                    "minute": 30,
                    "interval_count": 4,
                    "url": "ftp://93.184.216.34/timber_product_feed.csv"
                }
            }
        }
    ]
}

This request returns a specific Product Feed based on the Product Feed id.

HTTP Request

GET https://adsapi.snapchat.com/v1/product_feeds/{product_feed_id}

Parameters

Parameter Default Description
feed_id Feed ID

Delete a Product Feed

curl -X DELETE "https://adsapi.snapchat.com/v1/product_feeds/ab2ac629-b218-4699-9e19-6946d17faaa3" \
  -H "Authorization: Bearer meowmeowmeow"

The above request returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f74d24400ff06f46ef9a8b6c00001737e616473617069736300016275696c642d63326234383933652d312d3338392d3000010155",
    "product_feeds": []
}

This request deletes a specific Product Feed.

HTTP Request

DELETE https://adsapi.snapchat.com/v1/product_feeds/{product_feed_id}

Parameters

Parameter Default Description
product_feed_id Feed ID

Feed Upload

A Feed Upload is an individual upload of new data to the Product feed, when using the Product Feed schedule attribute the Feed Uploads are created automatically by the API at the set timings as specified by the schedule setting.

It’s possible to create a Feed Upload without using the schedule attribute, this is suitable for feeds that remain largely static and only need to be updated occasionally. Such an upload is referred to as a one time upload, one time uploads can only happen in product feeds where there is no schedule attribute defined.

Feed Upload attributes

Attribute Description Required Possible Values
url The FTP/SFTP/HTTP/HTTPS URL including file name where the product feed is to be fetched from R
update_type Indicates the type of update, REPLACE means existing product feed will be replaced by the new file, UPSERT means products in the uploaded file will be updated or added to the product feed, any products already in the product feed but missing in the file will be preserved R REPLACE, UPSERT
username The username to access the product feed O/Required if url is password protected
password The password to access the product feed O/Required if url is password protected
id The id of the upload Read only
feed_id The product feed id Read only
status Indicates the current status of the upload Read only INITIALIZED, FETCHING, PROCESSING, COMPLETE, ERRORED
summary A summary of the items affected by the upload including errors and recommendations Read only

Feed Upload Status

Status attribute Description
INITIALIZED The feed upload has been created and is expected to start downloading soon
FETCHING The file is currently being downloaded
PROCESSING The file is downloaded and the catalog is being updated
COMPLETE The file was downloaded and the catalog was updated
ERRORED All products in the upload failed because of a problem with the download or with the file

Feed Upload Summary

Summary attribute Description Possible Values
total_items Total number of items affected by the upload
items_modified Number of items that were modified by the upload
items_deleted Number of items that were deleted by the upload
items_errored Number of items that has an error
items_with_warnings Number of items that have a warning
issues_summary Summary of all errors and recommendations see errors and recommendations

Errors and Recommendations

Recommendation Description
CAT_RECOMMENDATION_MISSING_APP_INSTALL_PROPERTIES Properties required to run App Install Ads haven’t been provided.
CAT_RECOMMENDATION_MISSING_DEEP_LINK_PROPERTIES Properties required to run Deep Link Ads haven’t been provided.
Error Description
CAT_VALIDATION_ERROR_CATALOG_ID_INVALID Catalog id is invalid/malformed
CAT_VALIDATION_ERROR_EVENT_SOURCE_ID_INVALID Event source id is invalid/malformed
CAT_VALIDATION_ERROR_FEED_ID_INVALID Feed id is invalid/malformed
CAT_VALIDATION_ERROR_UPLOAD_ID_INVALID Upload id is invalid/malformed
CAT_VALIDATION_ERROR_FILTER_ID_INVALID Filter id is invalid/malformed
CAT_VALIDATION_ERROR_ORGANIZATION_ID_INVALID Organization id is invalid/malformed
CAT_VALIDATION_ERROR_PRODUCT_SET_ID_INVALID Product set id is invalid/malformed
CAT_VALIDATION_ERROR_SNAP_PRODUCT_ID_INVALID Snap product id is invalid
CAT_VALIDATION_ERROR_PRODUCT_SCAN_FILTER_INVALID Product scan filter is invalid
CAT_VALIDATION_ERROR_REQUIRED_INPUT_PARAMETER_EMPTY Required parameter is empty
CAT_VALIDATION_ERROR_REQUIRED_INPUT_PARAMETER_NULL Required parameter cannot be null
CAT_VALIDATION_ERROR_DUPLICATE_PRODUCT Duplicate Product detected. Please make sure product ‘id’ is unique
CAT_VALIDATION_ERROR_DEEP_LINK_INVALID Link is invalid
CAT_VALIDATION_ERROR_IMAGE_LINK_INVALID Image Link must be a well formed URL
CAT_VALIDATION_ERROR_PRODUCT_TYPE_INVALID Product Type is invalid
CAT_VALIDATION_ERROR_BRAND_INVALID Brand is invalid
CAT_VALIDATION_ERROR_ICON_MEDIA_URL_INVALID Icon Media Link must be a well formed URL
CAT_VALIDATION_ERROR_DEEP_LINK_APP_NAME_INVALID App Name is invalid
CAT_VALIDATION_ERROR_DEEP_LINK_ANDROID_INFO_INVALID Android Information is invalid/malformed
CAT_VALIDATION_ERROR_DEEP_LINK_STORE_ID_INVALID Apple Store ID is invalid/malformed
CAT_VALIDATION_ERROR_PRODUCT_LINK_INVALID Product Link must be a well formed URL
CAT_VALIDATION_ERROR_MOBILE_LINK_INVALID Mobile Link must be a well formed URL
CAT_VALIDATION_ERROR_ADDITIONAL_IMAGES_LINK_INVALID The additional image Link must be a well formed URL
CAT_VALIDATION_ERROR_ADDITIONAL_IMAGES_TAG_INVALID Image Tags for additional images is not valid
CAT_VALIDATION_ERROR_TOO_MANY_TAGS Too many tags have been used for a product
CAT_VALIDATION_ERROR_TOO_MANY_ADDITIONAL_IMAGES Too many additional images have been used for a product
CAT_VALIDATION_ERROR_PRODUCT_CONDITION_INVALID Product condition value is invalid
CAT_VALIDATION_ERROR_AVAILABILITY_INVALID Product availability value is invalid
CAT_VALIDATION_ERROR_ADULT_INVALID Adult value is invalid
CAT_VALIDATION_ERROR_REQUIRED_INPUT_PARAMETER_TOO_LARGE Parameter is too large
CAT_VALIDATION_ERROR_SALE_PRICE_EFFECTIVE_DATE_INVALID Sale Price Effective Date is invalid/malformed
CAT_VALIDATION_ERROR_GTIN_INVALID GTIN value is invalid
CAT_VALIDATION_ERROR_MPN_INVALID MPN value is invalid
CAT_VALIDATION_ERROR_COLOR_INVALID Color value is invalid
CAT_VALIDATION_ERROR_GENDER_INVALID Gender value is invalid
CAT_VALIDATION_ERROR_MATERIAL_INVALID Material value is invalid
CAT_VALIDATION_ERROR_PATTERN_INVALID Pattern is value invalid
CAT_VALIDATION_ERROR_SIZE_INVALID Size value is invalid
CAT_VALIDATION_ERROR_ITEM_GROUP_ID_INVALID Item Group ID is invalid
CAT_VALIDATION_ERROR_CUSTOM_LABEL_INVALID Custom Label is invalid
CAT_VALIDATION_ERROR_REQUIRED_INPUT_PARAMETER_MALFORMED Required input parameter is malformed
CAT_VALIDATION_ERROR_REQUIRED_INPUT_PARAMETER_TOO_SMALL Required input parameter is too small
CAT_VALIDATION_ERROR_PRODUCT_PRICE_INVALID Price is invalid/malformed
CAT_VALIDATION_ERROR_SALE_PRICE_INVALID Sale Price is invalid/malformed
CAT_VALIDATION_EXPIRATION_DATE_INVALID Expiration Date is invalid/malformed
CAT_VALIDATION_ERROR_INVALID_GOOGLE_PRODUCT_CATEGORY Google product category is invalid/malformed
CAT_VALIDATION_ERROR_AVAILABILITY_RADIUS_INVALID Availability Radius is invalid/malformed
CAT_VALIDATION_ERROR_GEOGRAPHIC_COORDINATES_INVALID Geographic Coordinates are invalid/malformed
CAT_VALIDATION_ERROR_AVAILABILITY_RADIUS_AND_GEOGRAPHIC_COORDINATE_MISSING Availability Radius and geographic coordinates are both required
CAT_FX_RATE_NOT_SUPPORTED The provided currency is currently not supported in our Fx Service
CAT_SALE_PRICE_EQUAL_OR_GREATER_THAN_PRICE Sale price is greater than or equal to the regular price
CAT_VALIDATION_ERROR_AGE_GROUP_INVALID Age Group is invalid
CAT_VALIDATION_ERROR_CURRENCY_INVALID Currency Code is invalid/malformed
CAT_VALIDATION_ERROR_DESCRIPTION_INVALID Description is invalid
CAT_VALIDATION_ERROR_TITLE_INVALID Title is invalid.
CAT_VALIDATION_ERROR_PRODUCT_ID_INVALID Product ‘ID’ is invalid
CAT_FEED_FILE_NO_DATA File containing feed is empty or cannot be fully parsed

Get all Feed Uploads

curl
"https://adsapi.snapchat.com/v1/product_feeds/c03a1fd9-97f2-4f87-a1c2-7696a8d6bde8/feed_uploads" \
  -H "Authorization: Bearer meowmeowmeow"

The above request returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f7e5a1b00ff0d38ed96d3af7c0001737e616473617069736300016275696c642d31663731616139352d312d3339312d3100010105",
    "feed_uploads": [
        {
            "sub_request_status": "SUCCESS",
            "feed_upload": {
                "created_at": "2020-10-08T00:15:06.631226Z",
                "updated_at": "2020-10-08T00:15:06.631226Z",
                "id": "f5e58ff4-1014-401a-baeb-5866e515deb0",
                "feed_id": "c03a1fd9-97f2-4f87-a1c2-7696a8d6bde8",
                "summary": {
                    "issues_summary": {}
                },
                "url": "https://www.example.com/productfeed/timber_product_feed.csv",
                "update_type": "REPLACE",
                "status": "INITIALIZED"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "feed_upload": {
                "created_at": "2020-10-07T23:15:00.702Z",
                "updated_at": "2020-10-07T23:15:35.624449Z",
                "id": "0aea4326-80cf-49de-9555-6d7c01566d9d",
                "feed_id": "c03a1fd9-97f2-4f87-a1c2-7696a8d6bde8",
                "summary": {
                    "total_items": 16,
                    "items_modified": 16,
                    "issues_summary": {
                        "recommendations": {
                            "CAT_RECOMMENDATION_MISSING_APP_INSTALL_PROPERTIES": 5,
                            "CAT_RECOMMENDATION_MISSING_DEEP_LINK_PROPERTIES": 5
                        }
                    }
                },
                "url": "https://www.example.com/productfeed/timber_product_feed.csv",
                "update_type": "REPLACE",
                "status": "COMPLETE"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "feed_upload": {
                "created_at": "2020-10-07T22:15:01.366260Z",
                "updated_at": "2020-10-07T22:15:32.186709Z",
                "id": "6d3e1ecd-362a-4386-b2b7-71b199d20c5b",
                "feed_id": "c03a1fd9-97f2-4f87-a1c2-7696a8d6bde8",
                "summary": {
                    "total_items": 7,
                    "items_modified": 7,
                    "issues_summary": {
                        "recommendations": {
                            "CAT_RECOMMENDATION_MISSING_APP_INSTALL_PROPERTIES": 7,
                            "CAT_RECOMMENDATION_MISSING_DEEP_LINK_PROPERTIES": 7
                        }
                    }
                },
                "url": "https://www.example.com/productfeed/timber_product_feed.csv",
                "update_type": "REPLACE",
                "status": "COMPLETE"
            }
        }
    ]
}

This request lists the 200 latest Feed Uploads for the Product feed in order of creation.

HTTP Request

GET https://adsapi.snapchat.com/v1/product_feeds/{product_feed_id}/feed_uploads

Parameters

Parameter Default Description
product_feed_id Feed ID

Create a Feed Upload

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"product_feeds":[{"catalog_id":"7ae3e924-dc70-48f6-9733-4d009d4f2152","name":"The No Schedule Feed","default_currency":"EUR","status":"ACTIVE"}]}' \
  "https://adsapi.snapchat.com/v1/catalogs/7ae3e924-dc70-48f6-9733-4d009d4f2152/product_feeds"

The above request creates a Product Feed without the scheduling attribute:

{
    "request_status": "SUCCESS",
    "request_id": "5f7e532800ff070665a0c9d0a00001737e616473617069736300016275696c642d31663731616139352d312d3339312d310001010b",
    "product_feeds": [
        {
            "sub_request_status": "SUCCESS",
            "product_feed": {
                "created_at": "2020-10-07T23:45:44.925724Z",
                "updated_at": "2020-10-07T23:45:44.925724Z",
                "id": "c79a127a-3ff2-4278-ae5a-f3f35f4093ae",
                "catalog_id": "7ae3e924-dc70-48f6-9733-4d009d4f2152",
                "name": "The No Schedule Feed",
                "default_currency": "EUR"
            }
        }
    ]
}
curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '{"feed_uploads":[{"url":"ftp://93.184.216.34/timber_product_feed.csv","username":"H0neyBadger","password":"BeezAreCool99","update_type":"REPLACE"}]}' \
   "https://adsapi.snapchat.com/v1/product_feeds/c79a127a-3ff2-4278-ae5a-f3f35f4093ae/feed_uploads"

The above request creates a one time upload of the designated file to the Product feed, the update_type REPLACE value stipulates all products in the current feed will be replaced by the products in the new file.:

{
    "request_status": "SUCCESS",
    "request_id": "5f7db87900ff0627f67519a13a0001737e616473617069736300016275696c642d31663731616139352d312d3339312d3100010121",
    "feed_uploads": [
        {
            "sub_request_status": "SUCCESS",
            "feed_upload": {
                "created_at": "2020-10-07T12:45:45.884998Z",
                "updated_at": "2020-10-07T12:45:45.884998Z",
                "id": "2c2a503a-01cf-4695-986b-b8281e7136e2",
                "feed_id": "c79a127a-3ff2-4278-ae5a-f3f35f4093ae",
                "summary": {
                    "issues_summary": {}
                },
                "url": "ftp://93.184.216.34/timber_product_feed.csv",
                "update_type": "REPLACE",
                "status": "INITIALIZED"
            }
        }
    ]
}

The Create Feed upload request is used to create a one off Feed Upload for a Product Feed where the schedule attribute has not been defined.

  1. Create a Product Feed without the schedule attribute.
  2. Create a Feed Upload specifying url and update_type, if the url is password protected username and password are required.

Body

Attribute Description Required Possible Values
url The FTP/SFTP/HTTP/HTTPS URL including file name where the product feed is to be fetched from R
update_type Indicates the type of update, REPLACE means existing product feed will be replaced by the new file, UPSERT means products in the uploaded file will be updated or added to the product feed, any products already in the product feed but missing in the file will be preserved R REPLACE, UPSERT
username The username to access the product feed O/Required if url is password protected
password The password to access the product feed O/Required if url is password protected

HTTP Request

POST https://adsapi.snapchat.com/v1/product_feeds/{product_feed_id}/feed_uploads

Parameters

Parameter Default Description
product_feed_id Feed ID

Get a Feed Upload

curl
"https://adsapi.snapchat.com/v1/feed_uploads/ea7534f3-5576-4698-b48c-5a955aca0747" \
  -H "Authorization: Bearer meowmeowmeow"

The above request returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5f7d150400ff0b8aba6ba67c710001737e616473617069736300016275696c642d31663731616139352d312d3339312d3100010121",
    "feed_uploads": [
        {
            "sub_request_status": "SUCCESS",
            "feed_upload": {
                "created_at": "2020-10-06T04:00:06.146753Z",
                "updated_at": "2020-10-06T04:03:06.001196Z",
                "id": "ea7534f3-5576-4698-b48c-5a955aca0747",
                "feed_id": "72cffebf-b91b-4af7-a8b9-d2a91e51b456",
                "summary": {
                    "total_items": 7,
                    "items_modified": 7,
                    "issues_summary": {
                        "recommendations": {
                            "CAT_RECOMMENDATION_MISSING_APP_INSTALL_PROPERTIES": 7,
                            "CAT_RECOMMENDATION_MISSING_DEEP_LINK_PROPERTIES": 7
                        }
                    }
                },
                "url": "ftp://93.184.216.34/timber_product_feed.csv",
                "update_type": "REPLACE",
                "status": "COMPLETE"
            }
        }
    ]
}

This request fetches a specific Feed upload, this contains a summary of any recommendations or feedback for the latest executed upload.

HTTP Request

GET https://adsapi.snapchat.com/v1/product_feeds/{product_feed_id}/feed_uploads

Parameters

Parameter Default Description
product_feed_id Feed ID

Catalog Diagnostics

curl -X POST \
  -d '{"facets": [{"property": "BRAND"}], "filter": {"AVAILABILITY": {"EQ": "IN_STOCK"}}}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/catalogs/f1180af0-949b-4439-8f62-021ac96cfcff

The above command returns JSON structured like this:


{
    "request_status": "SUCCESS",
    "request_id": "5ed4fe0a00ff00ff18b512bc3ae30001737e616473617069736300016275696c642d36653163373061642d312d3335352d3000010154",
    "summary": {
        "total_products": {
            "count": "100",
            "relation": "EQ"
        }
    },
    "facets": [
        {
            "facet": {
                "property": "BRAND"
            },
            "values": [
                {
                    "name": "Farmani",
                    "count": "89"
                },
                {
                    "name": "Rolo Ralph",
                    "count": "10"
                },
                {
                    "name": "Thomas Hillgren",
                    "count": "1"
                }
            ]
        }
    ]
}

Catalog diagnostics allows you to group existing items given the properties you define, either for an entire Catalog, or for a single Product Set.

The facets body allows you to specify a property to group items by. You can also use a single AND/OR operator to select up to ten additional item properties, this is defined within the filter part the request, you can filter by up to ten item properties using AND/OR.

If you want to keep the grouping to a single Product Set you can do so by using the product_set_id within the filter part of the request.

HTTP Request

POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/facets?limit=100

Parameters

Parameter Required Description
catalog_id R Catalog ID
limit O Integer, min 1, max 50, the number of groupings returned

Attributes

These attributes can be used within the facets part of

Attribute Description Required Possible values
property The property you want to group products by R AGE_GROUP, AVAILABILITY, BASE_PRICE_CURRENCY, BRAND, COLOR, CONDITION, CUSTOM_LABEL_0, CUSTOM_LABEL_1, CUSTOM_LABEL_2, CUSTOM_LABEL_3, CUSTOM_LABEL_4, GENDER, GOOGLE_PRODUCT_CATEGORY, ITEM_GROUP_ID, MATERIAL, PATTERN, PRICE_CURRENCY, PRODUCT_TYPE, SIZEEL_3, CUSTOM_LABEL_4, GOOGLE_PRODUCT_CATEGORY, ITEM_GROUP_ID, MATERIAL, PATTERN, SALE_PRICE_CURRENCY, SIZE, AGE_GROUP, AVAILABILITY, COLOR, CONDITION, GENDER, PRICE_CURRENCY, LOYALTY_PROGRAM, ACTIVITY, LOCALITY, POSTAL_CODE, COUNTRY_CODE, ORIGIN_AIRPORT, DESTINATION_AIRPORT, ORIGIN_CITY, DESTINATION_CITY
filter Optional filtering, can use one logical operator (AND, OR) O PRODUCT_SET_ID, AGE_GROUP, AVAILABILITY, BRAND, COLOR, CONDITION, CUSTOM_LABEL_0, CUSTOM_LABEL_1, CUSTOM_LABEL_2, CUSTOM_LABEL_3, CUSTOM_LABEL_4, GENDER, GOOGLE_PRODUCT_CATEGORY, ITEM_GROUP_ID, MATERIAL, PATTERN, PRICE_CURRENCY, PRODUCT_TYPE, SIZE, BASE_PRICE_AMOUNT, SALE_PRICE_AMOUNT, NEIGHBORHOOD, STAR_RATING, LOYALTY_PROGRAM, ACTIVITY, LOCALITY, POSTAL_CODE, COUNTRY_CODE, NUMBER_OF_RATERS, GUEST_RATING_SCORE, ORIGIN_AIRPORT, DESTINATION_AIRPORT, ORIGIN_CITY, DESTINATION_CITY

Filter Operator

Operator Description Can be used with
EQ Equal to Integer, Float, String
NEQ Not Equal to Integer, Float, String
GT Greater than Integer, Float
GTE Greater than or equal to Integer, Float
LT Less than Integer, Float
LTE Less than or equal to Integer, Float
CONTAINS Contains String
NOT_CONTAINS Does not contain String
I_CONTAINS Contains - Case insensitive String
I_NOT_CONTAINS Does not contain - Case insensitive String
STARTS_WITH Starts with String
I_STARTS_WITH Starts with - Case insensitive String
IS_ANY Is any of the list. Only works with strings containing alphanumeric characters List of Strings
IS_NOT_ANY Is not any of the list. Only works with strings containing alphanumeric characters List of Strings
I_IS_ANY Is any of the list - Case insensitive. Only works with strings containing alphanumeric characters List of Strings
I_IS_NOT_ANY Is not any of the list - Case insensitive. Only works with strings containing alphanumeric characters List of Strings

Example 1 - Diagnostics

Diagnostics for a single Product Set using product_set_id

curl -X POST \
  -d '{"facets": [{"property": "BRAND"}], "filter": {"PRODUCT_SET_ID": {"EQ": "99246572-4c2b-4e66-935c-1b1ee1ea2360"}}}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/catalogs/8318ff5c-78f7-47db-8a32-675f0b787c75/facets?limit=50

The above command returns JSON structured like this:


{
    "request_status": "SUCCESS",
    "request_id": "5ed517ff0000ff0a11b020203f100001737e616473617069736300016275696c642d36653163373061642d312d3335352d300001014f",
    "summary": {
        "total_products": {
            "count": "33",
            "relation": "EQ"
        }
    },
    "facets": [
        {
            "facet": {
                "property": "BRAND"
            },
            "values": [
                {
                    "name": "Rolo Ralph",
                    "count": "33"
                }
            ]
        }
    ]
}

Example 2 - Diagnostics

Diagnostics using several AND operators (gender, availablity, size)

curl -X POST \
  -d '{"facets": [{"property": "BRAND"}], "filter": {"AND": [{"GENDER": {"EQ": "UNISEX"}},{"AVAILABILITY": {"EQ": "IN_STOCK"}},{"SIZE": {"EQ": "M"}}]}}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/catalogs/8318ff5c-78f7-47db-8a32-675f0b787c75/facets?limit=50

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ed5252800ff0e424ba54e30da0001737e616473617069736300016275696c642d36653163373061642d312d3335352d3000010115",
    "summary": {
        "total_products": {
            "count": "11",
            "relation": "EQ"
        }
    },
    "facets": [
        {
            "facet": {
                "property": "BRAND"
            },
            "values": [
                {
                    "name": "Rolo Ralph",
                    "count": "11"
                }
            ]
        }
    ]
}

Example 3 - Diagnostics

Diagnostics using several AND operators (product_set_id, gender, availablity, size)

curl -X POST \
  -d '{"facets": [{"property": "BRAND"}], "filter": {"AND": [{"PRODUCT_SET_ID": {"EQ":"99246572-4c2b-4e66-935c-1b1ee1ea2360"}},{"GENDER": {"EQ": "UNISEX"}},{"AVAILABILITY": {"EQ": "IN_STOCK"}},{"SIZE": {"EQ": "M"}}]}}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/catalogs/8318ff5c-78f7-47db-8a32-675f0b787c75/facets?limit=50

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ed5252800ff0e424ba54e30da0001737e616473617069736300016275696c642d36653163373061642d312d3335352d3000010115",
    "summary": {
        "total_products": {
            "count": "11",
            "relation": "EQ"
        }
    },
    "facets": [
        {
            "facet": {
                "property": "BRAND"
            },
            "values": [
                {
                    "name": "Rolo Ralph",
                    "count": "11"
                }
            ]
        }
    ]
}

The product search is used to search a catalog for products given a provided filter, each level of the filter can only have one operator and we allow up to two levels of nesting, for each operator we can have up to 10 fields

HTTP Request

POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/products/search

Request Parameters

Parameter Required Description
catalog_id R Catalog ID

Body Parameters

Parameter Required Description
limit O this pagination variable specifies the number of products per page 50 - 1000

Filter properties

Property Possible values
AGE_GROUP NEWBORN, INFANT, TODDLER, KIDS, ADULT
AVAILABILITY IN_STOCK, OUT_OF_STOCK, PREORDER, DISCONTINUED, AVAILABLE_FOR_ORDER
BRAND
COLOR
CONDITION NEW, REFURBISHED, USED
CUSTOM_LABEL_0
CUSTOM_LABEL_1
CUSTOM_LABEL_2
CUSTOM_LABEL_3
CUSTOM_LABEL_4
GENDER FEMALE, MALE, UNISEX
GOOGLE_PRODUCT_CATEGORY
ID
ITEM_GROUP_ID
MATERIAL
PATTERN
PRICE_AMOUNT
PRICE_CURRENCY
PRODUCT_TYPE
SIZE
TITLE
PRODUCT_SET_ID
PRODUCT_STATUS COMPLETE, FAILED_MEDIA
ELIGIBLE_AD_TYPE APP_INSTALL, REMOTE_WEBPAGE, DEEPLINK_ATTACHMENT

Filter Operator

Operator Description Can be used with
EQ Equal to Integer, Float, String
NEQ Not Equal to Integer, Float, String
GT Greater than Integer, Float
GTE Greater than or equal to Integer, Float
LT Less than Integer, Float
LTE Less than or equal to Integer, Float
CONTAINS Contains String
NOT_CONTAINS Does not contain String
I_CONTAINS Contains - Case insensitive String
I_NOT_CONTAINS Does not contain - Case insensitive String
STARTS_WITH Starts with String
I_STARTS_WITH Starts with - Case insensitive String
IS_ANY Is any of the list. Only works with strings containing alphanumeric characters List of Strings
IS_NOT_ANY Is not any of the list. Only works with strings containing alphanumeric characters List of Strings
I_IS_ANY Is any of the list - Case insensitive. Only works with strings containing alphanumeric characters List of Strings
I_IS_NOT_ANY Is not any of the list - Case insensitive. Only works with strings containing alphanumeric characters List of Strings

Request the entire Product Catalog using a pagination of 50 products, setting "limit":50 attribute achieves this.

curl -X POST \
  -d '{"limit": 50}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/products/search

The above command returns JSON structured like this (this response has been shortened):

{
    "request_status": "SUCCESS",
    "request_id": "5f19a01000ff00fff430ee807f720001737e616473617069736300016275696c642d63616265303361622d312d3336392d3000010108",
    "summary": {
        "total_products": {
            "count": "209",
            "relation": "EQ"
        }
    },
    "paging": {
        "next_link": "https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/products/search?cursor=IlNDLTE1MCI=&limit=50",
        "next_link_body": "H4sIAAAAAAAAAONiAAB1-ja7AgAAAA=="
    },
    "products": [
        {
            "sub_request_status": "SUCCESS",
            "product": {
                "id": "9156245200715568072",
                "external_id": "SC-101",
                "catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
                "title": "Denim Shirt - Women's",
                "description": "Women's denim shirt - crafted from the finest squirrel made denim.",
                "link": "https://www.example.com/ch/en/jj/denim/denim-jackets/jean-cj-195-denim-jacket-12169148.html?cgid=jj-outerwear-denim&dwvar_colorPattern=12169148_BlueDenim",
                "image_link": "https://www.example.com/dw/image/v2/ABBT_PRD/on/demandware.static/-/Sites-bd-catalog/default/dw7809338c/pim-static/large/12169148_BlueDenim_003_ProductLarge.jpg?sw=685",
                "availability": "in stock",
                "google_product_category": "Apparel & Accessories > Clothing > Shirts & Tops",
                "product_type": "Women's > Tops > Denim",
                "brand": "Honeybear Denim Jackets",
                "gtin": "912345678905",
                "mpn": "912345678905",
                "condition": "new",
                "age_group": "adult",
                "color": "blue",
                "gender": "female",
                "size": "L",
                "item_group_id": "SC-1",
                "custom_label_0": "Bestseller",
                "price": {
                    "value": "24.99",
                    "currency": "USD"
                },
                "sale_price": {
                    "value": "22.99",
                    "currency": "USD"
                },
                "created_at": "2020-07-23T14:34:56.532179Z",
                "updated_at": "2020-07-23T14:34:56.532202Z",
                "additional_media": [
                    {
                        "url": "https://example.com/images/womensdenimshirt/altimage.jpeg"
                    }
                ]
            }
        },
    ...
        {
            "sub_request_status": "SUCCESS",
            "product": {
                "id": "9151706793146519301",
                "external_id": "SC-150",
                "catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
                "title": "Denim trousers",
                "description": "Blue jeans for men",
                "link": "https://www.example.com.com/loose-fit-jeans-1999.html?cgid=jj-nl-some-37&dwvar_colorPattern=12179324_BlueDenim",
                "image_link": "https://www.example.com/static/large/11239324_BlueDenim_003_ProductLarge.jpg",
                "availability": "in stock",
                "product_type": "Unisex > Trousers",
                "brand": "Honeybear Denim",
                "gtin": "912345678905",
                "mpn": "912345678905",
                "condition": "new",
                "age_group": "adult",
                "color": "blue",
                "gender": "unisex",
                "size": "M",
                "item_group_id": "SC-5",
                "custom_label_0": "Bestseller",
                "price": {
                    "value": "14.99",
                    "currency": "USD"
                },
                "created_at": "2020-07-23T14:34:56.536774Z",
                "updated_at": "2020-07-23T14:34:56.536779Z"
            }
        }
    ]
}

Request all products within a specific Product Set.

curl -X POST \
  -d '{"limit": 50,"filter": {"PRODUCT_SET_ID": {"EQ": "dcaa2832-48bd-4df6-8ba5-0edac83971c2"}}}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/products/search

The above command returns JSON structured like this (this response has been shortened):

{
    "request_status": "SUCCESS",
    "request_id": "5f19a9fc00ff0356de38dde9990001737e616473617069736300016275696c642d63616265303361622d312d3336392d3000010131",
    "summary": {
        "total_products": {
            "count": "20",
            "relation": "EQ"
        }
    },
    "products": [
        {
            "sub_request_status": "SUCCESS",
            "product": {
                "id": "998335299479914169",
                "external_id": "SC-106",
                "catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
                "title": "Beanie hat",
                "description": "Honeybear knitted beanie hat",
                "link": "https://www.example.com/accessories/beanies/ackman-short-knit-beanie-beanie-12164650.html?cgid=jj-accessories-beanies&dwvar_colorPattern=12164650_WinterMoss",
                "image_link": "https://www.example.com/image/e/12164650_ProductLarge.jpg",
                "availability": "in stock",
                "product_type": "Unisex > Headwear",
                "brand": "Honeybear Headwear",
                "gtin": "912345678905",
                "mpn": "912345678905",
                "condition": "new",
                "age_group": "adult",
                "color": "red",
                "gender": "unisex",
                "size": "M",
                "item_group_id": "SC-6",
                "custom_label_0": "Bestseller",
                "price": {
                    "value": "14.99",
                    "currency": "USD"
                },
                "created_at": "2020-07-23T15:17:16.594913Z",
                "updated_at": "2020-07-23T15:17:16.594933Z"
            }
        },
        ...
        {
            "sub_request_status": "SUCCESS",
            "product": {
                "id": "9435790241890490957",
                "external_id": "SC-209",
                "catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
                "title": "Cap",
                "description": "Cap with Kevin",
                "link": "https://www.example.com/accessories/caps/billy-baseball-cap.html?ar_colorPattern=121_Black",
                "image_link": "https://www.example.com/image/9964499_Black_001_ProductLarge.jpg",
                "availability": "in stock",
                "product_type": "Unisex > Headwear",
                "brand": "Honeybear Caps",
                "gtin": "912345778905",
                "mpn": "912345778905",
                "condition": "new",
                "age_group": "adult",
                "color": "green",
                "gender": "unisex",
                "size": "M",
                "item_group_id": "SC-10",
                "custom_label_0": "Bestseller",
                "price": {
                    "value": "4.99",
                    "currency": "USD"
                },
                "created_at": "2020-07-23T15:17:16.597499Z",
                "updated_at": "2020-07-23T15:17:16.597501Z"
            }
        }
    ]
}

Request all products in a feed where the media failed due to being unavailable.

curl -X POST \
  -d '{"limit": 50,"filter":{"PRODUCT_STATUS": {"EQ": "FAILED_MEDIA"}}}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/products/search

The above command returns JSON structured like this (this response has been shortened):

{
    "request_status": "SUCCESS",
    "request_id": "5f1af77c00ff075e0536d7780d0001737e616473617069736300016275696c642d32363038643739372d312d3337302d3000010145",
    "summary": {
        "total_products": {
            "count": "12",
            "relation": "EQ"
        }
    },
    "products": [
        {
            "sub_request_status": "SUCCESS",
            "product": {
                "id": "9877985877291710328",
                "external_id": "W999-HOT-M",
                "catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
                "title": "Honeybear Bikini",
                "description": "A bikini made out of the finest fox crafted fabric.",
                "link": "https://www.example.com/products/womens-bikini-red.jpg",
                "image_link": "https://example.com/external/images/5a54e8920edac/94d9b4004d87f46722801c503514585a.jpg",
                "availability": "out of stock",
                "product_type": "Swimwear",
                "brand": "Honeybear Swimwear",
                "condition": "new",
                "age_group": "adult",
                "color": "red",
                "gender": "female",
                "item_group_id": "123",
                "custom_label_0": "Women's Bikini",
                "custom_label_2": "Subscription Available",
                "custom_label_4": "additional_images",
                "price": {
                    "value": "18.00",
                    "currency": "USD"
                },
                "created_at": "2020-07-24T15:00:12.854449Z",
                "updated_at": "2020-07-24T15:00:12.854470Z",
                "feed_id": "852733e2-6838-4c61-9d23-7e5fddaca3f8",
                "main_media": {
                    "url": "https://example.com/external/images/5a54e8920edac/94d9b4004d87f46722801c503514585a.jpg",
                    "internal_url_status": "FAILURE",
                    "internal_url_error_code": "NOT_FOUND"
                },
                "icon_media": {}
            }
        },
    ...
        {
            "sub_request_status": "SUCCESS",
            "product": {
                "id": "9940768843314259508",
                "external_id": "W9990-HTH-XXXL/XXXXL",
                "catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
                "title": "Women's Robe",
                "description": "This robe is the perfect addition to your wardrobe.",
                "link": "https://www.example.com/products/womens-robe.jpg",
                "image_link": "https://example.com/external/images/5a54e8920edac/b90a21dfe0c3da11d7b37232f599a5db.jpg",
                "availability": "in stock",
                "google_product_category": "Apparel & Accessories > Clothing > Sleepwear & Loungewear > Loungewear",
                "product_type": "Robes",
                "brand": "Honeybear Homewear",
                "condition": "new",
                "age_group": "adult",
                "color": "green",
                "gender": "female",
                "item_group_id": "368",
                "custom_label_0": "Women's Robe",
                "custom_label_2": "Subscription Not Available",
                "custom_label_4": "additional_images",
                "price": {
                    "value": "88.00",
                    "currency": "USD"
                },
                "created_at": "2020-07-24T15:00:12.856278Z",
                "updated_at": "2020-07-24T15:00:12.856287Z",
                "feed_id": "852733e2-6838-4c61-9d23-7e5fddaca3f8",
                "main_media": {
                    "url": "https://example.com/external/images/5a54e8920edac/b90a21dfe0c3da11d7b37232f599a5db.jpg",
                    "internal_url_status": "FAILURE",
                    "internal_url_error_code": "NOT_FOUND"
                },
                "icon_media": {}
            }
        }
    ]
}

Request all products within a specific Product Set, where the title attribute contains the term ‘jacket’ or ‘hat’, and where the availability is in stock and the product status is complete.

curl -X POST \
  -d '{"filter": {"AND": [{"OR": [{"TITLE": {"I_CONTAINS": "jacket"}},{"TITLE": {"I_CONTAINS": "hat"}}]},{"PRODUCT_STATUS": {"EQ": "COMPLETE"}},{"AVAILABILITY": {"EQ": "IN_STOCK" }},{"PRODUCT_SET_ID": {"EQ": "99246572-4c2b-4e66-935c-1b1ee1ea2360"}}]}}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/products/search

The above command returns JSON structured like this (this response has been shortened):

{
    "request_status": "SUCCESS",
    "request_id": "5f1ad42e00ff09810a9af6828c0001737e616473617069736300016275696c642d32363038643739372d312d3337302d300001015d",
    "summary": {
        "total_products": {
            "count": "11",
            "relation": "EQ"
        }
    },
    "products": [
        {
            "sub_request_status": "SUCCESS",
            "product": {
                "id": "9767298711984673596",
                "external_id": "SC-103",
                "catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
                "title": "Denim Jacket",
                "description": "Oversized denim jacket",
                "link": "https://www.example.com/index.php?jj-outerwear-denim&dwvar_colorPattern=12166869_BlueDenim",
                "image_link": "https://www.example.com/dw/image/large/12166811_BlueDenim_008_ProductLarge.jpg?sw=685",
                "availability": "in stock",
                "product_type": "Men's > Jackets > Denim",
                "brand": "Badger Denim",
                "gtin": "912345678905",
                "mpn": "912345678905",
                "condition": "new",
                "age_group": "adult",
                "color": "green",
                "gender": "unisex",
                "size": "M",
                "item_group_id": "SC-3",
                "custom_label_0": "Bestseller",
                "price": {
                    "value": "14.99",
                    "currency": "USD"
                },
                "created_at": "2020-07-24T12:29:35.036864Z",
                "updated_at": "2020-07-24T12:29:35.036901Z"
            }
        },
    ...
        {
            "sub_request_status": "SUCCESS",
            "product": {
                "id": "9285992718921035814",
                "external_id": "SC-193",
                "catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
                "title": "Denim Jacket",
                "description": "Skinny fit denim jacket",
                "link": "https://www.example.com/index.php?bd-outerwear-denim&dwvar_colorPattern=12166869_BlueDenim",
                "image_link": "https://www.example.com/dw/image/large/12166869_BlueDenim_003_ProductLarge.jpg?sw=685",
                "availability": "in stock",
                "product_type": "Men's > Jackets > Denim",
                "brand": "Honeybear Denim",
                "gtin": "912345678905",
                "mpn": "912345678905",
                "condition": "new",
                "age_group": "adult",
                "color": "light blue",
                "gender": "unisex",
                "size": "M",
                "item_group_id": "SC-3",
                "custom_label_0": "Bestseller",
                "price": {
                    "value": "24.99",
                    "currency": "USD"
                },
                "created_at": "2020-07-24T12:29:35.039136Z",
                "updated_at": "2020-07-24T12:29:35.039142Z"
            }
        }
    ]
}

The hotel search is used to search a catalog for hotels given a provided filter, each level of the filter can only have one operator and we allow up to two levels of nesting, for each operator we can have up to 10 fields

HTTP Request

POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/hotels/search

Request Parameters

Parameter Required Description
catalog_id R Catalog ID

Body Parameters

Parameter Required Description
limit O this pagination variable specifies the number of products per page 50 - 1000

Filter properties

Property Possible values
ID
NAME
BASE_PRICE_AMOUNT
BASE_PRICE_CURRENCY
SALE_PRICE_AMOUNT
SALE_PRICE_CURRENCY
BRAND
NEIGHBORHOOD
STAR_RATING
LOYALTY_PROGRAM
ACTIVITY ACTIVE, INACTIVE
CUSTOM_LABEL_0
CUSTOM_LABEL_1
CUSTOM_LABEL_2
CUSTOM_LABEL_3
CUSTOM_LABEL_4
LOCALITY
POSTAL_CODE
COUNTRY_CODE
NUMBER_OF_RATERS
GUEST_RATING_SCORE
PRODUCT_SET_ID
PRODUCT_STATUS COMPLETE, FAILED_MEDIA
ELIGIBLE_AD_TYPE APP_INSTALL, REMOTE_WEBPAGE, DEEPLINK_ATTACHMENT

Filter Operator

Operator Description Can be used with
EQ Equal to Integer, Float, String
NEQ Not Equal to Integer, Float, String
GT Greater than Integer, Float
GTE Greater than or equal to Integer, Float
LT Less than Integer, Float
LTE Less than or equal to Integer, Float
CONTAINS Contains String
NOT_CONTAINS Does not contain String
I_CONTAINS Contains - Case insensitive String
I_NOT_CONTAINS Does not contain - Case insensitive String
STARTS_WITH Starts with String
I_STARTS_WITH Starts with - Case insensitive String
IS_ANY Is any of the list. Only works with strings containing alphanumeric characters List of Strings
IS_NOT_ANY Is not any of the list. Only works with strings containing alphanumeric characters List of Strings
I_IS_ANY Is any of the list - Case insensitive. Only works with strings containing alphanumeric characters List of Strings
I_IS_NOT_ANY Is not any of the list - Case insensitive. Only works with strings containing alphanumeric characters List of Strings

Request the entire Hotel Catalog using a pagination of 50 products, setting "limit":50 attribute achieves this.

curl -X POST \
  -d '{"limit": 50}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/hotels/search

The above command returns JSON structured like this (this response has been shortened):

{
    "request_status": "SUCCESS",
    "request_id": "5f19a01000ff00fff430ee807f720001737e616473617069736300016275696c642d63616265303361622d312d3336392d3000010108",
    "summary": {
        "total_products": {
            "count": "209",
            "relation": "EQ"
        }
    },
    "paging": {
        "next_link": "https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/hotels/search?cursor=IlNDLTE1MCI=&limit=50",
        "next_link_body": "H4sIAAAAAAAAAONiAAB1-ja7AgAAAA=="
    },
    "products": [
        {
            "sub_request_status": "SUCCESS",
            "product": {
                "id": "9156245200715568072",
                "external_id": "SC-101",
                "created_at": "2020-07-23T14:34:56.532179Z",
                "updated_at": "2020-07-23T14:34:56.532202Z",
                "catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
                "name": "Snapchat Hotel",
                "description": "Located in sunny Santa Monica",
                "link": "https://www.example.com/hotel",
                "mobile_link": "https://www.m.example.com/hotel",
                "main_media": {
                    "url": "https://storage.example.com/hotels-assets/image1926.jpg",
                    "tags": [
                        "Swimming pool",
                        "Gym"
                    ]
                },
                "additional_media": [
                    {
                        "url": "https://storage.example.com/hotels-assets/image19262.jpg",
                        "tags": [
                            "Lobby view",
                            "Overview"
                        ]
                    }
                ],
                "address": {
                    "line": "1600 Pennsylvania Avenue",
                    "line2": "Unit 1",
                    "locality": "Los Angeles",
                    "postal_code": "90210",
                    "region": "California",
                    "country_code": "US"
                },
                "price": {
                    "value": "199",
                    "currency": "USD"
                },
                "sale_price": {
                    "value": "299",
                    "currency": "USD"
                },
                "neighborhoods": [
                    "uptown",
                    "downtown"
                ],
                "geographic_coordinates": {
                    "longitude": 2.294464,
                    "latitude": 48.858353
                },
                "guest_ratings": {
                    "rating_system": "tripAdvisor", 
                    "score": "7.8", 
                    "max_score": "10", 
                    "number_of_reviewers": "300"
                },
                "star_rating": "3.5",
                "ios_app_link": {
                    "url": "myapp://a/random/path",
                    "app_store_id": "427916203",
                    "app_name": "Snapchat Hotel App"
                },
                "android_app_link": {
                    "url": "https://snapchathoteldeeplink.com",
                    "package": "com.snap.hotel",
                    "app_name": "Snapchat Hotel App"
                },
                "loyalty_program": "Premium program",
                "custom_labels": {},
                "activity": "ACTIVE",
            }
        },
    ...
          {
            "sub_request_status": "SUCCESS",
            "product": {
                "id": "9156245200715568072",
                "external_id": "SC-101",
                "created_at": "2020-07-23T14:34:56.532179Z",
                "updated_at": "2020-07-23T14:34:56.532202Z",
                "catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
                "name": "Fantastic Hotel",
                "description": "This hotel features a restaurant, an outdoor pool, and a front-desk safe.",
                "link": "https://www.example.com/hotel",
                "brand": "Independent",
                "main_media": {
                    "url": "https://storage.example.com/hotels-assets/image1.jpg",
                    "tags": ["Lobby View"]
                },
                "address":  {
                    "line1": "342 Snap Avenue",
                    "line2": "Unit 505",
                    "locality": "Las Vegas",
                    "region": "Nevada",
                    "postal_code": "90210",
                    "country": "US"
                },
                "price": {
                    "value": "499",
                    "currency": "USD"
                },
                "sale_price": {
                    "value": "599",
                    "currency": "USD"
                },
                "neighborhoods": [
                    "eastside",
                ],
                "geographic_coordinates": {
                    "longitude": 24.294464,
                    "latitude": -48.858353
                },
                "guest_ratings": {
                    "rating_system": "tripAdvisor", 
                    "score": "7.8", 
                    "max_score": "10", 
                    "number_of_reviewers": "300"
                },
                "star_rating": "2.5",
                "ios_app_link": {
                    "url": "myapp://a/random/path",
                    "app_store_id": "427916203",
                    "app_name": "Snapchat Hotel App"
                },
                "android_app_link": {
                    "url": "https://snapchathoteldeeplink.com",
                    "package": "com.snap.hotel",
                    "app_name": "Snapchat Hotel App"
                },
                "loyalty_program": "Loyalty Diamond Program",
                "custom_labels": {},
                "activity": "ACTIVE",
            }
        },
    ]
}

Request all hotels within a specific Product Set, where the name attribute contains the term ‘Snap’ or ‘elmwood’, and the star rating is greater or equal than 3.5.

curl -X POST \
  -d '{"filter": {"AND":[{"OR":[{"NAME": {"I_CONTAINS": "Snap"}},{"NAME": {"I_CONTAINS": "elmwood"}}]},{"STAR_RATING": {"GTE": "3.5"}}]}}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/hotels/search

The above command returns JSON structured like this (this response has been shortened):

{
    "request_status": "SUCCESS",
    "request_id": "5f19a01000ff00fff430ee807f720001737e616473617069736300016275696c642d63616265303361622d312d3336392d3000010108",
    "summary": {
        "total_hotels": {
            "count": "1",
            "relation": "EQ"
        }
    },
    "hotels": [
        {
            "sub_request_status": "SUCCESS",
            "product": {
                "id": "9156245200715568072",
                "external_id": "SC-101",
                "created_at": "2020-07-23T14:34:56.532179Z",
                "updated_at": "2020-07-23T14:34:56.532202Z",
                "catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
                "name": "Snapchat Hotel",
                "description": "Located in sunny Santa Monica",
                "link": "https://www.example.com/hotel",
                "mobile_link": "https://www.m.example.com/hotel",
                "main_media": {
                    "url": "https://storage.example.com/hotels-assets/image1926.jpg",
                    "tags": [
                        "Swimming pool",
                        "Gym"
                    ]
                },
                "additional_media": [
                    {
                        "url": "https://storage.example.com/hotels-assets/image19262.jpg",
                        "tags": [
                            "Lobby view",
                            "Overview"
                        ]
                    }
                ],
                "address": {
                    "line": "1600 Pennsylvania Avenue",
                    "line2": "Unit 1",
                    "locality": "Los Angeles",
                    "postal_code": "90210",
                    "region": "California",
                    "country_code": "US"
                },
                "price": {
                    "value": "199",
                    "currency": "USD"
                },
                "sale_price": {
                    "value": "299",
                    "currency": "USD"
                },
                "neighborhoods": [
                    "uptown",
                    "downtown"
                ],
                "geographic_coordinates": {
                    "longitude": 2.294464,
                    "latitude": 48.858353
                },
                "guest_ratings": {
                    "rating_system": "tripAdvisor", 
                    "score": "7.8", 
                    "max_score": "10", 
                    "number_of_reviewers": "300"
                },
                "star_rating": "3.5",
                "ios_app_link": {
                    "url": "myapp://a/random/path",
                    "app_store_id": "427916203",
                    "app_name": "Snapchat Hotel App"
                },
                "android_app_link": {
                    "url": "https://snapchathoteldeeplink.com",
                    "package": "com.snap.hotel",
                    "app_name": "Snapchat Hotel App"
                },
                "loyalty_program": "Premium program",
                "custom_labels": {},
                "activity": "ACTIVE",
            }
        },
    ]
}

The flight search is used to search a catalog for flights given a provided filter, each level of the filter can only have one operator and we allow up to two levels of nesting, for each operator we can have up to 10 fields

HTTP Request

POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/flights/search

Request Parameters

Parameter Required Description
catalog_id R Catalog ID

Body Parameters

Parameter Required Description
limit O this pagination variable specifies the number of products per page 50 - 1000

Filter properties

Property Possible values
ID
ORIGIN_AIRPORT
DESTINATION_AIRPORT
ORIGIN_CITY
DESTINATION_CITY
PRICE_AMOUNT
CUSTOM_LABEL_0
CUSTOM_LABEL_1
CUSTOM_LABEL_2
CUSTOM_LABEL_3
CUSTOM_LABEL_4
ITEM_SET_ID
PRODUCT_STATUS COMPLETE, FAILED_MEDIA
ELIGIBLE_AD_TYPE APP_INSTALL, REMOTE_WEBPAGE, DEEPLINK_ATTACHMENT

Filter Operator

Operator Description Can be used with
EQ Equal to Integer, Float, String
NEQ Not Equal to Integer, Float, String
GT Greater than Integer, Float
GTE Greater than or equal to Integer, Float
LT Less than Integer, Float
LTE Less than or equal to Integer, Float
CONTAINS Contains String
NOT_CONTAINS Does not contain String
I_CONTAINS Contains - Case insensitive String
I_NOT_CONTAINS Does not contain - Case insensitive String
STARTS_WITH Starts with String
I_STARTS_WITH Starts with - Case insensitive String
IS_ANY Is any of the list. Only works with strings containing alphanumeric characters List of Strings
IS_NOT_ANY Is not any of the list. Only works with strings containing alphanumeric characters List of Strings
I_IS_ANY Is any of the list - Case insensitive. Only works with strings containing alphanumeric characters List of Strings
I_IS_NOT_ANY Is not any of the list - Case insensitive. Only works with strings containing alphanumeric characters List of Strings

Request the entire Flight Catalog using a pagination of 50 products, setting "limit":50 attribute achieves this.

curl -X POST \
  -d '{"limit": 50}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/flights/search

The above command returns JSON structured like this (this response has been shortened):

{
    "request_status": "SUCCESS",
    "request_id": "5f19a01000ff00fff430ee807f720001737e616473617069736300016275696c642d63616265303361622d312d3336392d3000010108",
    "summary": {
        "total_flights": {
            "count": "209",
            "relation": "EQ"
        }
    },
    "paging": {
        "next_link": "https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/flights/search?cursor=IlNDLTE1MCI=&limit=50",
        "next_link_body": "H4sIAAAAAAAAAONiAAB1-ja7AgAAAA=="
    },
    "flights": [
        {
            "sub_request_status": "SUCCESS",
            "flight": {
                "id": "3675153106588450894",
                "external_id": "1",
                "catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
                "created_at": "2022-07-06T01:14:01.354366Z",
                "updated_at": "2022-07-06T02:12:36.444333Z",
                "origin_airport_code": "BWI",
                "destination_airport_code": "SEA",
                "link": "https://www.example.com/flights/tt0080339/2",
                "description": "Flight to Seattle from Baltimore",
                "price": {
                    "value": "95.00",
                    "currency": "USD"
                },
                "main_media": {
                    "url": "https://storage.snap-flights-example.com/flights-assets/image1.jpg",
                    "tags": [
                        "banner"
                    ]
                },
                "icon_media": {
                    "url": "https://storage.snap-flights-example.com/flights-assets/icon.jpg",
                },
                "additional_media": [
                    {
                        "url": "https://storage.snap-flights-example.com/flights-assets/image2.jpg",
                    }
                ],
                "origin_city": "Baltimore",
                "destination_city": "Seattle",
                "ios_app_link": {
                    "url": "myapp://a/random/path",
                    "app_store_id": "427916203",
                    "app_name": "Snap Flight App"
                },
                "android_app_link": {
                    "url": "https://snapairplanedeeplink.com",
                    "package": "com.snap.airplane",
                    "app_name": "Snap Flight App"
                },
                "custom_labels": {}
            }
        },
    ...
        {
            "sub_request_status": "SUCCESS",
            "flight": {
                "id": "877657809172084551",
                "external_id": "6",
                "catalog_id": "6d5def3e-a2af-4dcc-88c1-9da72632e25f",
                "created_at": "2022-07-06T01:14:01.354366Z",
                "updated_at": "2022-07-06T02:12:26.927293Z",
                "origin_airport_code": "SFO",
                "destination_airport_code": "LAX",
                "link": "https://www.example.com/flights/tt0080339/4",
                "description": "Flight SFO to LAX",
                "price": {
                    "value": "495.00",
                    "currency": "USD"
                },
                "main_media": {
                    "url": "https://storage.snap-flights-example.com/flights-assets/image1.jpg",
                    "tags": [
                        "banner"
                    ]
                },
                "icon_media": {
                    "url": "https://storage.snap-flights-example.com/flights-assets/icon.jpg",
                },
                "additional_media": [
                    {
                        "url": "https://storage.snap-flights-example.com/flights-assets/image2.jpg",
                    }
                ],
                "origin_city": "San Francisco",
                "destination_city": "Los Angeles",
                "ios_app_link": {
                    "url": "myapp://a/random/path",
                    "app_store_id": "427916203",
                    "app_name": "Snap Flight App"
                },
                "android_app_link": {
                    "url": "https://snapairplanedeeplink.com",
                    "package": "com.movie.airplane",
                    "app_name": "Snap Flight App"
                },
                "custom_labels": {}
            }
        },
    ]
}

Request all flights within a specific Product Set, where the origin airport attribute contains the term ‘BWI’.

  -d '{"filter": {"ORIGIN_AIRPORT": {"CONTAINS": "BWI"}}}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/catalogs/8818ff5c-78f7-47db-8a88-675f0b787c78/flights/search

The above command returns JSON structured like this (this response has been shortened):

{
    "request_status": "SUCCESS",
    "request_id": "5f19a01000ff00fff430ee807f720001737e616473617069736300016275696c642d63616265303361622d312d3336392d3000010108",
    "summary": {
        "total_flights": {
            "count": "209",
            "relation": "EQ"
        }
    },
     "flights": [
        {
            "sub_request_status": "SUCCESS",
            "flight": {
                "id": "3675153106588450894",
                "external_id": "1",
                "catalog_id": "8818ff5c-78f7-47db-8a88-675f0b787c78",
                "created_at": "2022-07-06T01:14:01.354366Z",
                "updated_at": "2022-07-06T02:12:36.444333Z",
                "origin_airport_code": "BWI",
                "destination_airport_code": "SEA",
                "link": "https://www.example.com/flights/tt0080339/2",
                "description": "Flight to Seattle from Baltimore",
                "price": {
                    "value": "95.00",
                    "currency": "USD"
                },
                "main_media": {
                    "url": "https://storage.snap-flights-example.com/flights-assets/image1.jpg",
                    "tags": [
                        "banner"
                    ]
                },
                "icon_media": {
                    "url": "https://storage.snap-flights-example.com/flights-assets/icon.jpg",
                },
                "additional_media": [
                    {
                        "url": "https://storage.snap-flights-example.com/flights-assets/image2.jpg",
                    }
                ],
                "origin_city": "Baltimore",
                "destination_city": "Seattle",
                "ios_app_link": {
                    "url": "myapp://a/random/path",
                    "app_store_id": "427916203",
                    "app_name": "Snap Flight App"
                },
                "android_app_link": {
                    "url": "https://snapairplanedeeplink.com",
                    "package": "com.snap.airplane",
                    "app_name": "Snap Flight App"
                },
                "custom_labels": {}
            }
        },
    ...
        {
            "sub_request_status": "SUCCESS",
            "flight": {
                "id": "877657809172084551",
                "external_id": "3",
                "catalog_id": "6d5def3e-a2af-4dcc-88c1-9da72632e25f",
                "created_at": "2022-07-06T01:14:01.354366Z",
                "updated_at": "2022-07-06T02:12:26.927293Z",
                "origin_airport_code": "BWI",
                "destination_airport_code": "LAX",
                "link": "https://www.example.com/flights/tt0080339/4",
                "description": "Flight BWI to LAX",
                "price": {
                    "value": "295.00",
                    "currency": "USD"
                },
                "main_media": {
                    "url": "https://storage.snap-flights-example.com/flights-assets/image1.jpg",
                    "tags": [
                        "banner"
                    ]
                },
                "icon_media": {
                    "url": "https://storage.snap-flights-example.com/flights-assets/icon.jpg",
                },
                "additional_media": [
                    {
                        "url": "https://storage.snap-flights-example.com/flights-assets/image2.jpg",
                    }
                ],
                "origin_city": "Baltimore",
                "destination_city": "Los Angeles",
                "ios_app_link": {
                    "url": "myapp://a/random/path",
                    "app_store_id": "427916203",
                    "app_name": "Snap Flight App"
                },
                "android_app_link": {
                    "url": "https://snapairplanedeeplink.com",
                    "package": "com.movie.airplane",
                    "app_name": "Snap Flight App"
                },
                "custom_labels": {}
            }
        },
    ]
}

Product Set

A product set is a group of products from your catalog defined by filters.

Create a Product Set

Parameter Description
name Name of the Product Set
filter Filter rule to be applied. See table below

Product Set Filter

Parameter Description
operator At most 1 type of logical operator (AND, OR)
product attribute The attribute of the product to filter on
filter operator The operator to be used
filter value The value to be matched

Filter Operator

Operator Description Can be used with
EQ Equal to Integer, Float, String
NEQ Not Equal to Integer, Float, String
GT Greater than Integer, Float
GTE Greater than or equal to Integer, Float
LT Less than Integer, Float
LTE Less than or equal to Integer, Float
CONTAINS Contains String
NOT_CONTAINS Does not contain String
I_CONTAINS Contains - Case insensitive String
I_NOT_CONTAINS Does not contain - Case insensitive String
STARTS_WITH Starts with String
I_STARTS_WITH Starts with - Case insensitive String
IS_ANY Is any of the list. Only works with strings containing alphanumeric characters List of Strings
IS_NOT_ANY Is not any of the list. Only works with strings containing alphanumeric characters List of Strings
I_IS_ANY Is any of the list - Case insensitive. Only works with strings containing alphanumeric characters List of Strings
I_IS_NOT_ANY Is not any of the list - Case insensitive. Only works with strings containing alphanumeric characters List of Strings

Product attributes And Supported Filters

Product Attribute Filter Operators Supported Filter Value
AGE_GROUP EQ, NEQ NEWBORN, INFANT, TODDLER, KIDS, ADULT
AVAILABILITY EQ, NEQ IN_STOCK, OUT_OF_STOCK, PREORDER, DISCONTINUED, AVAILABLE_FOR_ORDER
BRAND ALL String, List of Strings
COLOR ALL String, List of Strings
CONDITION EQ, NEQ NEW, REFURBISHED, USED
CUSTOM_LABEL_0 ALL String, List of Strings
CUSTOM_LABEL_1 ALL String, List of Strings
CUSTOM_LABEL_2 ALL String, List of Strings
CUSTOM_LABEL_3 ALL String, List of Strings
CUSTOM_LABEL_4 ALL String, List of Strings
GENDER EQ, NEQ MALE, FEMALE, UNISEX
GOOGLE_PRODUCT_CATEGORY ALL String, List of Strings
ID ALL String, List of Strings
ITEM_GROUP_ID ALL String, List of Strings
MATERIAL ALL String, List of Strings
PATTERN ALL String, List of Strings
PRICE_AMOUNT EQ, NEQ, GT, GTE, LT, LTE Number, 2 decimals
PRICE_CURRENCY EQ, NEQ ISO 4217 currency code
PRODUCT_TYPE ALL String, List of Strings
SIZE ALL String, List of Strings
TITLE ALL String, List of Strings

API Limits

Product Set Filter Entry Examples

TITLE contains “Red Shoes"

{"TITLE": {
       "CONTAINS": "Red Shoes"
   }
}

BRAND is any of “brand1”, “brand2”

{"BRAND": {
       "IS_ANY": ["brand1", "brand2"]
   }
}

AVAILABILITY is IN_STOCK

Note: Caps separated by underscore should be used for enums.

{"AVAILABILITY": {
       "EQ": "IN_STOCK"
   }
}

PRICE_AMOUNT greater than US$15.50

Note: Float value should be wrapped in a string

{"AND": [
       {"PRICE_AMOUNT": {
               "GT": "15.50"
           }
       },
       {"PRICE_CURRENCY": {
               "EQ": "US"
           }
       }
   ]
}

Filter chaining

Price greater than $15.50 and availability is in stock. Only one operator is allowed at a time.

{"AND": [
       {"PRICE_AMOUNT": {
               "GT": "15.50"
           }
       },
       {"AVAILABILITY": {
               "EQ": "IN_STOCK"
           }
       }
   ]
}

Create a Product Set

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
-d '{"product_sets": [{"name": "In Stock", "filter": {"AVAILABILITY": {"EQ": "IN_STOCK"}}}]}' \
https://adsapi.snapchat.com/v1/catalogs/306544db-be30-472c-ab87-c277b4d61d0f/product_sets

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "caf894e2-3bd1-420a-ae3a-5b1a19289488",
    "product_sets": [
        {
            "sub_request_status": "SUCCESS",
            "product_set": {
                "id": "8d2d659e-0e3c-4938-a417-09d1a8fa4348",
                "catalog_id": "306544db-be30-472c-ab87-c277b4d61d0f",
                "name": "In Stock",
                "filter": {
                    "AVAILABILITY": {
                        "EQ": "IN_STOCK"    
                    }
                },
                "created_at": "2019-06-14T18:38:49.640871Z",
                "updated_at": "2019-06-14T18:38:49.640871Z"
            }
        }
    ]
}

This creates an Product Set within a Catalog.

Attributes

Attribute Description Required Possible Values
name Name of the Product Set Yes
filter Filter rule to be applied Yes See tables above

HTTP Request

POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/product_sets

Parameters

Parameter Default Description
catalog_id Catalog ID

ERRORS

Error Cause
CAT_VALIDATION_ERROR_INVALID_PRODUCT_SET_FILTER Thrown when the product set filter provided is invalid
CAT_VALIDATION_ERROR_MAX_PRODUCT_SET_COUNT_FOR_CATALOG_REACHED Thrown when the maximum product set count for catalog has been reached
CAT_VALIDATION_ERROR_MAX_PRODUCT_SET_FILTER_ENTRY_COUNT_REACHED Thrown if the max product set filter entry count is reached
CAT_VALIDATION_ERROR_TOO_MANY_PRODUCT_SETS_IN_BATCH Thrown when there are too many product sets in a batch
CAT_VALIDATION_ERROR_PRODUCT_SET_NAME_LENGTH_INVALID Thrown if the product set name length is not valid
CAT_VALIDATION_ERROR_INVALID_PRODUCT_SET_ID Thrown if the product set id provided is invalid
CAT_VALIDATION_ERROR_INVALID_PAGINATION_READ_LIMIT Thrown if the read limit specified by user is invalid
CAT_VALIDATION_ERROR_READ_LIMIT_MUST_BE_SPECIFIED Thrown if only pagination cursor is provided but not an explicit read limit
CAT_VALIDATION_ERROR_INVALID_CURSOR Thrown if the pagination cursor provided by the user is invalid

Update a Product Set

curl -X PUT -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
-d '{"product_sets": [{ "id": "8d2d659e-0e3c-4938-a417-09d1a8fa4348","name": "In Stock & Red","filter": {"AND": [{"AVAILABILITY": {"EQ": "IN_STOCK"}},{"COLOR": {"IS_ANY": ["red"]}}]}}]}' \
https://adsapi.snapchat.com/v1/product_sets

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "caf894e2-3bd1-420a-ae3a-5b1a19289488",
    "product_sets": [
        {
            "sub_request_status": "SUCCESS",
            "product_set": {
                "id": "8d2d659e-0e3c-4938-a417-09d1a8fa4348",
                "catalog_id": "306544db-be30-472c-ab87-c277b4d61d0f",
                "name": "In Stock & Red",
                "filter": {
                    "AND": [
                        {
                            "AVAILABILITY": {
                                "EQ": "IN_STOCK"    
                            }
                        },
                        {
                            "COLOR": {
                                "IS_ANY": ["red"]
                            }
                        }
                    ]
                },
                "created_at": "2019-06-14T18:38:49.640871Z",
                "updated_at": "2019-06-14T20:38:49.640871Z"
            }
        }
    ]
}

This endpoint will update a specified Product Set.

HTTP Request

PUT https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/product_sets

Parameters

Parameter Default Description
catalog_id Catalog ID

Delete a Product Set

curl -X DELETE -H https://adsapi.snapchat.com/v1/product_sets/8d2d659e-0e3c-4938-a417-09d1a8fa4348 \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "caf894e2-3bd1-420a-ae3a-5b1a19289488",
    "product_sets": []
}

This endpoint will delete a specified Product Set.

HTTP Request

PUT https://adsapi.snapchat.com/v1/product_sets/{product_set_id}

Parameters

Parameter Default Description
catalog_id Catalog ID

Get All Product Sets

curl
"https://adsapi.snapchat.com/v1/catalogs/306544db-be30-472c-ab87-c277b4d61d0f/product_sets?cursor=abc123&limit=50" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:


{
    "request_status": "SUCCESS",
    "request_id": "caf894e2-3bd1-420a-ae3a-5b1a19289488",
    "product_sets": [
        {
            "sub_request_status": "SUCCESS",
            "product_set": {
                "id": "8d2d659e-0e3c-4938-a417-09d1a8fa4348",
                "catalog_id": "306544db-be30-472c-ab87-c277b4d61d0f",
                "name": "In Stock",
                "filter": {
                    "AVAILABILITY": {
                        "EQ": "IN_STOCK"    
                    }
                },
                "created_at": "2019-06-14T18:38:49.640871Z",
                "updated_at": "2019-06-14T18:38:49.640871Z"
            }
        }

    ],
    "paging": {
        "next_link": "https://adsapi.snapchat.com/v1/catalogs/306544db-be30-472c-ab87-c277b4d61d0f/product_sets?cursor=def456&limit=50"
    }
}

This endpoint will get all the Product Sets within the Catalog.

HTTP Request

GET https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/product_sets?cursor=abc123&limit=50

Parameters

Parameter Default Description
catalog_id Catalog ID

Get a Product Set by ID

curl
"https://adsapi.snapchat.com/v1/product_sets/8d2d659e-0e3c-4938-a417-09d1a8fa4348" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:


{
    "request_status": "SUCCESS",
    "request_id": "caf894e2-3bd1-420a-ae3a-5b1a19289488",
    "product_sets": [
        {
            "sub_request_status": "SUCCESS",
            "product_set": {
                "id": "8d2d659e-0e3c-4938-a417-09d1a8fa4348",
                "catalog_id": "306544db-be30-472c-ab87-c277b4d61d0f",
                "name": "In Stock",
                "filter": {
                    "AVAILABILITY": {
                        "EQ": "IN_STOCK"    
                    }
                },
                "created_at": "2019-06-14T18:38:49.640871Z",
                "updated_at": "2019-06-14T18:38:49.640871Z"
            }
        }
    ]
}

This endpoint will get a specified Product Set.

HTTP Request

GET: https://adsapi.snapchat.com/v1/product_sets/{product_set_id}

Parameters

Parameter Default Description
product_set_id Product Set ID

Create the Campaign

For DPA, the following fields have been updated or added to the Campaign object:

Attribute Description Required Possible Values
product_properties Product Properties to be associated with the Campaign Yes See table below

product_properties

Attribute Description Required Possible Values
catalog_id The Product Catalog ID to be associated with the Campaign Yes “product_properties”: {“catalog_id”: “1bcfb8cd-2e57”}
curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
   -d '"campaigns": [{"name": "First DPA campaign", "ad_account_id": "497979f0-ed17-4971-8288-054883f1cbca","daily_budget_micro": "100000000000","status": "PAUSED","start_time": "2019-12-01T17:12:49.707Z","end_time": "2019-12-12T17:12:49.707Z","product_properties" : {"catalog_id": "079d2a83-e422-4c0e-918b-8db17f087205"}}]}' \
"https://adsapi.snapchat.com/v1/adaccounts/{ad_acount_id}/campaigns"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5d8bd65100ff0d03b71380cd950001737e616473617069736300016275696c642d34353936393233352d312d3239312d3100010119",
    "campaigns": [
        {
            "sub_request_status": "SUCCESS",
            "campaign": {
                "id": "41b98396-4aaa-4a8e-acd4-50d25ac87488",
                "updated_at": "2019-09-25T21:04:18.433Z",
                "created_at": "2019-09-25T21:04:18.433Z",
                "name": "First DPA campaign",
                "ad_account_id": "497979f0-ed17-4971-8288-054883f1cbca",
                "daily_budget_micro": 100000000000,
                "status": "PAUSED",
                "objective": "BRAND_AWARENESS",
                "start_time": "2019-12-01T17:12:49.707Z",
                "end_time": "2019-12-12T17:12:49.707Z",
                "product_properties": {
                    "catalog_id": "079d2a83-e422-4c0e-918b-8db17f087205"
                }
            }
        }
    ]
}

Pixel

The Pixel associated with the Ad Account will be the one assumed as the event source for targeting.

Create the Ad Squad

DPA Ad Squads have specific requirements for the targeting and optimization_goal attributes, DPA Ad Squads also require the product_properties attribute.

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 For prospecting; IMPRESSIONS, SWIPES, APP_INSTALLS, VIDEO_VIEWS, VIDEO_VIEWS_15_SEC, PIXEL_PAGE_VIEW, PIXEL_ADD_TO_CART, PIXEL_PURCHASE, PIXEL_SIGNUP, APP_ADD_TO_CART, APP_PURCHASE, APP_SIGNUP , For re-targeting; PIXEL_PURCHASE, PIXEL_PAGE_VIEW, PIXEL_ADD_TO_CART, APP_PURCHASE, APP_SIGN_UP, APP_ADD_TO_CART, SWIPES
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
story_ad_creative_type Indicates the type of Creative used in Dynamic Story Ads, required when using Dynamic Story Ads O APP_INSTALL, WEB_VIEW, DEEP_LINK
targeting Targeting spec R Must contain product_audiences array for retargeting. For prospecting, omit the product_audiences array, also see App Install states targeting
type Ad Squad Type R SNAP_ADS
cap_and_exclusion_config The frequency cap and exclusion spec O
ad_scheduling_config The schedule for running ads O
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 Required for retargeting, Optional for prospecting
measurement_provider_names approved measurement provider O MOAT_SS, DOUBLEVERIFY
delivery_constraint Type of delivery R DAILY_BUDGET (when using daily_budget_micro), LIFETIME_BUDGET (when using lifetime_budget_micro)
pacing_type Type of pacing O STANDARD (default), ACCELERATED
event_sources Snap App Id to be associated with the Ad Squad O Availble for Dynamic Product Ads when using APP_INSTALL / DEEP_LINK, see App Install states

For DPA, the following attribute has been added to the Ad Squad object. Only retargeting and prospecting are supported now, cross-sell and upsell use cases will be supported soon.

Attribute Description Required Possible Values
product_properties Product Properties to be associated with the Ad Squad R See table below

product_properties

Attribute Description Required Possible Values
product_set_id The Product Set ID to be associated with the Ad Squad R “product_properties”: {“catalog_id”: “1bcfb8cd-2e57”}
catalog_vertical Catalog vertical, automatically set by the Catalog Read-only COMMERCE, HOTELS, PLACES, FLIGHTS

product_audiences

Attribute Description Required Possible Values
event_type The Pixel or App event type to be targeted R Only PAGE_VIEW, VIEW_CONTENT, ADD_CART, PURCHASE are supported
product_set The Product Set ID used to track pixel events against R For retargeting, product_set must match product_set_id on the Ad Squad
retention_seconds Retention in seconds R Min 86400 (1 day), Max 2592000 (30 days)
operation Operation to be applied R INCLUDE or EXCLUDE

Prospecting Ad Squad

Prospecting does not require that the Snap Pixel is activated at Ad Account level and associated with the Ad Squad, having a pixel however will allow you to track PIXEL_PURCHASE events which along with the purchase value and transaction id will allow you to calculate a Return on Ad Spend.

Prospecting Example

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{"adsquads": [{"name": "DPA Prospecting Ad Squad example","optimization_goal": "IMPRESSIONS","status": "ACTIVE","campaign_id": "4114749d-7362-42e8-b05d-48ef7984a91d","type": "SNAP_ADS","targeting": {"regulated_content": false,"geos": [{"country_code": "us"}],"product_audiences": [{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "PAGE_VIEW","retention_seconds": 1209600,"operation": "EXCLUDE"},{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "ADD_CART","retention_seconds": 1209600,"operation": "EXCLUDE"},{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "PURCHASE","retention_seconds": 1209600,"operation": "EXCLUDE"},{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "VIEW_CONTENT","retention_seconds": 1209600,"operation": "EXCLUDE"}],"auto_expansion_options":{"interest_expansion_option":{"enabled": true},"custom_audience_expansion_option":{"enabled": true}}},"placement_v2": {"config": "AUTOMATIC"},"billing_event": "IMPRESSION","bid_strategy": "AUTO_BID","daily_budget_micro": 50000000,"start_time": "2020-06-16T23:25:34.370Z","end_time": "2020-06-21T06:59:59.000Z","pixel_id": "9315b2c2-3680-411d-b6c1-d17de25fc1e0","delivery_constraint": "DAILY_BUDGET","pacing_type": "STANDARD","product_properties": {"product_set_id": "da17a495-0392-448f-b4f4-f027ecdcb794"}}]}' \
https://adsapi.snapchat.com/v1/campaigns/4114749d-7362-42e8-b05d-48ef7984a91d/adsquads

The above example request for Prospecting returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5eea238500ff08f85033418b420001737e616473617069736300016275696c642d37316537353330622d312d3335392d3300010129",
    "adsquads": [
        {
            "sub_request_status": "SUCCESS",
            "adsquad": {
                "id": "5d9556b8-eb0c-4209-b23a-385a79918e6b",
                "updated_at": "2020-06-17T14:07:02.933Z",
                "created_at": "2020-06-17T14:07:02.933Z",
                "name": "DPA Prospecting Ad Squad example",
                "status": "ACTIVE",
                "campaign_id": "4114749d-7362-42e8-b05d-48ef7984a91d",
                "type": "SNAP_ADS",
                "targeting": {
                    "regulated_content": false,
                    "geos": [
                        {
                            "country_code": "us"
                        }
                    ],
                    "product_audiences": [
                        {
                            "product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
                            "event_type": "PAGE_VIEW",
                            "retention_seconds": 1209600,
                            "operation": "EXCLUDE"
                        },
                        {
                            "product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
                            "event_type": "ADD_CART",
                            "retention_seconds": 1209600,
                            "operation": "EXCLUDE"
                        },
                        {
                            "product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
                            "event_type": "PURCHASE",
                            "retention_seconds": 1209600,
                            "operation": "EXCLUDE"
                        },
                        {
                            "product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
                            "event_type": "VIEW_CONTENT",
                            "retention_seconds": 2592000,
                            "operation": "EXCLUDE"
                        }
                    ],
                    "auto_expansion_options":
                        {
                            "interest_expansion_option":
                            {
                                "enabled": true
                            },
                        "custom_audience_expansion_option":
                            {
                                "enabled": true
                            }
                        }
                },
                "targeting_reach_status": "VALID",
                "placement_v2": {
                    "config": "AUTOMATIC"
                },
                "billing_event": "IMPRESSION",
                "auto_bid": true,
                "target_bid": false,
                "bid_strategy": "AUTO_BID",
                "daily_budget_micro": 50000000,
                "start_time": "2020-06-16T23:25:34.370Z",
                "end_time": "2020-06-21T06:59:59.000Z",
                "optimization_goal": "IMPRESSIONS",
                "pixel_id": "9315b2c2-3680-411d-b6c1-d17de25fc1e0",
                "delivery_constraint": "DAILY_BUDGET",
                "pacing_type": "STANDARD",
                "product_properties": {
                    "product_set_id": "da17a495-0392-448f-b4f4-f027ecdcb794",
                    "catalog_vertical": "COMMERCE"
                }
            }
        }
    ]
}

In the following example of product_audiences we target all users who haven’t triggered the specific events PAGE_VIEW, ADD_CART, PURCHASE, VIEW_CONTENT on your website/app for the past 14 days = 1209600 seconds.

"product_audiences": [
{
"product_set": "{{product_set_id}}",
"event_type": "PAGE_VIEW",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
},
{
"product_set": "{{product_set_id}}",
"event_type": "ADD_CART",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
},
{
"product_set": "{{product_set_id}}",
"event_type": "PURCHASE",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
},
{
"product_set": "{{product_set_id}}",
"event_type": "VIEW_CONTENT",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
}
]

Retargeting Ad Squad

Retargeting requires that you have a Pixel activated and associated with the Ad Squad.

Retargeting Example 1

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{"adsquads": [{"name": "DPA Retargeting Ad Squad - Viewers and Add Cart","optimization_goal": "SWIPES","status": "ACTIVE","campaign_id": "4114749d-7362-42e8-b05d-48ef7984a91d","type": "SNAP_ADS","targeting": {"regulated_content": false,"geos": [{"country_code": "us"}],"product_audiences": [{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "PAGE_VIEW","retention_seconds": 1209600,"operation": "INCLUDE"},{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "ADD_CART","retention_seconds": 1209600,"operation": "INCLUDE"},{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "PURCHASE","retention_seconds": 1209600,"operation": "EXCLUDE"},{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "VIEW_CONTENT","retention_seconds": 1209600,"operation": "INCLUDE"}],"auto_expansion_options":{"interest_expansion_option":{"enabled": true},"custom_audience_expansion_option":{"enabled": true}}},"placement_v2": {"config": "AUTOMATIC"},"billing_event": "IMPRESSION","bid_strategy": "TARGET_COST","bid_micro": 1000000,"daily_budget_micro": 50000000,"start_time": "2020-06-16T23:25:34.370Z","end_time": "2020-06-21T06:59:59.000Z","pixel_id": "9315b2c2-3680-411d-b6c1-d17de25fc1e0","delivery_constraint": "DAILY_BUDGET","pacing_type": "STANDARD","product_properties": {"product_set_id": "da17a495-0392-448f-b4f4-f027ecdcb794"}}]}' \
https://adsapi.snapchat.com/v1/campaigns/4114749d-7362-42e8-b05d-48ef7984a91d/adsquads

The above request for Retargeting Example 1 returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5eea3a9800ff07b42dbea034bf0001737e616473617069736300016275696c642d37316537353330622d312d3335392d3300010122",
    "adsquads": [
        {
            "sub_request_status": "SUCCESS",
            "adsquad": {
                "id": "a7171164-12b0-4576-a441-52eb57679ede",
                "updated_at": "2020-06-17T03:44:19.788Z",
                "created_at": "2020-06-17T00:44:19.486Z",
                "name": "DPA Retargeting Ad Squad - Viewers and Add Cart",
                "status": "ACTIVE",
                "campaign_id": "4114749d-7362-42e8-b05d-48ef7984a91d",
                "type": "SNAP_ADS",
                "targeting": {
                    "regulated_content": false,
                    "geos": [
                        {
                            "country_code": "us"
                        }
                    ],
                    "product_audiences": [
                        {
                            "product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
                            "event_type": "PAGE_VIEW",
                            "retention_seconds": 1209600,
                            "operation": "INCLUDE"
                        },
                        {
                            "product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
                            "event_type": "ADD_CART",
                            "retention_seconds": 1209600,
                            "operation": "INCLUDE"
                        },
                        {
                            "product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
                            "event_type": "PURCHASE",
                            "retention_seconds": 1209600,
                            "operation": "EXCLUDE"
                        },
                        {
                            "product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
                            "event_type": "VIEW_CONTENT",
                            "retention_seconds": 1209600,
                            "operation": "INCLUDE"
                        }
                    ],
                    "auto_expansion_options":
                    {
                        "interest_expansion_option":
                        {
                            "enabled": true
                        },
                        "custom_audience_expansion_option":
                        {
                            "enabled": true
                        }
                    }
                },
                "targeting_reach_status": "VALID",
                "placement_v2": {
                    "config": "AUTOMATIC"
                },
                "billing_event": "IMPRESSION",
                "bid_micro": 1000000,
                "bid_strategy": "TARGET_COST",
                "daily_budget_micro": 50000000,
                "start_time": "2020-06-16T23:25:34.370Z",
                "end_time": "2020-06-21T06:59:59.000Z",
                "optimization_goal": "SWIPES",
                "pixel_id": "9315b2c2-3680-411d-b6c1-d17de25fc1e0",
                "delivery_constraint": "DAILY_BUDGET",
                "pacing_type": "STANDARD",
                "product_properties": {
                    "product_set_id": "da17a495-0392-448f-b4f4-f027ecdcb794",
                    "catalog_vertical": "COMMERCE"
                }
            }
        }
    ]
}

In the following example of product_audiences we target all users who have triggered the specific events PAGE_VIEW, ADD_CART, VIEW_CONTENT, but not triggered a PURCHASE event on your website/app in the past 14 days = 1209600 seconds.

"product_audiences": [
{
"product_set": "{{product_set_id}}",
"event_type": "PAGE_VIEW",
"retention_seconds": 1209600,
"operation": "INCLUDE"
},
{ "product_set": "{{product_set_id}}",
"event_type": "VIEW_CONTENT",
"retention_seconds": 1209600,
"operation": "INCLUDE"
},
{
"product_set": "{{product_set_id}}",
"event_type": "ADD_CART",
"retention_seconds": 1209600,
"operation": "INCLUDE"
},
{
"product_set": "{{product_set_id}}",
"event_type": "PURCHASE",
"retention_seconds": 1209600,
"operation": "EXCLUDE"
}
]

Retargeting Example 2

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{"adsquads": [{"name": "DPA Retargeting Ad Squad - Add Cart","optimization_goal": "PIXEL_PURCHASE","status": "ACTIVE","campaign_id": "4114749d-7362-42e8-b05d-48ef7984a91d","type": "SNAP_ADS","targeting": {"regulated_content": false,"geos": [{"country_code": "us"}],"product_audiences": [{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "ADD_CART","retention_seconds": 2592000,"operation": "INCLUDE"},{"product_set": "da17a495-0392-448f-b4f4-f027ecdcb794","event_type": "PURCHASE","retention_seconds": 2592000,"operation": "EXCLUDE"}],"auto_expansion_options":{"interest_expansion_option":{"enabled": true},"custom_audience_expansion_option":{"enabled": true}}},"placement_v2": {"config": "AUTOMATIC"},"billing_event": "IMPRESSION","bid_strategy": "TARGET_COST","bid_micro": 1000000,"daily_budget_micro": 50000000,"start_time": "2020-06-16T23:25:34.370Z","end_time": "2020-06-21T06:59:59.000Z","pixel_id": "9315b2c2-3680-411d-b6c1-d17de25fc1e0","delivery_constraint": "DAILY_BUDGET","pacing_type": "STANDARD","product_properties": {"product_set_id": "da17a495-0392-448f-b4f4-f027ecdcb794"}}]}' \
https://adsapi.snapchat.com/v1/campaigns/4114749d-7362-42e8-b05d-48ef7984a91d/adsquads

The above request for Retargeting Example 2 returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5eea3a9800ff07b42dbea034bf0001737e616473617069736300016275696c642d37316537353330622d312d3335392d3300010122",
    "adsquads": [
        {
            "sub_request_status": "SUCCESS",
            "adsquad": {
                "id": "a7171164-12b0-4576-a441-52eb57679ede",
                "updated_at": "2020-06-15T03:44:19.788Z",
                "created_at": "2020-06-15T00:44:19.486Z",
                "name": "DPA Retargeting Ad Squad - Add Cart",
                "status": "ACTIVE",
                "campaign_id": "4114749d-7362-42e8-b05d-48ef7984a91d",
                "type": "SNAP_ADS",
                "targeting": {
                    "regulated_content": false,
                    "geos": [
                        {
                            "country_code": "us"
                        }
                    ],
                    "product_audiences": [
                         {
                            "product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
                            "event_type": "ADD_CART",
                            "retention_seconds": 2592000,
                            "operation": "INCLUDE"
                        },
                        {
                            "product_set": "da17a495-0392-448f-b4f4-f027ecdcb794",
                            "event_type": "PURCHASE",
                            "retention_seconds": 2592000,
                            "operation": "EXCLUDE"
                        }
                    ],
                    "auto_expansion_options":
                    {
                        "interest_expansion_option":
                        {
                            "enabled": true
                        },
                        "custom_audience_expansion_option":
                        {
                            "enabled": true
                        }
                    }
                },
                "targeting_reach_status": "VALID",
                "placement_v2": {
                    "config": "AUTOMATIC"
                },
                "billing_event": "IMPRESSION",
                "bid_micro": 1000000,
                "bid_strategy": "TARGET_COST",
                "daily_budget_micro": 50000000,
                "start_time": "2020-06-18T23:25:34.370Z",
                "end_time": "2020-06-21T06:59:59.000Z",
                "optimization_goal": "PIXEL_PURCHASE",
                "pixel_id": "9315b2c2-3680-411d-b6c1-d17de25fc1e0",
                "delivery_constraint": "DAILY_BUDGET",
                "pacing_type": "STANDARD",
                "product_properties": {
                    "product_set_id": "da17a495-0392-448f-b4f4-f027ecdcb794"
                }
            }
        }
    ]
}

In the following example of product_audiences we target all users who have triggered ADD_CART, but not triggered a PURCHASE event on your website/app, in the past 30 days = 2592000 seconds.

"product_audiences": [
{
"product_set": "{{product_set_id}}",
"event_type": "ADD_CART",
"retention_seconds": 2592000,
"operation": "INCLUDE"
},
{
"product_set": "{{product_set_id}}",
"event_type": "PURCHASE",
"retention_seconds": 2592000,
"operation": "EXCLUDE"
}
]

Create a Creative

For DPA, the following fields have been updated or added to the Creative object. Only Creatives of type WEB_VIEW, APP_INSTALL and DEEP_LINK are supported now.

Attribute Description Required Possible Values
render_type Render Type Yes DYNAMIC (required for DPA)
type Type of the Creative Yes Must be set to WEB_VIEW, APP_INSTALL or DEEP_LINK for render_type=DYNAMIC. If type is APP_INSTALL or DEEP_LINK, Campaign must contain “measurement_spec” for proper tracking.
dynamic_render_properties Properties to be set when render_type is DYNAMIC Yes See table below
url_macro_parameters Property that provides url macro parameters appended to all product urls O Supported macros:
  • {{campaign.name}}
  • {{campaign.id}}
  • {{adSet.name}}
  • {{adSet.id}}
  • {{ad.id}}

Format eg: utm_campaign={{campaign.id}}&utm_term={{ad.name}}

dynamic_render_properties

Attribute Description Required Possible Values
dynamic_template_id ID of the Dynamic template to be used R Dynamic Template ID
product_set_id ID of the Product Set from which products will be selected to be shown in the ads Yes Valid Product Set ID. Product Set must exist. Product Set must have products. Must match Ad Squad’s product_set_id.
curl -X POST \
  -d '{"creatives": [{"name": "DPA Ad", "ad_account_id": "497979f0-ed17-4971-8288-054883f1cbca", "type": "WEB_VIEW", "headline": "Shopping Forever", "brand_name": "DPA Brand", "call_to_action": "SHOP_NOW", "render_type": "DYNAMIC", "url_macro_parameters": "utm_campaign={{adset.name}}&utm_content={{ad.id}}", "dynamic_render_properties": {"dynamic_template_id": "75aa5c00-cabf-4b37-991a-7462ecf9a1cc", "product_set_id": "62984de1-0c0c-46e6-a21b-14e9cf5e2523"}}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adaccounts/497979f0-ed17-4971-8288-054883f1cbca/creatives

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5d8c2f9c00ff051b94bb93a0a70001737e616473617069736300016275696c642d35653536303765312d312d3239312d3500010124",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "bb0c57ca-8bf2-4f15-8162-704e9c33d88e",
                "updated_at": "2019-09-26T03:25:16.459Z",
                "created_at": "2019-09-26T03:25:16.459Z",
                "name": "DPA Ad",
                "ad_account_id": "497979f0-ed17-4971-8288-054883f1cbca",
                "type": "WEB_VIEW",
                "packaging_status": "SUCCESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "Shopping Forever",
                "brand_name": "DPA Brand",
                "call_to_action": "SHOP_NOW",
                "render_type": "DYNAMIC",
                "dynamic_render_properties": {
                    "dynamic_template_id": "75aa5c00-cabf-4b37-991a-7462ecf9a1cc",
                    "product_set_id": "62984de1-0c0c-46e6-a21b-14e9cf5e2523"
                },
                "top_snap_crop_position": "MIDDLE",
                "ad_product": "SNAP_AD"
            }
        }
    ]
}

Create the Ad

For DPA, the following fields have been updated or added to the Ad object.

Attribute Description Required Possible Values
creative_id ID of the Creative to be used Yes product_set_id of the Creative used must match the product_set_id on the Ad Squad associated with this Ad.
ad_squad_id ID of the Ad Squad Yes Ad Squad must have a product_set_id associated with it. And product_set_id of the Creative used must match the product_set_id on the Ad Squad associated with this Ad.
type Type of the Ad Yes Must be set to REMOTE_WEBPAGE, APP_INSTALL or DEEP_LINK. If type is APP_INSTALL or DEEP_LINK, Campaign must contain “measurement_spec” for proper tracking.
render_type The render type for the Dynamic Product Ad Required DYNAMIC
curl -X POST \
  -d '{"ads": [{"name": "DPA Ad", "ad_squad_id": "57d7ad65-1a40-40da-9443-6eafb15b0273", "creative_id": "bb0c57ca-8bf2-4f15-8162-704e9c33d88e", "status": "PAUSED", "type": "REMOTE_WEBPAGE", "render_type": "DYNAMIC"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
https://adsapi.snapchat.com/v1/adsquads/57d7ad65-1a40-40da-9443-6eafb15b0273/ads

The above command returns JSON structured like this:


{
    "request_status": "SUCCESS",
    "request_id": "5d8c331f00ff0a2bc7749e4dbc0001737e616473617069736300016275696c642d35653536303765312d312d3239312d3500010145",
    "ads": [
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "1c0deb89-bf95-458f-9c57-32c736046135",
                "updated_at": "2019-09-26T03:40:16.264Z",
                "created_at": "2019-09-26T03:40:16.264Z",
                "name": "DPA Ad",
                "ad_squad_id": "57d7ad65-1a40-40da-9443-6eafb15b0273",
                "creative_id": "bb0c57ca-8bf2-4f15-8162-704e9c33d88e",
                "status": "PAUSED",
                "type": "REMOTE_WEBPAGE",
                "render_type": "DYNAMIC",
                "review_status": "APPROVED"
            }
        }
    ]
}

Dynamic Templates

Dynamic Templates allows you to construct your own product template for use with your Dynamic Ads. The Dynamic Template entity is made up of a combination of Overlays and Text Overlays which define what the template will look like when it renders.

Dynamic Template Attributes

Name Description Required Possible Values
ad_account_id Ad Account ID R
name Template Name R Max length 375 characters
ios_url The URL which will render the Ad R https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html
android_url The URL which will render the Ad R https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html
layout Layout of the template R AUTOMATIC, FILL_WIDTH, FILL_HEIGHT, FIT, HEADER, TILT, CAROUSEL*, SLIDESHOW*
text_fields Text field out of Catalog attributes R Array with a maximum of two Text fields from the Catalog attributes
background_color Background color of template O Represented as three- or six-digit hexadecimal number
preferred_image_tags Array of Image tags out of your Product Feed O A list of Image tags from your product feed, see section on preferred_image_tags
overlay_specs Array of Overlay elements O See Overlay table

* The CAROUSEL and SLIDESHOW layout requires that the Creative is a Collection Ad.

Overlay Attributes

Name Description Required Possible Values
type The type of overlay R IMAGE, FRAME, TEXT
media_id Media ID of an IMAGE/FRAME type overlay O, R when type is IMAGE/FRAME Media ID
text The text of a TEXT type overlay O Max length 34 characters
position Position of the overlay R BOTTOM_MIDDLE, BOTTOM_LEFT, BOTTOM_RIGHT, CENTER, TOP_MIDDLE, TOP_LEFT, TOP_RIGHT, must be CENTER if type is FRAME
opacity Opacity of the overlay O Integer, between 75-100
text_overlay_properties Text Overlay O See Text Overlay table

Text Overlay Attributes

Name Description Required Possible Values
shape Background shape of text overlay, NONE means no shape underneath text R NONE, CIRCLE, PILL, RECTANGLE
shape_color Color of background of text overlay O Represented as three- or six-digit hexadecimal number
text_color Color of the text in the text overlay R Represented as three- or six-digit hexadecimal number

Preferred Image Tags

If your product feed includes additional image you have the option of using preferred_image_tags for your Dynamic Template.

When your Dynamic Template includes the preferred_image_tags attribute the Template will first attempt to fetch the image url as specified by your product feed and none of the other features within the Dynamic Template will be used. If no corresponding image url can be found in your product feed the Overlay will be used.

Preferred Image Tags Example

Product Feed Column Value Description
image[0].url https://www.renderingurl.com?tag=x url to be rendered when tag[0] is specified
image[0].tag[0] x tag value mapping to image[0]
image[1].url https://www.renderingurl.com?tag=y url to be rendered when tag[1] is specified
image[1].tag[0] y tag value mapping to image[1]

Given the above Product Feed specification the Dynamic Template can make use of the following preferred_image_tags attribute:

"preferred_image_tags": [ "x", "y" ]

The behaviour of the Dynamic Template in this scenario would be to first check if there is a corresponding value for the tag x, in this case the url https://www.renderingurl.com?tag=x is available, this would be requested and it would return a rendered image to be used in place of the Overlay.

Assuming there had been no corresponding image url for the listed tags the Dynamic Template would instead have used the Overlay.

Media Requirements

The Media used for IMAGE/FRAME overlays within a Dynamic Template have the following requirements.

File Requirements

Name Description File Type File Dimension File size
Overlay Frame Used as frame JPG or PNG 1080px * 1920px maximum 2mb
Overlay Image Used as logo JPG or PNG 200px * 200px maximum 2mb

Media Requirements

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
name Media name R
type Media Type R IMAGE
visibility R INVISIBLE

Create Dynamic Template

curl -X POST \
  -d '{"dynamic_templates": [{"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2","name": "Test Template III","ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html","android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html","layout": "FILL_WIDTH","text_fields": ["title","price"],"background_color": "FFFF00","overlay_specs": [{"type": "IMAGE","media_id": "e292db69-139f-41fb-b79b-4cb7ab2e9840","position": "BOTTOM_LEFT"},{"type": "FRAME","media_id": "e8aa0151-9a6f-48a0-bcaa-82fc4f714161","position": "CENTER","opacity": "80"},{"type": "TEXT","text": "meow meow","position": "BOTTOM_RIGHT","opacity": "80","text_overlay_properties": {"shape": "CIRCLE","shape_color": "09C","text_color": "4287F5"}},{"type": "TEXT","text": "woof woof","position": "TOP_RIGHT","opacity": "80","text_overlay_properties": {"shape": "PILL","shape_color": "09C","text_color": "000"}}]}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/dynamic_templates

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ee4011200ff030f7b28c958f70001737e616473617069736300016275696c642d32313965343130312d312d3335382d310001010a",
    "dynamic_templates": [
        {
            "sub_request_status": "SUCCESS",
            "dynamic_template": {
                "id": "a523ad2d-226a-40c1-8645-4420cac49b76",
                "updated_at": "2020-06-12T22:26:26.638Z",
                "created_at": "2020-06-12T22:26:26.638Z",
                "name": "Test Template III",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
                "ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
                "android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
                "layout": "FILL_WIDTH",
                "text_fields": [
                    "title",
                    "price"
                ],
                "background_color": "FFFF00",
                "overlay_specs": [
                    {
                        "type": "IMAGE",
                        "media_id": "e292db69-139f-41fb-b79b-4cb7ab2e9840",
                        "position": "BOTTOM_LEFT"
                    },
                    {
                        "type": "FRAME",
                        "media_id": "e8aa0151-9a6f-48a0-bcaa-82fc4f714161",
                        "position": "CENTER",
                        "opacity": 80
                    },
                    {
                        "type": "TEXT",
                        "text": "meow meow",
                        "position": "BOTTOM_RIGHT",
                        "opacity": 80,
                        "text_overlay_properties": {
                            "shape": "CIRCLE",
                            "shape_color": "09C",
                            "text_color": "4287F5"
                        }
                    },
                    {
                        "type": "TEXT",
                        "text": "woof woof",
                        "position": "TOP_RIGHT",
                        "opacity": 80,
                        "text_overlay_properties": {
                            "shape": "PILL",
                            "shape_color": "09C",
                            "text_color": "000"
                        }
                    }
                ]
            }
        }
    ]
}

This request creates a Dynamic Template.

HTTP Request

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

URL Parameters

Parameter Description
ad_account_id The ID of the Ad Account where the Dynamic Template will be created

Update Dynamic Template

curl -X PUT \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"dynamic_templates": [{"id": "c2987693-f5c3-43b1-90bd-31445493cef1","name": "Grey Seal Template","ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2","ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html","android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html","layout": "FILL_WIDTH","text_fields": ["title","price"],"background_color": "FFFFFF","preferred_image_tags": ["tag1","tag2"],"overlay_specs": [{"type": "IMAGE","media_id": "e292db69-139f-41fb-b79b-4cb7ab2e9840","position": "TOP_LEFT"},{"type": "FRAME","media_id": "e8aa0151-9a6f-48a0-bcaa-82fc4f714161","position": "CENTER","opacity": 75},{"type": "TEXT","text": "Diving Equipment","position": "BOTTOM_RIGHT","opacity": 80,"text_overlay_properties": {"shape": "CIRCLE","shape_color": "09C","text_color": "4287F5"}},{"type": "TEXT","text": "Sliding Attire","position": "BOTTOM_LEFT","opacity": 80,"text_overlay_properties": {"shape": "PILL","shape_color": "09C","text_color": "6342F5"}}]}]}'
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/dynamic_templates

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ee7660600ff0b01c7922c0efc0001737e616473617069736300016275696c642d32313965343130312d312d3335382d310001011e",
    "dynamic_templates": [
        {
            "sub_request_status": "SUCCESS",
            "dynamic_template": {
                "id": "c2987693-f5c3-43b1-90bd-31445493cef1",
                "updated_at": "2020-06-15T12:13:59.179Z",
                "created_at": "2020-06-10T15:19:27.803Z",
                "name": "Grea Seal Template",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
                "ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
                "android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
                "layout": "FIT",
                "text_fields": [
                    "title",
                    "price"
                ],
                "background_color": "FFFFFF",
                "preferred_image_tags": [
                    "tag1",
                    "tag2"
                ],
                "overlay_specs": [
                    {
                        "type": "IMAGE",
                        "media_id": "e292db69-139f-41fb-b79b-4cb7ab2e9840",
                        "position": "TOP_LEFT"
                    },
                    {
                        "type": "FRAME",
                        "media_id": "e8aa0151-9a6f-48a0-bcaa-82fc4f714161",
                        "position": "CENTER",
                        "opacity": 75
                    },
                    {
                        "type": "TEXT",
                        "text": "Diving Equipment",
                        "position": "BOTTOM_RIGHT",
                        "opacity": 80,
                        "text_overlay_properties": {
                            "shape": "CIRCLE",
                            "shape_color": "09C",
                            "text_color": "4287F5"
                        }
                    },
                    {
                        "type": "TEXT",
                        "text": "Sliding Attire",
                        "position": "BOTTOM_LEFT",
                        "opacity": 80,
                        "text_overlay_properties": {
                            "shape": "PILL",
                            "shape_color": "09C",
                            "text_color": "6342F5"
                        }
                    }
                ]
            }
        }
    ]
}

This request updates a Dynamic Template.

HTTP Request

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

URL Parameters

Parameter Description
ad_account_id The ID of the Ad Account

Get Dynamic Template by ID

curl "https://adsapi.snapchat.com/v1/dynamic_templates/baf5c1d9-7a86-4453-aba1-b27a9ce8348b" \
  -H "Authorization: Bearer meowmeowmeow"

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ee3ec5000ff0553580d379f2c0001737e616473617069736300016275696c642d32313965343130312d312d3335382d3100010133",
    "dynamic_templates": [
        {
            "sub_request_status": "SUCCESS",
            "dynamic_template": {
                "id": "baf5c1d9-7a86-4453-aba1-b27a9ce8348b",
                "updated_at": "2020-06-11T18:07:20.968Z",
                "created_at": "2020-06-11T18:07:20.968Z",
                "name": "Test Template II",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
                "ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
                "android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
                "layout": "FILL_WIDTH",
                "text_fields": [
                    "title",
                    "price"
                ],
                "background_color": "FFFFFF",
                "preferred_image_tags": [
                    "tag1",
                    "tag2"
                ],
                "overlay_specs": [
                    {
                        "type": "IMAGE",
                        "media_id": "e292db69-139f-41fb-b79b-4cb7ab2e9840",
                        "position": "TOP_LEFT"
                    },
                    {
                        "type": "FRAME",
                        "media_id": "e8aa0151-9a6f-48a0-bcaa-82fc4f714161",
                        "position": "CENTER",
                        "opacity": 75
                    },
                    {
                        "type": "TEXT",
                        "text": "meow meow",
                        "position": "BOTTOM_RIGHT",
                        "opacity": 80,
                        "text_overlay_properties": {
                            "shape": "CIRCLE",
                            "shape_color": "09C",
                            "text_color": "4287F5"
                        }
                    },
                    {
                        "type": "TEXT",
                        "text": "woof woof",
                        "position": "BOTTOM_LEFT",
                        "opacity": 80,
                        "text_overlay_properties": {
                            "shape": "PILL",
                            "shape_color": "09C",
                            "text_color": "6342F5"
                        }
                    }
                ]
            }
        }
    ]
}

This request gets a Template by it’s template id.

HTTP Request

GET https://adsapi.snapchat.com/v1/dynamic_templates/{dynamic_template_id}

URL Parameters

Parameter Description
dynamic_template_id The ID of the Dynamic Template to retrieve

Get Dynamic Templates by Ad Account ID

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

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ee4060700ff0d381e5ae4f67a0001737e616473617069736300016275696c642d32313965343130312d312d3335382d3100010107",
    "paging": {},
    "dynamic_templates": [
        {
            "sub_request_status": "SUCCESS",
            "dynamic_template": {
                "id": "a523ad2d-226a-40c1-8645-4420cac49b76",
                "updated_at": "2020-06-12T22:26:26.638Z",
                "created_at": "2020-06-12T22:26:26.638Z",
                "name": "Fox Template",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
                "ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
                "android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
                "layout": "FILL_WIDTH",
                "text_fields": [
                    "title",
                    "price"
                ],
                "background_color": "FFFF00",
                "overlay_specs": [
                    {
                        "type": "IMAGE",
                        "media_id": "e292db69-139f-41fb-b79b-4cb7ab2e9840",
                        "position": "BOTTOM_LEFT"
                    },
                    {
                        "type": "FRAME",
                        "media_id": "e8aa0151-9a6f-48a0-bcaa-82fc4f714161",
                        "position": "CENTER",
                        "opacity": 80
                    },
                    {
                        "type": "TEXT",
                        "text": "meow meow",
                        "position": "BOTTOM_RIGHT",
                        "opacity": 80,
                        "text_overlay_properties": {
                            "shape": "CIRCLE",
                            "shape_color": "09C",
                            "text_color": "4287F5"
                        }
                    },
                    {
                        "type": "TEXT",
                        "text": "woof woof",
                        "position": "TOP_RIGHT",
                        "opacity": 80,
                        "text_overlay_properties": {
                            "shape": "PILL",
                            "shape_color": "09C",
                            "text_color": "000"
                        }
                    }
                ]
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "dynamic_template": {
                "id": "baf5c1d9-7a86-4453-aba1-b27a9ce8348b",
                "updated_at": "2020-06-11T18:07:20.968Z",
                "created_at": "2020-06-11T18:07:20.968Z",
                "name": "Honey Bear Template",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
                "ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
                "android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
                "layout": "FILL_WIDTH",
                "text_fields": [
                    "title",
                    "price"
                ],
                "background_color": "FFFFFF",
                "preferred_image_tags": [
                    "tag1",
                    "tag2"
                ],
                "overlay_specs": [
                    {
                        "type": "IMAGE",
                        "media_id": "e292db69-139f-41fb-b79b-4cb7ab2e9840",
                        "position": "TOP_LEFT"
                    },
                    {
                        "type": "FRAME",
                        "media_id": "e8aa0151-9a6f-48a0-bcaa-82fc4f714161",
                        "position": "CENTER",
                        "opacity": 75
                    },
                    {
                        "type": "TEXT",
                        "text": "meow meow",
                        "position": "BOTTOM_RIGHT",
                        "opacity": 80,
                        "text_overlay_properties": {
                            "shape": "CIRCLE",
                            "shape_color": "09C",
                            "text_color": "4287F5"
                        }
                    },
                    {
                        "type": "TEXT",
                        "text": "woof woof",
                        "position": "BOTTOM_LEFT",
                        "opacity": 80,
                        "text_overlay_properties": {
                            "shape": "PILL",
                            "shape_color": "09C",
                            "text_color": "6342F5"
                        }
                    }
                ]
            }
        }
    ]
}

This request gets all Dynamic Templates under an Ad Account.

HTTP Request

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

URL Parameters

Parameter Description
ad_account_id The ID of the Ad Account

Reporting

All standard reporting metrics and granularities are supported for DPA. Please refer to the DPA reporting section for more details

Dynamic Collections Ads Guide

Collection ads can be used to market products dynamically, these Ads can either be made fully Dynamic or partly Dynamic.

Both variants of the Dynamic Collection Ad need an Interaction zone with 2-4 Creative Elements, the Creative Elements will dynamically select Products out of an associated Product Set.

Assuming you have an existing Product feed and Product set, the order of creation from the bottom of the hierarchy is:

  1. Creative Elements
  2. Interaction Zone
  3. Creative
  4. Ad Squad
  5. Ad entity

Product feed - Interaction support

Before setting up the Creative Elements you should ensure the chosen interaction is supported by the product feed and product set you intend to use. The Product Search method along with the parameter ELIGIBLE_AD_TYPE can be used to evaluate this. Refer to Product Search

The three Ad formats supported by product search and ELIGIBLE_AD_TYPE are APP_INSTALL, DEEP_LINK_ATTACHMENT and REMOTE_WEBPAGE.

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"filter":{"AND":[{"ELIGIBLE_AD_TYPE":{"EQ":"DEEP_LINK_ATTACHMENT"}},{"PRODUCT_SET_ID":{"EQ":"8dc5f3ff-ab02-460b-bbbd-1ade8bb3da38"}},{"OR":[{"AVAILABILITY":{"EQ":"IN_STOCK"}},{"AVAILABILITY":{"EQ":"PREORDER"}},{"AVAILABILITY":{"EQ":"AVAILABLE_FOR_ORDER"}}]}]}}' 
https://adsapi.snapchat.com/v1/catalogs/82225ba6-7559-4000-9663-bace8adff5f8/product_search?limit=0
{
  "request_status": "SUCCESS",
  "request_id": "5ff70e2b00ff08056236e672d10001737e616473617069736300016275696c642d33343532666138312d312d3431312d300001013d",
  "summary": {
    "total_products": {
      "count": "47",
      "relation": "EQ"
    }
  },
  "paging": {},
  "products": [
    { ...}
  ]
}

HTTP Request

POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/product_search?limit=0

Creative Elements

The Creative element is a holder for the Product Feed images which will be picked dynamically from the Product set defined in dynamic_render_properties.product_set_id at the Creative level.

The Creative Element also specifies the interaction triggered when the user taps the Element (webview/app install/deep link) via the attribute interaction_type.

Once the Creative Element entity has been created it cannot be updated.

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"creative_elements":[{"name":"Product tile 1","type":"BUTTON","interaction_type":"WEB_VIEW","render_type":"DYNAMIC"},{"name":"Product tile 2","type":"BUTTON","interaction_type":"WEB_VIEW","render_type":"DYNAMIC"},{"name":"Product tile 3","type":"BUTTON","interaction_type":"WEB_VIEW","render_type":"DYNAMIC"}]}' 
  https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f8/creative_elements
{
    "request_status": "SUCCESS",
    "request_id": "5fda1dd300ff0d787cd06ea62b0001737e616473617069736300016275696c642d66306132623635382d312d3430392d3200010160",
    "creative_elements": [
        {
            "sub_request_status": "SUCCESS",
            "creative_element": {
                "id": "5bc30331-9428-46a6-8d4c-5093124c6d03",
                "updated_at": "2020-12-16T14:46:44.152Z",
                "created_at": "2020-12-16T14:46:44.152Z",
                "name": "Product tile 1",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f8",
                "type": "BUTTON",
                "interaction_type": "WEB_VIEW",
                "render_type": "DYNAMIC"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "creative_element": {
                "id": "83d7b96d-bdb1-4e46-83b2-1a6d61a36b56",
                "updated_at": "2020-12-16T14:46:44.454Z",
                "created_at": "2020-12-16T14:46:44.454Z",
                "name": "Product tile 2",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f8",
                "type": "BUTTON",
                "interaction_type": "WEB_VIEW",
                "render_type": "DYNAMIC"
            }
        },
        {
            "sub_request_status": "SUCCESS",
            "creative_element": {
                "id": "578e3f05-a87d-4af5-a389-55c086277dad",
                "updated_at": "2020-12-16T14:46:44.727Z",
                "created_at": "2020-12-16T14:46:44.727Z",
                "name": "Product tile 3",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f8",
                "type": "BUTTON",
                "interaction_type": "WEB_VIEW",
                "render_type": "DYNAMIC"
            }
        }
    ]
}

HTTP Request

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

Creative Elements Parameters

Attribute Description Required Possible Values
name Creative Element name R
type R BUTTON
title Creative Element title O
description Creative Element description O
interaction_type Defines the behaviour of the Creative Elements R WEB_VIEW, APP_INSTALL, DEEP_LINK
render_type R DYNAMIC

Interaction Zones

The Interaction zone is mainly a holder where the Dynamic Creative Elements will be shown, it also holds the call to action for the Snap Ad under the attribute headline. The 2-4 Creative Elements that are added to the Interaction Zone should have the same interaction_type.

Once created the Interaction Zone entity cannot be updated.

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"interaction_zones":[{"name":"The Badger Shop Interaction Zone","render_type":"DYNAMIC","creative_element_ids":["5bc30331-9428-46a6-8d4c-5093124c6d03","83d7b96d-bdb1-4e46-83b2-1a6d61a36b56","578e3f05-a87d-4af5-a389-55c086277dad"],"headline":"MORE"}]}' 
  https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f8/interaction_zones
{
    "request_status": "SUCCESS",
    "request_id": "5fda1f3300ff0c89632e43f2c20001737e616473617069736300016275696c642d66306132623635382d312d3430392d3200010128",
    "interaction_zones": [
        {
            "sub_request_status": "SUCCESS",
            "interaction_zone": {
                "id": "51d12f07-8690-4a41-b201-6a99335bbaa2",
                "updated_at": "2020-12-16T14:52:36.057Z",
                "created_at": "2020-12-16T14:52:36.057Z",
                "name": "The Badger Shop Interaction Zone",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f8",
                "headline": "MORE",
                "creative_element_ids": [
                    "5bc30331-9428-46a6-8d4c-5093124c6d03",
                    "83d7b96d-bdb1-4e46-83b2-1a6d61a36b56",
                    "578e3f05-a87d-4af5-a389-55c086277dad"
                ],
                "render_type": "DYNAMIC"
            }
        }
    ]
}

HTTP Request

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

Interaction Zones Parameters

Attribute Description Required Possible Values
name Interaction Zone name R
render_type R DYNAMIC
creative_elements An array of 2-4 Creative Element ids, these elements should be of the same interaction_type R
headline This is used as the CTA for the Collection Ad R APPLY_NOW, BOOK_NOW, BUY_TICKETS, DONATE, DOWNLOAD, GET_NOW, INSTALL_NOW, LISTEN, MORE, OPEN_APP, ORDER_NOW, PLAY, READ, RESPOND, SHOP_NOW, SHOW, SHOWTIMES, SIGN_UP, TRY, USE_APP, VIEW, WATCH

Fully Dynamic Collection Ad Creative

The Top Snap media will be a product picked dynamically based on the Product Catalog (product_set) like in an ordinary Dynamic Product Ad.

The 2-4 Creative Elements displayed at the bottom of the Top Snap are inserted via the Interaction Zone and picked dynamically based on the Product Catalog (product_set).

The collection_properties.default_fallback_interaction_type should match the interaction_type of the Creative Elements used in the Interaction Zone.

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"creatives":[{"ad_account_id":"82225ba6-7559-4000-9663-bace8adff5f8","name":"Dynamic Collection Ad with Dynamic Top Snap","type":"COLLECTION","headline":"Badger Supplies","brand_name":"Badger Tunneling","shareable":true,"render_type":"DYNAMIC","dynamic_render_properties":{"dynamic_template_id":"013cb00d-7b8a-467a-a6be-614c269dafe2","product_set_id":"b6d35541-d5b6-4e06-a400-03f9937392cc"},"collection_properties":{"interaction_zone_id":"51d12f07-8690-4a41-b201-6a99335bbaa2","default_fallback_interaction_type":"WEB_VIEW"}}]}' 
  https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f8/creatives
{
    "request_status": "SUCCESS",
    "request_id": "5fda234d00ff02f5557aba61770001737e616473617069736300016275696c642d66306132623635382d312d3430392d3200010123",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "de8a165e-f031-4a94-a56b-d0b5b4e1c20f",
                "updated_at": "2020-12-16T15:10:05.566Z",
                "created_at": "2020-12-16T15:10:05.566Z",
                "name": "Dynamic Collection Ad with Dynamic Top Snap",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f8",
                "type": "COLLECTION",
                "packaging_status": "SUCCESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "Badger Supplies",
                "brand_name": "Badger Tunneling",
                "render_type": "DYNAMIC",
                "dynamic_render_properties": {
                    "dynamic_template_id": "013cb00d-7b8a-467a-a6be-614c269dafe2",
                    "product_set_id": "b6d35541-d5b6-4e06-a400-03f9937392cc"
                },
                "top_snap_crop_position": "MIDDLE",
                "ad_product": "SNAP_AD",
                "collection_properties": {
                    "interaction_zone_id": "51d12f07-8690-4a41-b201-6a99335bbaa2",
                    "default_fallback_interaction_type": "WEB_VIEW"
                }
            }
        }
    ]
}

HTTP Request

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

Creative - Collection Creative with Dynamic Top Snap - Parameters

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
name Creative name R
type Creative type R COLLECTION
headline 34 characters max R
brand_name 25 characters max R
shareable Allow Users to Share with Friends O true (default), false
render_type DYNAMIC R
dynamic_render_properties.dynamic_template_id Dynamic Template ID R
dynamic_render_properties.product_set_id Product Set ID used for Products R
collection_properties.interaction_zone_id Interaction Zone ID R
collection_properties.default_fallback_interaction_type Defines Interaction behaviour for the Creative R WEB_VIEW, APP_INSTALL, DEEP_LINK

Partly Dynamic Collection Ad

The Top Snap media is uploaded as a separate Media (image/video) and has its own set of attributes at the Creative level (WEB_VIEW, APP_INSTALL, DEEP_LINK), this attribute should match the interaction_type of the Creative Elements.

The 3-4 Creative Elements displayed at the bottom of the Top Snap are inserted via the Interaction Zone and picked dynamically based on the Product Catalog (product_set).

The collection_properties.default_fallback_interaction_type should match the interaction_type of the Creative Elements used in the Interaction Zone.

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"creatives":[{"ad_account_id":"82225ba6-7559-4000-9663-bace8adff5f8","name":"Dynamic Collection Ad with Static Top Snap","type":"COLLECTION","headline":"Badger Supplies","brand_name":"Badger Tunneling","shareable":true,"render_type":"STATIC","top_snap_media_id":"e02308fd-ab84-4b6e-8c71-4fe1fc2f1ae2","dynamic_render_properties":{"product_set_id":"b6d35541-d5b6-4e06-a400-03f9937392cc"},"collection_properties":{"interaction_zone_id":"51d12f07-8690-4a41-b201-6a99335bbaa2","default_fallback_interaction_type":"WEB_VIEW","web_view_properties":{"url":"https://www.example.com/bookingfolder/linkedpage.html","allow_snap_javascript_sdk":false,"use_immersive_mode":false,"deep_link_urls":[],"block_preload":false}}}]}' 
  https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f8/creatives
{
    "request_status": "SUCCESS",
    "request_id": "5fda252200ff00ff08972bb0da7a0001737e616473617069736300016275696c642d66306132623635382d312d3430392d3200010119",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "8eec06bd-d3fd-4841-b330-d04b82dfd862",
                "updated_at": "2020-12-16T15:17:54.396Z",
                "created_at": "2020-12-16T15:17:54.396Z",
                "name": "Dynamic Collection Ad with Static Top Snap",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f8",
                "type": "COLLECTION",
                "packaging_status": "SUCCESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "Badger Supplies",
                "brand_name": "Badger Tunneling",
                "render_type": "STATIC",
                "top_snap_media_id": "e02308fd-ab84-4b6e-8c71-4fe1fc2f1ae2",
                "dynamic_render_properties": {
                    "product_set_id": "b6d35541-d5b6-4e06-a400-03f9937392cc"
                },
                "top_snap_crop_position": "MIDDLE",
                "ad_product": "SNAP_AD",
                "collection_properties": {
                    "interaction_zone_id": "51d12f07-8690-4a41-b201-6a99335bbaa2",
                    "default_fallback_interaction_type": "WEB_VIEW",
                    "web_view_properties": {
                        "url": "https://www.example.com/bookingfolder/linkedpage.html",
                        "allow_snap_javascript_sdk": false,
                        "use_immersive_mode": false,
                        "deep_link_urls": [],
                        "block_preload": false
                    }
                }
            }
        }
    ]
}

HTTP Request

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

Creative - Collection Creative with uploaded Top Snap - Parameters

Attribute Description Required Possible Values
ad_account_id Ad Account ID R
name Creative name R
type Creative type R COLLECTION
headline 34 characters max R
brand_name 25 characters max R
shareable Allow Users to Share with Friends O true (default), false
render_type R STATIC
top_snap_media_id Media ID of Top Snap, the Media type can be either VIDEO or IMAGE R
dynamic_render_properties.product_set_id Product Set id R
collection_properties.interaction_zone_id Interaction Zone id R
collection_properties.default_fallback_interaction_type Defines Interaction behaviour for the Creative R WEB_VIEW, APP_INSTALL, DEEP_LINK

For a partly dynamic Collection Ad you need to specify the properties for the top snap, these properties are defined within the JSON of the collection_properties and

Webview attributes

Attribute Description Required Possible Values
collection_properties.web_view_properties.url Web view URL R
collection_properties.web_view_properties.allow_snap_javascript_sdk O true, false (default)
collection_properties.web_view_properties.use_immersive_mode O true, false (default)
collection_properties.web_view_properties.block_preload Block Snapchat from preloading the web page O true, false (default)

App Install attributes

Attribute Description Required
collection_properties.app_install_properties.app_name App name R
collection_properties.app_install_properties.ios_app_id iOS App ID R
collection_properties.app_install_properties.android_app_url Google Play Store ID R
collection_properties.app_install_properties.icon_media_id Icon Media ID R
collection_properties.app_install_properties.product_page_id iOS App Store Custom Product Page ID O
Attribute Description Required Possible Values
collection_properties.deep_link_properties.deep_link_uri Deep link URL for App R
collection_properties.deep_link_properties.app_name App name R
collection_properties.deep_link_properties.ios_app_id iOS App ID R
collection_properties.deep_link_properties.android_app_url Google Play Store ID R
collection_properties.deep_link_properties.icon_media_id Icon Media ID R
collection_properties.deep_link_properties.fallback_type Behaviour for user that doesn’t have app installed R APP_INSTALL, WEB_SITE
collection_properties.deep_link_properties.web_view_fallback_url Required if fallback_type is WEB_SITE R
collection_properties.deep_link_properties.deep_link_uri Deep link URL for App R
collection_properties.deep_link_properties.product_page_id iOS App Store Custom Product Page ID O

Ad Squad

The Ad Squad follows the exact requirements of an Ad Squad used for Dynamic Product Ads, there are no additional parameters for using Dynamic Collection Ads. Refer Create Ad Squad

The Ad entity links the Creative and the Ad Squad together, the type and render_type needs to use the below specified values, the only attribute that differs from Dynamic Product Ads is the type attribute which needs to be set to the value COLLECTION.

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"ads":[{"id":"6fca9a40-08e9-44e4-8ac2-de40d604af1f","name":"Dynamic Collection Ad with Dynamic Top Snap","ad_squad_id":"ea47539a-dd29-4957-b24c-2624957fa7e7","creative_id":"de8a165e-f031-4a94-a56b-d0b5b4e1c20f","status":"ACTIVE","type":"COLLECTION","render_type":"DYNAMIC"}]}' 
  https://adsapi.snapchat.com/v1/adsquads/ea47539a-dd29-4957-b24c-2624957fa7e7/ads
{
    "request_status": "SUCCESS",
    "request_id": "5fda26e300ff0eeb712b8d14d80001737e616473617069736300016275696c642d66306132623635382d312d3430392d3200010160",
    "ads": [
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "e88eb5f7-d4da-4c8e-b1c8-d98f81ae3801",
                "updated_at": "2020-12-16T15:25:25.109Z",
                "created_at": "2020-12-16T15:25:25.109Z",
                "name": "Dynamic Collection Ad with Dynamic Top Snap",
                "ad_squad_id": "ea47539a-dd29-4957-b24c-2624957fa7e7",
                "creative_id": "de8a165e-f031-4a94-a56b-d0b5b4e1c20f",
                "status": "ACTIVE",
                "type": "COLLECTION",
                "render_type": "DYNAMIC",
                "review_status": "PENDING",
                "review_status_reasons": [],
                "delivery_status": [
                    "INVALID_EFFECTIVE_INVALID",
                    "INVALID_PENDING_REVIEW_STATUS"
                ]
            }
        }
    ]
}

Attribute Description Required Possible Values
name Ad name R
ad_squad_id Ad squad ID R
creative_id Creative ID R
status Ad status R ACTIVE, PAUSED
type Ad type R COLLECTION
render_type Rendering type R DYNAMIC

Please refer to the FAQ section for FAQs on Dynamic Collection Ads

The Dynamic Collection Ad supports two different Creative experiences via Dynamic Templates, these experiences are activated by specifying CAROUSEL or SLIDESHOW as the layout type.

layout Description
CAROUSEL Product images are displayed as thumbnails and rotated in a main image slot
SLIDESHOW Product images are rotated in a main image slot
curl -X POST \
  -d '{"dynamic_templates": [{"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2","name": "Dynamic Collection Carousel Template","ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html","android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html","layout": "CAROUSEL","text_fields": ["title","price"]}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/dynamic_templates

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ee4011200ff030f7b28c958f70001737e616473617069736300016275696c642d32313965343130312d312d3335382d310001010a",
    "dynamic_templates": [
        {
            "sub_request_status": "SUCCESS",
            "dynamic_template": {
                "id": "a523ad2d-226a-40c1-8645-4420cac49b76",
                "updated_at": "2020-06-12T22:26:26.638Z",
                "created_at": "2020-06-12T22:26:26.638Z",
                "name": "Dynamic Collection Carousel Template",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
                "ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
                "android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
                "layout": "CAROUSEL",
                "text_fields": [
                    "title",
                    "price"
                ]
            }
        }
    ]
}

This request creates a Dynamic Template for a Dynamic Collection Ad using the CAROUSEL layout.

HTTP Request

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

URL Parameters

Parameter Description
ad_account_id The ID of the Ad Account where the Dynamic Template will be created

Example 2 - Create a SLIDESHOW Dynamic Template

curl -X POST \
  -d '{"dynamic_templates": [{"ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2","name": "Dynamic Collection Carousel Template","ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html","android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html","layout": "SLIDESHOW","text_fields": ["title","price"]}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adaccounts/22225ba6-7559-4000-9663-bace8adff5f2/dynamic_templates

The above command returns JSON structured like this:

{
    "request_status": "SUCCESS",
    "request_id": "5ee4011200ff030f7b28c958f70001737e616473617069736300016275696c642d32313965343130312d312d3335382d310001010a",
    "dynamic_templates": [
        {
            "sub_request_status": "SUCCESS",
            "dynamic_template": {
                "id": "a523ad2d-226a-40c1-8645-4420cac49b76",
                "updated_at": "2020-06-12T22:26:26.638Z",
                "created_at": "2020-06-12T22:26:26.638Z",
                "name": "Dynamic Collection Carousel Template",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
                "ios_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
                "android_url": "https://ads-interfaces.sc-cdn.net/adformats/templates/V2/index.html",
                "layout": "SLIDESHOW",
                "text_fields": [
                    "title",
                    "price"
                ]
            }
        }
    ]
}

This request creates a Dynamic Template for a Dynamic Collection Ad using the CAROUSEL layout.

HTTP Request

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

URL Parameters

Parameter Description
ad_account_id The ID of the Ad Account where the Dynamic Template will be created

Showcase Experience

The Showcase Experience for DPA collection Ads is a new format which delivers a native commerce experience on Snapchat. It allows users to swipe up to a collection of products, rendered natively, for a seamless, delightful shopping experience.

The setup for the Showcase Experience is identical to the DPA collection ads setup with creative elements, interaction zones, ad squads and ad objects. The primary difference is in the setup of the creative object.

Showcase Creative

The showcase creative is a creative of type COLLECTION and render_type DYNAMIC. It contains a new property within collection_properties called showcase_properties.

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{
        "creatives": [
        {
            "ad_account_id": "497979f0-ed17-4971-8288-0548abcdcbca",
            "name": "Dynamic Collection Ad with Dynamic Top Snap for showcase API",
            "type": "COLLECTION",
            "headline": "Badger Supplies",
            "brand_name": "Badger Tunneling",
            "shareable": true,
            "render_type": "DYNAMIC",
            "dynamic_render_properties":
            {
                "dynamic_template_id": "186491f9-abcd-4322-9bf5-42bc0b2a79b8",
                "product_set_id": "0ae60e22-5764-abcd-88ad-5f77f8f286dd"
            },
            "collection_properties":
            {
                "interaction_zone_id": "618ef9f7-abcd-abcd-abcd-9b2eda44eb04",
                "default_fallback_interaction_type": "SHOWCASE",
                "showcase_properties": {
                           "product_set_id": "0ae60e22-abcd-abcd-88ad-5f77f8f286dd",
                           "interaction_type": "WEB_VIEW",
                           "callout_text": "20% off",
                           "web_view_properties": {
                           "url": "http://www.bananas.com"
                           }
                       }
            }
        }]
    }'
    https://adsapi.snapchat.com/v1/adaccounts/497979f0-ed17-4971-8278-054883f1cbca/creatives
{
    "request_status": "SUCCESS",
    "request_id": "60bff16b00ff09d211e5b48ed40001737e616473617069736300016275696c642d63313332343265352d312d3435332d3000010155",
    "creatives": [
    {
        "sub_request_status": "SUCCESS",
        "creative":
        {
            "id": "5970d72e-abcd-abcd-90f8-496f6091bb3b",
            "updated_at": "2021-06-08T22:38:35.974Z",
            "created_at": "2021-06-08T22:38:35.974Z",
            "created_by_app_id": "faaabe40-abcd-abcd-abcd-b88f802dc3d2",
            "created_by_user": "9b50736f-abcd-abcd-abcd-21f99554aa31",
            "last_updated_by_app_id": "faaabe40-abcd-abcd-837d-b88f802dc3d2",
            "last_updated_by_user": "9b50736f-abcd-abcd-abcd-21f99554aa31",
            "name": "Dynamic Collection Ad with Dynamic Top Snap for showcase API",
            "ad_account_id": "497979f0-abcd-abcd-abcd-054883f1cbca",
            "type": "COLLECTION",
            "packaging_status": "SUCCESS",
            "review_status": "PENDING_REVIEW",
            "shareable": true,
            "headline": "Badger Supplies",
            "brand_name": "Badger Tunneling",
            "render_type": "DYNAMIC",
            "dynamic_render_properties":
            {
                "dynamic_template_id": "186491f9-abcd-abcd-abcd-42bc0b2a79b8",
                "product_set_id": "0ae60e22-abcd-abcd-abcd-5f77f8f286dd"
            },
            "top_snap_crop_position": "MIDDLE",
            "ad_product": "SNAP_AD",
            "collection_properties":
            {
                "interaction_zone_id": "618ef9f7-abcd-abcd-abcd-9b2eda44eb04",
                "default_fallback_interaction_type": "SHOWCASE",
                "showcase_properties":
                {
                    "product_set_id": "0ae60e22-abcd-abcd-abcd-5f77f8f286dd",
                    "interaction_type": "WEB_VIEW",
                    "callout_text": "20% off",
                    "web_view_properties":
                    {
                        "url": "http://www.baanas.com",
                        "allow_snap_javascript_sdk": false,
                        "use_immersive_mode": false,
                        "deep_link_urls": [],
                        "block_preload": false
                    }
                }
            }
        }
    }]
}

Property Name Required Description Possible Values
product_set_id R The product set ID to be associated to generate the Showcase unit Product set ID eg: 0ae60e22-5764-4d34-88ad-5f77f8f286ad
interaction_type R WEB_VIEW, DEEP_LINK
callout_text O Text shown in the banner at the top of the Showcase experience Max length: 30
web_view_properties Required when interaction_type is web_view Defines the url for “Shop Now” button Required when interaction_type == WEB_VIEW. Only url in web_view_properties can be used refer to web_view_properties table
deep_link_properties Required when interaction_type is deep_link Defines the url for “Shop Now” button Required when interaction_type == DEEP_LINK. Only deeplinkUri, iosAppId, AndroidAppUrl and webViewFallbackUrl in deep_link_properties can be used. FallbackType must be WEB_SITE refer to deep_link_properties table

Validations

Some important validations to take note of.

Dynamic Story Ads Guide

Story Ads are a Dynamic Ad format that allows advertisers to dynamically display a series of 3-10 product ads pulled directly from a Catalog.

This opens an opportunity to leverage Dynamic Ads campaigns within another placement across Snapchat, within our Discover tab where the Dynamic Story Ad will display.

Dynamic Story Ads are available for Website and Deep Link campaigns with both prospecting and retargeting audience targeting, and available for App Install campaigns with prospecting audience targeting.

Dynamic Story Ads currently has four possible variants.

Assuming you have an existing Product feed and Product set, the order of creation from the the top of the hierarchy is the following;

  1. Preview Creative
  2. Static Creative (Optional)
  3. 10x Dynamic Creatives
  4. Composite Creative
  5. Ad Squad (including product_audiences)
  6. Ad (Story type)

Product Feed - Interaction support

Before setting up the Creative Elements you should ensure the chosen interaction is supported by the product feed and product set you intend to use. The Product Search method along with the parameter ELIGIBLE_AD_TYPE can be used to evaluate this. Refer to Product Search

The three Ad formats supported by product search and ELIGIBLE_AD_TYPE are APP_INSTALL, DEEP_LINK_ATTACHMENT and REMOTE_WEBPAGE.

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"filter":{"AND":[{"ELIGIBLE_AD_TYPE":{"EQ":"DEEP_LINK_ATTACHMENT"}},{"PRODUCT_SET_ID":{"EQ":"8dc5f3ff-ab02-460b-bbbd-1ade8bb3da38"}},{"OR":[{"AVAILABILITY":{"EQ":"IN_STOCK"}},{"AVAILABILITY":{"EQ":"PREORDER"}},{"AVAILABILITY":{"EQ":"AVAILABLE_FOR_ORDER"}}]}]}}' 
https://adsapi.snapchat.com/v1/catalogs/82225ba6-7559-4000-9663-bace8adff5f8/product_search?limit=0
{
  "request_status": "SUCCESS",
  "request_id": "5ff70e2b00ff08056236e672d10001737e616473617069736300016275696c642d33343532666138312d312d3431312d300001013d",
  "summary": {
    "total_products": {
      "count": "47",
      "relation": "EQ"
    }
  },
  "paging": {},
  "products": [
    { ...}
  ]
}

HTTP Request

POST https://adsapi.snapchat.com/v1/catalogs/{catalog_id}/product_search?limit=0

Preview Creative

This Creative constitutes the tile that is used in the discover feed, it consists of the tile itself and a logo on top of the tile. The tile can either be a non-dynamic image, or the image can be fetched dynamically from a Product Set.

When the preview creative is non-dynamic it uses two Media entities of the type IMAGE

The Preview Media ID and Logo Media ID are defined in the preview_properties of this Creative, the preview_properties also contains a headline which can hold up to 55 characters and allows for the use of emoji Unicode characters.

When the preview creative is dynamic it needs to have the attribute dynamic_render_properties which specifies the product_set_id to be used, and the dynamic_template formulated on the Composite Creative.

Preview Media

This is a MEDIA creation request, the image dimension and size should be 360px x 600px PNG format, 2 MB maximum, detailed Media spec.

Attribute Description Required Possible Values
name Media name R
type Media Type R IMAGE
ad_account_id Ad Account ID R

Logo Media

This is a normal MEDIA creation request, the image dimension and size should be 993px x 284px PNG format on transparent background, 2 MB maximum, detailed Media spec.

Attribute Description Required Possible Values
name Media name R
type Media Type R IMAGE
ad_account_id Ad Account ID R

Example 1 - Preview Creative that uses a preview_media_id (IMAGE)

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"creatives":[{"name":"Preview Creative - STATIC - Badger Story Ad","ad_account_id":"82225ba6-7559-4000-9663-bace8adff5f2","type":"PREVIEW","shareable":true,"render_type":"STATIC","preview_properties":{"preview_media_id":"6774e417-c3b8-4bd5-9573-aee33658e7d8","logo_media_id":"16ddfd33-0e87-484b-9b6c-47d07724df78","preview_headline":"The latest Tunneling Gear 🛠"}}]}' 
  https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/creatives
{
    "request_status": "SUCCESS",
    "request_id": "60d34e6200ff0101c629819b530001737e616473617069736300016275696c642d63616365343036622d312d3435362d3200010149",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "5a63e6bd-6641-4d43-b4f8-484518f6d0e8",
                "updated_at": "2021-06-23T15:08:20.170Z",
                "created_at": "2021-06-23T15:08:20.170Z",
                "name": "Preview Creative - STATIC - Badger Story Ad",
                "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
                "type": "PREVIEW",
                "packaging_status": "SUCCESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "render_type": "STATIC",
                "top_snap_crop_position": "MIDDLE",
                "preview_properties": {
                    "preview_media_id": "6774e417-c3b8-4bd5-9573-aee33658e7d8",
                    "logo_media_id": "16ddfd33-0e87-484b-9b6c-47d07724df78",
                    "preview_headline": "The latest Tunneling Gear 🛠"
                },
                "ad_product": "SNAP_AD"
            }
        }
    ]
}

Example 2 - Preview Creative that uses a Dynamically picked image from a Product Set ID

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"creatives":[{"name":"Preview Creative - DYNAMIC - Badger Story Ad","ad_account_id":"22225ba6-7559-4000-9663-bace8adff5f2","type":"PREVIEW","shareable":true,"render_type":"DYNAMIC","top_snap_crop_position":"MIDDLE","dynamic_render_properties":{"dynamic_template_id":"c2987693-f5c3-43b1-90bd-31445493cef1","product_set_id":"b6d35541-d5b6-4e06-a400-03f9937392cc"},"preview_properties":{"logo_media_id":"16ddfd33-0e87-484b-9b6c-47d07724df70","preview_headline":"The latest Tunneling Gear 🛠"}}]}' 
  https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/creatives
{
    "request_status": "SUCCESS",
    "request_id": "611fe31700ff0e87127c39c75e0001737e616473617069736300016275696c642d39323666386331392d312d3437322d3000010108",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "3cb19304-4df3-446e-ac9d-b415b116e136",
                "updated_at": "2021-08-20T17:15:04.368Z",
                "created_at": "2021-08-20T17:15:04.368Z",
                "name": "Preview Creative - DYNAMIC - Badger Story Ad",
                "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2",
                "type": "PREVIEW",
                "packaging_status": "SUCCESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "render_type": "DYNAMIC",
                "dynamic_render_properties": {
                    "dynamic_template_id": "c2987693-f5c3-43b1-90bd-31445493cef1",
                    "product_set_id": "b6d35541-d5b6-4e06-a400-03f9937392cc"
                },
                "top_snap_crop_position": "MIDDLE",
                "preview_properties": {
                    "logo_media_id": "16ddfd33-0e87-484b-9b6c-47d07724df70",
                    "preview_headline": "The latest Tunneling Gear 🛠"
                },
                "ad_product": "SNAP_AD"
            }
        }
    ]
}

HTTP Request

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

Preview Creative Parameters

Attribute Description Required Possible Values
name Creative name R
ad_account_id Ad Account ID R
type Creative type R PREVIEW
shareable Allows sharing of the Story Ad on iOS, Android sharing is currently not available O true (default), false
render_type R STATIC, DYNAMIC
preview_properties.preview_media_id Preview Media ID, required when render_type is STATIC O
preview_properties.logo_media_id Logo Media ID R
preview_properties.preview_headline 55 Character limit, emoji unicode characters allowed R
dynamic_render_properties.dynamic_template_id Must match Dynamic Template ID set on the Composite creative, required when render_type is DYNAMIC O
dynamic_render_properties.product_set_id Must match Product Set ID set at Ad Squad level, required when render_type is DYNAMIC O

Dynamic Creatives

When creating a Dynamic Story Ad you will need 10 x Dynamic Creatives, these Dynamic Creatives need to be of the same Creative type (WEB_VIEW, APP_INSTALL, DEEP_LINK). It’s not possible to mix different Creative types within one Dynamic Story Ad.

The Dynamic Creatives follows the creation outlined here, the Dynamic Creatives will be listed in within an array of the Composite creative, even though a Dynamic Story Ad requires 10x Dynamic Creatives, at the point of serving 3-10 of these Creatives will be used to pull in Products from the Product feed.

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"creatives":[{"ad_account_id":"82225ba6-7559-4000-9663-bace8adff5f2","name":"DPA Story Ad Position 1","type":"WEB_VIEW","headline":"Tunneling Tools","brand_name":"Badger Tunneling","shareable":true,"call_to_action":"SHOP_NOW","render_type":"DYNAMIC","dynamic_render_properties":{"dynamic_template_id":"09d8d60b-1d05-423a-8d52-c2f52cf2c7dc","product_set_id":"10e7d339-0ff1-434a-996a-94d34918c948"}},{"name":"DPA Story Ad Position 2","ad_account_id":"82225ba6-7559-4000-9663-bace8adff5f2","type":"WEB_VIEW","shareable":true,"headline":"Tunneling Tools","brand_name":"Badger Tunneling","call_to_action":"SHOP_NOW","render_type":"DYNAMIC","dynamic_render_properties":{"dynamic_template_id":"09d8d60b-1d05-423a-8d52-c2f52cf2c7dc","product_set_id":"10e7d339-0ff1-434a-996a-94d34918c948"}}]}' 
  https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/creatives
{
   "request_status": "SUCCESS",
   "request_id": "60d4737600ff00ffde2766270dc80001737e616473617069736300016275696c642d63616365343036622d312d3435362d320001011d",
   "creatives": [
       {
           "sub_request_status": "SUCCESS",
           "creative": {
               "id": "885b4c1d-b496-40b9-9543-bd75bf1af010",
               "updated_at": "2021-06-24T11:58:46.929Z",
               "created_at": "2021-06-24T11:58:46.929Z",
               "name": "DPA Story Ad Position 1",
               "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
               "type": "WEB_VIEW",
               "packaging_status": "SUCCESS",
               "review_status": "PENDING_REVIEW",
               "shareable": true,
               "headline": "Tunneling Tools",
               "brand_name": "Badger Tunneling",
               "call_to_action": "SHOP_NOW",
               "render_type": "DYNAMIC",
               "dynamic_render_properties": {
                   "dynamic_template_id": "09d8d60b-1d05-423a-8d52-c2f52cf2c7dc",
                   "product_set_id": "10e7d339-0ff1-434a-996a-94d34918c948"
               },
               "top_snap_crop_position": "MIDDLE",
               "ad_product": "SNAP_AD"
           }
       },
       {
           "sub_request_status": "SUCCESS",
           "creative": {
               "id": "0ed1c7b0-4bfc-49cd-8037-0e20174ae51a",
               "updated_at": "2021-06-24T11:58:49.364Z",
               "created_at": "2021-06-24T11:58:49.364Z",
               "name": "DPA Story Ad Position 2",
               "ad_account_id": "82225ba6-7559-4000-9663-bace8adff5f2",
               "type": "WEB_VIEW",
               "packaging_status": "SUCCESS",
               "review_status": "PENDING_REVIEW",
               "shareable": true,
               "headline": "Tunneling Tools",
               "brand_name": "Badger Tunneling",
               "call_to_action": "SHOP_NOW",
               "render_type": "DYNAMIC",
               "dynamic_render_properties": {
                   "dynamic_template_id": "09d8d60b-1d05-423a-8d52-c2f52cf2c7dc",
                   "product_set_id": "10e7d339-0ff1-434a-996a-94d34918c948"
               },
               "top_snap_crop_position": "MIDDLE",
               "ad_product": "SNAP_AD"
           }
       }
   ]
}


HTTP Request

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

Dynamic Creative Parameters

Attribute Description Required Possible Values
name Creative Name R
ad_account_id Ad Account ID R
type Requires corresponding attribute in the product feed R WEB_VIEW, APP_INSTALL, DEEP_LINK
headline Max 34 characters with spaces R
brand_name Max 25 characters with spaces R
shareable O true (default), false
call_to_action As per the Creative type and Call to action mapping R
render_type R DYNAMIC
dynamic_render_properties.dynamic_template_id Must match Dynamic Template ID set on Composite creative R
dynamic_render_properties.product_set_id Must match Product Set ID set at Ad Squad level R

Non-Dynamic Creative Parameters

When creating a Story Ad you have the option of including one non-dynamic Creative in the story, this Creative can be of the types APP_INSTALL, WEB_VIEW or DEEP_LINK and should match the Dynamic Creatives type.

The creation of the non-dynamic Snap follows the regular creation of a Snap Ad with the corresponding attachment APP_INSTALL, WEB_VIEW and DEEP_LINK.

Composite Creative

The Composite creative contains information about the Tile (Preview Creative) and the Individual Snaps (Dynamic Creatives).

The headline and brand_name attributes on the Composite Creative are required but not used.

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"creatives":[{"name":"DPA Story Ad - Badger Tunneling Equipment","ad_account_id":"22225ba6-7559-4000-9663-bace8adff5f2","type":"COMPOSITE","headline":"Tunneling Tools","brand_name":"Badger Tunneling","render_type":"DYNAMIC","dynamic_render_properties":{"dynamic_template_id":"09d8d60b-1d05-423a-8d52-c2f52cf2c7dc","product_set_id":"10e7d339-0ff1-434a-996a-94d34918c948"},"composite_properties":{"creative_ids":["39283f04-3f1e-4c3a-89a7-2a8b7e15a58b","023ef23d-f3c9-4be1-a3fc-ec8dd76c6c88","b14f7e15-1c1f-4675-8c6d-0c8634bc9f58","d4b33aeb-1c8a-4a64-b46f-b3dd2c1dc208","aa982224-d78d-4400-8113-ff63cb309988","8fdb61d8-360e-4093-b6eb-a1d8f7bd45b8","abfdefb8-79a2-4b28-8de7-db4307c04948","a35c610b-75bf-40fc-87f3-08d82dec3108","5acecee9-ad03-4867-a319-e6dcb13b65d8","c75af576-1210-4a12-b9c1-7f2f6be71da8","1dae3e3e-75c7-4602-b9fa-05f98dbd7bf8"]},"preview_creative_id":"5a63e6bd-6641-4d43-b4f8-484518f6d0e8"}]}' 
  https://adsapi.snapchat.com/v1/adaccounts/82225ba6-7559-4000-9663-bace8adff5f2/creatives
{
    "request_status": "SUCCESS",
    "request_id": "60d46ed500ff067b3ef470a1250001737e616473617069736300016275696c642d63616365343036622d312d3435362d320001014b",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "4dba4e6e-fd3a-4fe7-aff9-0d18ba82927b",
                "updated_at": "2021-06-24T11:39:02.144Z",
                "created_at": "2021-06-24T11:39:02.144Z",
                "name": "DPA Story Ad - Badger Tunneling Equipment",
                "ad_account_id": "22225ba6-7559-4000-9663-bace8adff5f2",
                "type": "COMPOSITE",
                "packaging_status": "SUCCESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "Tunneling Tools",
                "brand_name": "Badger Tunneling",
                "render_type": "DYNAMIC",
                "dynamic_render_properties": {
                    "dynamic_template_id": "09d8d60b-1d05-423a-8d52-c2f52cf2c7dc",
                    "product_set_id": "10e7d339-0ff1-434a-996a-94d34918c948"
                },
                "top_snap_crop_position": "MIDDLE",
                "composite_properties": {
                    "creative_ids": [
                        "39283f04-3f1e-4c3a-89a7-2a8b7e15a58b",
                        "023ef23d-f3c9-4be1-a3fc-ec8dd76c6c88",
                        "b14f7e15-1c1f-4675-8c6d-0c8634bc9f58",
                        "d4b33aeb-1c8a-4a64-b46f-b3dd2c1dc208",
                        "aa982224-d78d-4400-8113-ff63cb309988",
                        "8fdb61d8-360e-4093-b6eb-a1d8f7bd45b8",
                        "abfdefb8-79a2-4b28-8de7-db4307c04948",
                        "a35c610b-75bf-40fc-87f3-08d82dec3108",
                        "5acecee9-ad03-4867-a319-e6dcb13b65d8",
                        "c75af576-1210-4a12-b9c1-7f2f6be71da8",
                        "1dae3e3e-75c7-4602-b9fa-05f98dbd7bf8"
                    ]
                },
                "ad_product": "SNAP_AD",
                "preview_creative_id": "5a63e6bd-6641-4d43-b4f8-484518f6d0e8"
            }
        }
    ]
}

HTTP Request

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

Composite Creative Parameters

Attribute Description Required Possible Values
name R
ad_account_id Ad Account ID R
type Creative type R COMPOSITE
headline Not used R
brand_name Not used R
render_type R DYNAMIC
preview_creative_id Preview Creative ID R
dynamic_render_properties.dynamic_template_id Dynamic Template ID R
dynamic_render_properties.product_set_id Product Set ID R
composite_properties.creative_ids Array of Creative IDs used in the Story, can be 1 x non-dynamic Creative + 10 x Dynamic Creativesor10 x Dynamic Creatives R

Individual Dynamic Snap Ad Creatives

The individual Dynamic Snap Ads that make up the story follow the exact same requirements as Dynamic Snap Ad Creatives.

Ad Squad

The Ad Squad follows the same requirements of an Ad Squad used for Dynamic Product Ads with the addition of the attribute story_ad_creative_type, this attribute is used to determine what type of Dynamic Creatives are used within the story.

Ad Squad Additional Parameter

Attribute Description Required Possible Values
story_ad_creative_type Indicates the type of Creatives used within the Story R APP_INSTALL, WEB_VIEW, DEEP_LINK

The Ad entity links the Creative and the Ad Squad together, the type and render_type needs to use the values specified in the table below, the only attribute that differs from Dynamic Product Ads is the type attribute which needs to be set to the value STORY.

curl -X POST \
  -H "Authorization: Bearer meowmeowmeow" \
  -H "Content-Type: application/json" \
  -d '{"ads":[{"name":"Dynamic Story Ad - Tunneling equipment","ad_squad_id":"54d79fbc-8ada-47cc-ae03-c044df05db3c","creative_id":"3f72ffee-5a3e-4d59-9893-2885dd983bea","status":"ACTIVE","type":"STORY","render_type":"DYNAMIC"}]}' 
  https://adsapi.snapchat.com/v1/adsquads/54d79fbc-8ada-47cc-ae03-c044df05db3c/ads
{
    "request_status": "SUCCESS",
    "request_id": "60d4765600ff0f3dbb82dac5e60001737e616473617069736300016275696c642d63616365343036622d312d3435362d3200010112",
    "ads": [
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "3aa9cf43-661e-45ad-a593-cc8e1daabe3a",
                "updated_at": "2021-06-24T12:11:04.612Z",
                "created_at": "2021-06-24T12:11:04.612Z",
                "name": "Dynamic Story Ad - Tunneling equipment",
                "ad_squad_id": "54d79fbc-8ada-47cc-ae03-c044df05db3c",
                "creative_id": "3f72ffee-5a3e-4d59-9893-2885dd983bea",
                "status": "ACTIVE",
                "type": "STORY",
                "render_type": "DYNAMIC",
                "review_status": "PENDING",
                "review_status_reasons": [],
                "delivery_status": [
                    "INVALID_PENDING_REVIEW_STATUS",
                    "INVALID_EFFECTIVE_INVALID"
                ]
            }
        }
    ]
}


HTTP Request

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

Attribute Description Required Possible Values
name Ad name R
ad_squad_id Ad squad ID R
creative_id Creative ID R
status Ad status R ACTIVE, PAUSED
type Ad type R STORY
render_type Rendering type R DYNAMIC

Lead Generation Ads Guide

Lead Generation Ads allow you to present the user with a form when they interact with the ad.

Lead Generation Ads Entities

The following entities are added to the creative entity when creating a Lead Generation creative.

Lead Generation Properties

JSON Example of the Lead Generation Ads entities

"lead_generation_properties": {
    "privacy_policy_url": "https://www.example.com/",
    "description": "This is my lead gen form",
    "form_fields": [
        {
            "type": "FIRST_NAME",
        },
        {
            "type": "LAST_NAME",
        },
        {
            "type": "EMAIL",
        },
        {
            "type": "CUSTOM",
            "custom_form_field_properties": {
                "type": "TEXT",
                "description": "What is your favorite color?"
            }
        }
    ],
    "legal_disclosures": {
        "title": "My terms",
        "description": "These are my terms",
        "consent_form_fields": [
            {
                "consent_description": "I agree to the terms",
                "required": true
            }
        ]
    },
    "banner_media_id": "a0bc123d-d4ab-4ecc-b4eb-1a23bc4567d2"
}

Attribute Description Required Possible Values
privacy_policy_url URL that points to your brand’s Privacy Policy. A link to this page will appear on the confirmation screen before the user submits their entries. Yes A URL string. For example: "https://www.example.com"
description A description of the lead generation form. This appears on the form before its question fields. Yes A text string. Max length is 180 characters.
form_fields A list of the questions in the form. Yes (See Form Requirements below.) A list of JSON objects that represent the questions in the form. Each element of the list must be a JSON object that contains a type attributed. For example:

{"type": "COMPANY_NAME"}

Possible values for type:
FIRST_NAME, LAST_NAME, EMAIL, PHONE_NUMBER, ADDRESS, POSTAL_CODE, BIRTHDAY_DATE, JOB_TITLE, COMPANY_NAME, CUSTOM.

If type is CUSTOM, the object must also include the custom_form_field_properties property.
legal_disclosures An object that describes that legal disclosures in the form. No A Legal Disclosure Properties object that contains information about the legal disclosures in the form.
banner_media_id Media ID of the form’s banner image. No A text string that contains a media ID.

Minimum Image Size: 750x230
Maximum Image Size: 1875x575
Aspect Ratio: 75:23
Max File Size: 5 MB
Attribute Description Required Possible Values
title Title of the legal disclosure. Yes, if legal_disclosures is non-null. A text string. For example: “Terms of Service”. Max length is 35 characters.
description A description of the terms that the user must agree to. Yes, if legal_disclosures is non-null. A text string. Max length is 80 characters.
consent_form_fields Description of the consent needed and if it is required. No A list of JSON objects that represent consents that must be given by the user when submitting the form. Each element of the list is a simple object that contains a text string consent_description and a boolean property required:

{"consent_description": "I agree to the terms", "required": true }

Can contain up to two elements.

Custom Form Field Properties

Attribute Description Required Possible Values
type Type of the form field. Yes TEXT, DATE, MULTIPLE_CHOICE_SINGLE_SELECTION, MULTIPLE_CHOICE_MULTI_SELECTION
description Description of the question being asked Yes A text string.
multiple_choice_descriptions Description of the consent needed and if it is required. Yes if type is MULTIPLE_CHOICE_SINGLE_SELECTION or MULTIPLE_CHOICE_MULTI_SELECTION A list of strings that represent choices that a user can answer this question with. The choices will appear in the same order as in the list. The list must contain between 2-4 elements. The max length of each string is 25 characters.

Form Requirements

How to create a Lead Generation Ad

Creating a Lead Generation Ad consists of the following steps:

  1. Create a header banner image for your form. (Only required if the form contains a banner header)
  2. Create a Lead Generation Form creative.
  3. Use the creative created in step 2 to create a Lead Generation ad.

Creating a header banner image for your form

Use the Create Media endpoint to create a media object for your banner’s header image. Refer to the Media entity documentation for more details.

Banner images must have a minimum size of 750x230, a maximum size of 1875x575, and a 75:23 aspect ratio. The max file size for a banner image is 5 MB.

Creating a Lead Generation creative

curl -X POST \
  -d '{"creatives":[{"ad_account_id":"8adc3db7-8148-4fbf-999c-8d2266369d74","name":"My Lead Gen Creative","type":"LEAD_GENERATION","headline":"This is my headline","brand_name":"Great brand","shareable":true,"call_to_action":"SIGN_UP","top_snap_media_id":"3m08b7ea-2dc6-4854-a44f-b3am70665b32","lead_generation_properties":{"privacy_policy_url":"https://www.example.com","description":"Please answer these questions!","form_fields":[{"type":"FIRST_NAME"},{"type":"LAST_NAME"},{"type":"PHONE_NUMBER"},{"type":"ADDRESS"},{"type":"BIRTHDAY_DATE"},{"type":"JOB_TITLE"},{"type":"COMPANY_NAME"},{"type":"CUSTOM","custom_form_field_properties":{"type":"TEXT","description":"What is your favorite word?"}},{"type":"CUSTOM","custom_form_field_properties":{"type":"MULTIPLE_CHOICE_MULTI_SELECTION","description":"What is your favorite color?","multiple_choice_descriptions":["Red","Blue","Green"]}}],"legal_disclosures":{"title":"legal title","description":"legal description","consent_form_fields":[{"consent_description":"Do you consent to the terms?","required":true}]},"banner_media_id":"d5cf309c-d4ab-4ecc-b4eb-3u63ba3314c2"}}]}' \
  -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": "92a44c1234ff0a974099d7d46d0001737e616473617069736300016275696c642d61353730363532632d312d3531322d3000012345",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "35fce3af-e1c7-46d4-a075-79180a3073ef",
                "updated_at": "2022-01-28T20:00:05.465Z",
                "created_at": "2022-01-28T20:00:05.465Z",
                "name": "My Lead Gen Creative",
                "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
                "type": "LEAD_GENERATION",
                "packaging_status": "IN_PROGRESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "This is my headline",
                "brand_name": "Great brand",
                "call_to_action": "SIGN_UP",
                "render_type": "STATIC",
                "top_snap_media_id": "1f08b7ea-2dc6-4854-a44f-z1xc23456b32",
                "top_snap_crop_position": "MIDDLE",
                "ad_product": "SNAP_AD",
                "lead_generation_properties": {
                    "privacy_policy_url": "https://www.example.com",
                    "description": "Please answer these questions!",
                    "form_fields": [
                        {
                            "type": "FIRST_NAME",
                            "is_required": true
                        },
                        {
                            "type": "LAST_NAME",
                            "is_required": true
                        },
                        {
                            "type": "PHONE_NUMBER",
                            "is_required": true
                        },
                        {
                            "type": "ADDRESS",
                            "is_required": true
                        },
                        {
                            "type": "BIRTHDAY_DATE",
                            "is_required": true
                        },
                        {
                            "type": "JOB_TITLE",
                            "is_required": true
                        },
                        {
                            "type": "COMPANY_NAME",
                            "is_required": true
                        },
                        {
                            "type": "CUSTOM",
                            "is_required": true,
                            "custom_form_field_properties": {
                                "type": "TEXT",
                                "description": "What is your favorite word?"
                            }
                        },
                        {
                            "type": "CUSTOM",
                            "is_required": true,
                            "custom_form_field_properties": {
                                "type": "MULTIPLE_CHOICE_MULTI_SELECTION",
                                "description": "What is your favorite color?",
                                "multiple_choice_descriptions": [
                                    "Red",
                                    "Blue",
                                    "Green"
                                ]
                            }
                        }
                    ],
                    "legal_disclosures": {
                        "title": "legal title",
                        "description": "legal description",
                        "consent_form_fields": [
                            {
                                "consent_description": "Do you consent to the terms?",
                                "required": true
                            }
                        ]
                    },
                    "banner_media_id": "d1cf309c-d4ab-4ecc-b4eb-1f23zx4564c1"
                }
            }
        }
    ]
}

The following properties must be added to the creative entity to create a Lead Generation creative.

Attribute Description Required Possible Values
lead_generation_properties Properties that describe the lead generation form. Yes Lead Generation Properties JSON entity.
legal_disclosures Custom Legal Disclosures that users can consent to when submitting the form. Yes Legal Disclosures JSON entity.
banner_media_id Media ID of the form’s banner image. No A media ID string. For example: “a1cf456c-d4ab-4ecc-b4eb-7a63bc1234d2”

Creating a Lead Generation Ad using a creative

curl -X POST \
  -d '{"ads":[{"ad_squad_id":"123456bd-8300-45f9-b335-9a3592b5f95c","creative_id":"35fce3af-e1c7-46d4-a075-79180a3073ef","name":"My Lead Generation Ad","type":"LEAD_GENERATION","status":"ACTIVE"}]}' \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  https://adsapi.snapchat.com/v1/adsquads/123456bd-8300-45f9-b335-9a3592b5f95c/ads
{
    "request_status": "SUCCESS",
    "request_id": "61f48d3000ff091ecf5f32b8c10001737e616473617069736300016275696c642d61353730363532632d312d3531322d3000010125",
    "ads": [
        {
            "sub_request_status": "SUCCESS",
            "ad": {
                "id": "52328535-5947-4213-a8c0-da47d144f5ec",
                "updated_at": "2022-01-29T00:41:21.303Z",
                "created_at": "2022-01-29T00:41:21.303Z",
                "effective_status": "ACTIVE",
                "name": "My Lead Generation Ad",
                "ad_squad_id": "123456bd-8300-45f9-b335-9a3592b5f95c",
                "creative_id": "35fce3af-e1c7-46d4-a075-79180a3073ef",
                "status": "ACTIVE",
                "type": "LEAD_GENERATION",
                "render_type": "STATIC",
                "review_status": "PENDING",
                "review_status_reasons": [],
                "review_rejection_ids": [],
                "approval_type": "NONE",
                "conditional_approval_reason_ids": [],
                "conditional_approval_reason_texts": [],
                "delivery_status": [
                    "INVALID_PENDING_REVIEW_STATUS",
                    "INVALID_EFFECTIVE_INVALID"
                ]
            }
        }
    ]
}

For Lead Generation Ads, type property must be set to LEAD_GENERATION.

Example 1 - Form with a header banner, and three multiple choice questions.

curl -X POST \
  -d '{"creatives":[{"ad_account_id":"8adc3db7-8148-4fbf-999c-8d2266369d74","name":"Form with lots of information","type":"LEAD_GENERATION","headline":"This is my headline","brand_name":"Great brand","shareable":true,"call_to_action":"SIGN_UP","top_snap_media_id":"3m08b7ea-2dc6-4854-a44f-b3am70665b32","lead_generation_properties":{"privacy_policy_url":"https://www.example.com","description":"Please answer these questions!","form_fields":[{"type":"FIRST_NAME"},{"type":"LAST_NAME"},{"type":"EMAIL"},{"type":"CUSTOM","custom_form_field_properties":{"type":"MULTIPLE_CHOICE_SINGLE_SELECTION","description":"What is your age range?","multiple_choice_descriptions":["0-14","15-25","25-50","Over 50"]}},{"type":"CUSTOM","custom_form_field_properties":{"type":"MULTIPLE_CHOICE_MULTI_SELECTION","description":"Which of these foods do you like?","multiple_choice_descriptions":["Hamburgers","Pizza","Salad","Steak"]}},{"type":"CUSTOM","custom_form_field_properties":{"type":"TEXT","description":"What is your favorite movie?"}}],"banner_media_id":"d5cf309c-d4ab-4ecc-b4eb-3u63ba3314c2"}}]}' \
  -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": "61f9c69900ff00ff783c74d19a860001737e616473617069736300016275696c642d37353461666336622d312d3531332d3000010162",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "35fce3af-e1c7-46d4-a075-79180a3073ef",
                "updated_at": "2022-02-01T23:47:38.213Z",
                "created_at": "2022-02-01T23:47:38.213Z",
                "name": "Form with lots of information",
                "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
                "type": "LEAD_GENERATION",
                "packaging_status": "IN_PROGRESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "This is my headline",
                "brand_name": "Great brand",
                "call_to_action": "SIGN_UP",
                "render_type": "STATIC",
                "top_snap_media_id": "1f08b7ea-2dc6-4854-a44f-z1xc23456b32",
                "top_snap_crop_position": "MIDDLE",
                "ad_product": "SNAP_AD",
                "lead_generation_properties": {
                    "privacy_policy_url": "https://www.example.com",
                    "description": "Please answer these questions!",
                    "form_fields": [
                        {
                            "type": "FIRST_NAME",
                            "is_required": true
                        },
                        {
                            "type": "LAST_NAME",
                            "is_required": true
                        },
                        {
                            "type": "EMAIL",
                            "is_required": true
                        },
                        {
                            "type": "CUSTOM",
                            "is_required": true,
                            "custom_form_field_properties": {
                                "type": "MULTIPLE_CHOICE_SINGLE_SELECTION",
                                "description": "What is your age range?",
                                "multiple_choice_descriptions": [
                                    "0-14",
                                    "15-25",
                                    "25-50",
                                    "Over 50"
                                ]
                            }
                        },
                        {
                            "type": "CUSTOM",
                            "is_required": true,
                            "custom_form_field_properties": {
                                "type": "MULTIPLE_CHOICE_MULTI_SELECTION",
                                "description": "Which of these foods do you like?",
                                "multiple_choice_descriptions": [
                                    "Hamburgers",
                                    "Pizza",
                                    "Salad",
                                    "Steak"
                                ]
                            }
                        },
                        {
                            "type": "CUSTOM",
                            "is_required": true,
                            "custom_form_field_properties": {
                                "type": "TEXT",
                                "description": "What is your favorite movie?"
                            }
                        }
                    ],
                    "banner_media_id": "d5cf309c-d4ab-4ecc-b4eb-3u63ba3314c2"
                }
            }
        }
    ]
}
curl -X POST \
  -d '{"creatives":[{"ad_account_id":"8adc3db7-8148-4fbf-999c-8d2266369d74","name":"Form with consent","type":"LEAD_GENERATION","headline":"This is my headline","brand_name":"Great brand","shareable":true,"call_to_action":"SIGN_UP","top_snap_media_id":"3m08b7ea-2dc6-4854-a44f-b3am70665b32","lead_generation_properties":{"privacy_policy_url":"https://www.example.com","description":"Please answer these questions!","form_fields":[{"type":"FIRST_NAME"},{"type":"LAST_NAME"},{"type":"PHONE_NUMBER"}],"legal_disclosures":{"title":"Legal Terms","description":"These are our terms","consent_form_fields":[{"consent_description":"I read your terms","required":true},{"consent_description":"I agree your terms","required":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": "61f9cbe000ff06c274effe15af0001737e616473617069736300016275696c642d37353461666336622d312d3531332d3000010135",
    "creatives": [
        {
            "sub_request_status": "SUCCESS",
            "creative": {
                "id": "35fce3af-e1c7-46d4-a075-79180a3073ef",
                "updated_at": "2022-02-02T00:10:09.887Z",
                "created_at": "2022-02-02T00:10:09.887Z",
                "name": "Form with consent",
                "ad_account_id": "8adc3db7-8148-4fbf-999c-8d2266369d74",
                "type": "LEAD_GENERATION",
                "packaging_status": "IN_PROGRESS",
                "review_status": "PENDING_REVIEW",
                "shareable": true,
                "headline": "This is my headline",
                "brand_name": "Great brand",
                "call_to_action": "SIGN_UP",
                "render_type": "STATIC",
                "top_snap_media_id": "1f08b7ea-2dc6-4854-a44f-a8da70665b32",
                "top_snap_crop_position": "MIDDLE",
                "ad_product": "SNAP_AD",
                "lead_generation_properties": {
                    "privacy_policy_url": "https://www.example.com",
                    "description": "Please answer these questions!",
                    "form_fields": [
                        {
                            "type": "FIRST_NAME",
                            "is_required": true
                        },
                        {
                            "type": "LAST_NAME",
                            "is_required": true
                        },
                        {
                            "type": "PHONE_NUMBER",
                            "is_required": true
                        }
                    ],
                    "legal_disclosures": {
                        "title": "Legal Terms",
                        "description": "These are our terms",
                        "consent_form_fields": [
                            {
                                "consent_description": "I read your terms",
                                "required": true
                            },
                            {
                                "consent_description": "I agree your terms",
                                "required": true
                            }
                        ]
                    }
                }
            }
        }
    ]
}

FAQ

Setting up your app

Can I use this API without a redirect url?

You cannot use this API without a redirect_uri, but this part of the API is only used for authentication. part, it’s fully possible for you to carry out the authentication part only once per user of the API.

How can I edit an existing redirect_url

You cannot edit an existing redirect_uri instead you will need to set up a new app with the redirect_uri that you wish to use.

Can I use this API to make server to server requests?

Yes, only the user authorization process of this API requires you to use a client (browser), this is needed in order to obtain the tokens that makes it possible to query the API (Access token and Refresh token). Once you have these two tokens, you can use them alongside your API client specific details in order to query the API in a server to server fashion.

What should the redirect url be? Do you have any rules around it?

The redirect URL should be a SSL hosted URL you control, or that you can set up. The purpose of the URL is to pass the code parameter which you will need in order to set up your first access token and refresh token.

You may choose to just copy the code out of a browser and then set up the tokens using a tool like POSTMan, or you might choose to build an application that is hosted on the redirect_uri itself, where the application will read the GET code parameter and then generate the tokens.

For example, let’s say you specify this redirect URL: https://www.example.com/index.html

After successful authentication the code parameter will be attached on the end of the URL the following way: https://www.example.com/index.html?code=1234567890

A step-by-step instruction for the full Authentication process can be found here: https://marketingapi.snapchat.com/docs/#full-web-flow-example

I can’t see OAuth apps section in Business Manager*

User Permissions and OAuth

When does the Access token and the Refresh token expire?

The refresh token does not expire, but will cease to function if the user it is tied to has their access removed.

The access token has an attribute expires_in which specifies the duration in seconds, a new access token will be valid for 1800 seconds = 30 minutes.

Do I need to generate a new access token if my user gets added to a new Organization/Ad Accounts?

No, the access token is specific to the Snapchat account used, so if ad accounts are added or removed, it is reflected without the need to generate new tokens. However if you are added to a new Organization you will need to accept the invitation in the Welcome email.

We previously had access to the Ads API but lost access after the user who set it up left

It’s possible that the employee used their own account when setting up the Access and Refresh token. If this is the case you need to generate new tokens, for a user account which you need to maintain and store the details for so that they do not get lost if an employee leaves your company.

How do I revoke access for an App?

You need to log in to the Snapchat account which has authorised the OAuth App access in order to revoke the access for that App.

  1. Navigate to this URL in a browser https://accounts.snapchat.com
  2. Log in as the user that granted access to the OAuth App in question
  3. Choose MANAGE APPS from the menu you are presented with https://accounts.snapchat.com/accounts/welcome Alternatively access the page directly by using this url https://accounts.snapchat.com/accounts/oauth2/apps
  4. The page will show you a list of all Applications that has been authorised to use your Ads API permissions on your behalf.
  5. Delete the app in question from the list.

Making API requests and interpreting responses

Can I use the Python requests library

Yes, however when using the Python requests library to upload Media files you need to remove one of the headers.

When using the Python requests library to upload files you should not include the header Content-Type':'multipart/form-data

When setting the headers in requests this should be sufficient:
headers = {'Authorization': 'Bearer ACCESS_TOKEN'}

Is the updated_at attribute on Ad level affected by Ad Review?

Yes it is, the updated_at attribute is updated when the review status of the Ad changes.

When requesting an entity I get the error message “Resource can not be found - error_code: E3003” what does it mean?

This type of error message (E3003) shows up in two different situations:

Was the entity deleted or misspelled?

To check if the entity has been deleted you can use the Audit logs for the entity in question. Audit logs are available for Campaigns/AdSquads/Ads/Creatives; https://developers.snapchat.com/docs/#audit-logs

This response means you do not have permission to access the Audit logs for the given entity

{
    "request_status": "ERROR",
    "request_id": "UNIQUE_ID",
    "debug_message": "None of the requested actions READ_CHANGE_LOG_RECORDS can be authorized. Current user principal: MEMBER_ID",
    "display_message": "We're sorry, but the requested resource is not available at this time",
    "error_code": "E3002"
}

This response means the entity ID is incorrect, there has never been an entity with this ID

{
    "request_status": "ERROR",
    "request_id": "UNIQUE_ID",
    "debug_message": "Resource can not be found",
    "display_message": "We're sorry, but the requested resource is not available at this time",
    "error_code": "E3003"
}

Do you have permission to the Ad Account where the entity lives?

Assuming you know the Ad Account that you are attempting to access, you can carry out the following checks.

This request shows which user the token represents, and the Organizations that the User is a Member of, the request is fully described in the User section.
GET https://developers.snapchat.com/docs/#user

This request will show you the Ad Accounts and the roles the user has within those Ad Accounts.
GET https://adsapi.snapchat.com/v1/me/organizations?with_ad_accounts?true

The User permission request is explained in our section on fetching all Organizations with Ad Accounts.

If the user doesn’t have access to the Ad Account they are attempting to access it’s possible for an Organization Admin to add them via Snap Business Manager.

If the user in question has access to the Ad Account already, but has got incorrect permissions, you can amend their Role to match the permissions they need to carry out the intended task.

Fetching Reporting via the API

What Role do I need to fetch Campaign reporting from an Ad Account?

This can be managed by using the API for Members and Roles, or it can be handled within Snap Busines Manager where the role is referred to as Data Manager.

Is there a way to get dummy data from the API whilst developing my reporting App?

Yes, you can get dummy data if you add test=true to any reporting API request, that will return dummy data.

My daily reporting job has started failing.

If your reporting was working, and then suddenly started failing, there is a possibility that daylight savings are the cause of this.

When you make your request to the API you need to take into account that we save all our timings in UTC, so you will need to add/subtract hours in order to make up a 24 hour period that corresponds to the setting in your Ad Account.

If we assume an account is set to Europe/Berlin (Central European Time). During daylight savings Europe/Berlin will be +1 hour ahead of UTC, prior to Daylight savings Europe/Berlin will be +2 hours ahead of UTC.

This means that if you added 2 hours to your start_time and end_time during the daylight savings period, you will now need to add just 1 hour to the start_time and end_time once daylight savings are

In the situation that you request a report where the start_time is in a period when daylight savings were active, and where the end_time is in the period where daylight savings ended you will need to +2 hours to the start_time and +1 hour to the end_time.

You should take daylight savings into account for your application when structuring reporting requests.

How do metrics in the Snap Ads Manager map to fields in the Snap Marketing API?

The following table shows how some of the common metrics in the Snap Ads Manager translate to fields in the Marketing API. Calculated Metrics in the Snap Ads Manager do not directly map to fields in the Marketing API. A description of how these metrics are calculated in the Ad Manager can be found in the Notes column.

Ads Manager Metric Marketing API Field Metric Type Notes
Start Time start_time Entity Attribute Ad squad attribute
End Time end_time Entity Attribute Attribute in campaign and ad squad object
ID id Entity Attribute The entity ID for a campaign, ad squad or ad object
Campaign/Ad Squad/Ad Name name Entity Attribute The entity name for a campaign, ad squad, or ad object.
Status status Entity Attribute The entity status for a campaign, ad squad, or ad object.
Spend spend Raw Metric
Paid Reach uniques Raw Metric
Paid Impressions impressions Raw Metric
Paid Frequency frequency Raw Metric
Paid eCPM - Calculated Metric Effective cost per thousand impressions. Calculated by taking the average cost for every 1,000 impressions.
Swipe Ups swipes Raw Metric
Swipe Up Rate - Calculated Metric The average number of swipes per impression. Shows as a percentage.
eCPSU - Calculated Metric Effective cost per swipe up. Calculated by taking the average cost per each swipe up.
Video Views video_views Raw Metric
eCPV - Calculated Metric Effective cost per video view. Calculated by taking the average cost per qualified video view.
Completions view_completion Raw Metric
Avg Screen Time - Calculated Metric The average number of seconds spent watching your ad across all paid impressions.
ROAS - Calculated Metric Return on ad spend. The value of generated sales relative to your media spend.
Attachment Frequency attachment_frequency Raw Metric
Attachment Reach attachment_uniques Raw Metric
Purchases Value conversion_purchases_value Raw Metric
Purchases conversion_purchases Raw Metric

Marketing API Newsletter

The Snapchat Marketing API Newsletter provides updates on new launches and deprecations for the Marketing API and the Conversions API. Marketing API Newsletter Sign up

Change Log

Date Description
2024-02-29 Updated Creatives to require the profile_properties field
2024-02-08 Added new Organization level Role data_admin , this is a reporting only role
2024-02-08 Added new placement PUBLIC_STORIES_INSTREAM
2024-01-30 Added new delivery_status LEARNING_PHASE for Ad Squads
2024-01-30 Added method to update Pixel at Organization level
2024-01-30 Removed deprecated attributes allow_snap_javascript_sdk and use_immersive_mode from webview properties
2024-01-30 Added new call to action VIEW_PROFILE
2024-01-27 Added Public Profile stats supported granularities, SPOTLIGHT stats fields, and new authorized data sharing endpoints
2023-12-26 Added FAVORITES to the list of supported metrics for STORY and SAVED_STORY
2023-01-10 Added documentation for Public Profile Search API tier parameter
2023-01-09 Added documentation for visibility parameter in Public Profile Saved Stories API
2023-11-17 Added new section introducing the Public Profile Search API
2023-11-06 Added new section introducing the Transactions entity
2023-10-24 Document Dynamic Template Changelogs
2023-07-24 Added update on the European Digital Service Act
2023-07-24 Added CAROUSEL and SLIDESHOW layout for Dynamic Collection Ads
2023-07-24 Updated the Ad Squad section, added conversion_window, updated Placement to Ad type, Optimisation goal to Ad type
2023-07-24 Snapcode Preview now supports Dynamic Ads
2023-07-24 Following deprecation in February Audience filters (FILTER), Longform video (LONGFORM_VIDEO) and Lens Longform video (LENS_LONGFORM_VIDEO) have been removed from the docs, Ad type specific metrics associated with these Ad types can still be fetched
2023-06-08 Added discover Public Profile stats documentation
2023-06-08 Update documentation of the Profile media upload API
2023-06-01 Added discover Public Profile Lenses documentation
2023-05-29 Added discover Public Profile Saved Stories documentation
2023-05-25 Added discover Public Profile Spotlights documentation
2023-05-22 Updated documentation for spotlight posting
2023-05-18 Added discover Public Profile documentation
2023-05-04 Added announcement for pagination enforcement
2023-04-03 Added possible objective values for campaign creation
2023-02-28 Add new INTERSTITIAL_SPOTLIGHT position to PlacementV2
2023-01-24 Updated CAPI Business SDK copy and removed beta
2022-12-23 Added Targeting Auto Expansion update in Announcements and Targeting section
2022-12-23 Added Long form Video deprecation in Announcements
2022-12-23 Added new First party Shopper Interest targeting (shp)
2022-12-23 Added new Dynamic Template option AUTOMATIC
2022-12-23 Updated Reporting Insights and Dimensions, breakdown by Country and Operating System is now available
2022-12-23 Deprecated Placed Interest targeting (plc)
2022-12-23 Deprecated the reporting parameter platform_stats
2022-12-23 Deprecated the placement_v2 snapchat_positions option GAMES
2022-12-23 Deprecated the placement_v2 snapchat_positions option AUDIENCE_EXTENSION
2022-09-29 Updated Ad Squad section, added currency aware bids, maximum value of bid_micro is now dependent on the currency of the Ad account
2022-09-29 Updated Measurement Section, all conversion events now have an equivalent value metric
2022-09-29 Updated Measurement section, added new metric profile_clicks
2022-09-29 Updated Role Section, how to update the Role type
2022-09-29 Updated User section, the response now includes the snapchat_username of the user
2022-09-29 Updated Interest Targeting section, interest targeting for SCLS and VAC now has a new endpoints and parameters
2022-09-29 Updated Targeting section, fetching targeting options per Country now has a new endpoint and a new parameter for non-US countries
2022-09-15 Added “post saved story” documentation in Profile API.
2022-09-14 Add “locale” in the post spotlight documentation in Profile API.
2022-09-02 Added “get spotlight” and “post spotlight” documentation in Profile API.
2022-08-24 Corrected some parameter terms in curl example and Best Practices section.
2022-08-22 Update Conversion API docs to improve language and fix typos on how to get started
2022-08-18 Corrected Snap Lifestyle Categories API to reflect updated country code param
2022-07-14 Updated Conversion API event_type with LEVEL_COMPLETE
2022-07-13 Updated public profile APIs
2022-07-06 Updated parameter best practices information
2022-07-06 Updated Product Search and Facets sections to include new travel endpoints (/products/search, /flights/search, /hotels/search) and associated attributes
2022-05-24 Updated creatives section to include instructions on attaching a profile
2022-05-23 Updated AdSquad SKAdNetwork section with critical changes to SKAdnetwork tracking and introduction of ecid_status
2022-05-23 Updated Measurement section, deprecated Reporting Insights for Conversion metrics for region, dma, lifestyle_category, product and make
2022-05-23 Added new section for the Marketing API Newsletter
2022-04-07 Renamed SAM (Snap Audience Match) to “Customer List” to align naming with other parts of the platform.
2022-01-10 Updated Ad Squad Section, Pixel/App Optimization goals no longer require conversions to unlock
2022-01-06 Updated Measurement section to include Lead Gen Reporting
2021-11-12 Added a new scopes table for coversion API and updated the auth docs to support multiple scopes
2021-10-25 Updated announcements, timelines and reference documentation for Ad squad targeting updates
2021-10-25 Updated entire Conversion API section
2021-10-25 Updated Ad Squad section, placement_v2, Story Ads can now serve in between User stories and Publisher stories
2021-10-05 Added the new Showcase Creative type to the Dynamic Collections Ads Guide
2021-10-05 Updated the Targeting Spec entity to include behaviour pre- and post 27 November 2021
2021-09-23 Updated Ad Squad section, the bid_strategy AUTOBID is now available to all App and Pixel Optimization Goals
2021-09-13 Updated Measurement section, SKAd reporting section updated with Ad level metrics (estimated) availability
2021-08-23 Added new section for Dynamic Story Ads
2021-08-23 Updated Measurement section, the granularity TOTAL is now available for frequency, uniques, attachment_uniques, attachment_frequency, total_reach, earned_reach
2021-08-23 Updated Measurement section, deprecated the HOUR granularity for frequency, uniques, attachment_uniques, attachment_frequency, total_reach, earned_reach
2021-08-23 Updated Measurement section, deprecated the metrics position_uniques and position_frequency
2021-08-23 Updated Entity Pagination section to include additional entities where pagination is supported
2021-06-17 Updated Ad Squad section with new attributes child_ad_type and forced_view_setting
2021-05-26 Updated SKAd Network Reporting to include VIEW conversions
2021-05-25 Deprecation of Story Ad metrics position_uniques and position_frequency announced
2021-05-25 Added new metric native_leads under Additional Metrics in the Measurement section
2021-05-25 Added new Media Rating Council accredited metrics in the Measurement section
2021-05-25 Updated Snap App ID section to include method to fetch all Snap App IDs under an Ad Account
2021-05-25 Updated Creative section specifying Snapcode Preview availability
2021-05-25 Updated Creative section, Story Ads now hold 1-20 individual Snaps
2021-05-25 Updated the Measurement section to consolidate Lens and Filter specific metrics under Additional metrics
2021-04-27 Added Apple Transparent Tracking changes to the Reporting and measurement API docs
2021-04-22 Updated DPA creative creation with url macros information
2021-04-12 Updated Ad, Ad Squad and Campaign sections to include new deleted attribute and new parameter read_deleted_entities
2021-04-12 Updated Roles section to include Catalog Roles
2021-03-12 Updated Ad Squad section to include SKAd Network attributes
2021-03-12 Updated Measurement section to include SKAd Network metrics and reporting
2021-03-03 Added new CTAs and delivery statuses
2021-02-03 Added a new section for Snap App ID
2021-02-03 Updated Ad Squad section to include new attribute event_sources
2021-02-03 Updated Dynamic Product Ads Guide to include new attribute event_sources
2021-02-03 Updated Targeting section to include new targeting option app_install_states
2021-02-03 Updated Targeting examples to include several examples of using app_install_states
2021-02-03 Updated available countries for Reach & Frequency Campaigns
2021-01-08 Added a new section for collection ads for DPA
2020-11-18 Added a new section under measurement for DPA reporting
2020-10-29 Updated section on Dynamic Ad products - Feed Upload to include UPSERT option
2020-10-23 Updated section on lookalike audience creation spec to support multi country targetting
2020-10-22 Added the parameter action_report_time (conversion, impression) for measurement requests
2020-10-22 Added the offline dimension to conversion_source_types for measurement requests
2020-10-19 Added new section for Conversion API
2020-10-12 Added new section for Dynamic Product Ads, introducing Feed Upload
2020-10-12 Added new section for Dynamic Product Ads, introducing Product Feeds
2020-10-12 Updated Dynamic Product Ads catalog section to include Create/Update/Delete
2020-09-22 Added test attribute for Ad Account creation in the /adaccounts endpoint
2020-09-22 Updated authentication section to call out the expiry of the Access token
2020-09-22 Updated section on Lookalike audience creation to include information on lookalike updating when seed audience is updated
2020-08-17 Updated Measurement section to include platform_stats attribute for use with the Snapchat Audience Network
2020-08-17 Updated Ad Squad section, placement_v2, Automatic Placement now mentions the Snapchat Audience Network
2020-07-27 Updated Dynamic Product Ads introducing Product Search and examples
2020-07-27 Added new section introducing the attribute delivery_status
2020-07-27 Added new section introducing the Invoice entity
2020-06-18 Updated Dynamic Product Ads introducing Dynamic Templates
2020-06-18 Updated Dynamic Product Ads introducing Catalog Diagnostics
2020-06-18 Updated Dynamic Product Ads with new examples of Prospecting and Retargeting Ad Squads
2020-06-18 Updated Creative and Lens section with new values for the Call To Action attribute
2020-06-18 Updated Ad Squad section to include clarification and example use of MIN_ROAS
2020-06-18 Updated Ad Squad section with additional Optimization Goals for use with Frequency Capping
2020-06-18 Updated Optimization Goals to include new goal APP_REENGAGE_OPEN
2020-06-18 Added example of SLC targeting exclusion to Example Targeting Spec section
2020-06-18 Added new table listing INCLUDE/EXCLUDE options for Targeting spec
2020-05-04 Added new section introducing the Role entity
2020-05-04 Added new section introducing the Member entity
2020-05-04 Added new section introducing the Billing Center entity
2020-05-04 Updated Ad Account Section with Ad Account Creation, Updating an Ad Account, assigning a Funding Source
2020-05-04 Updated the Ad Account attributes, to include political advertising, CHE and French Advertisers
2020-05-04 Updated Targeting section for Demographics, Age Range to list deprecated 35+ setting
2020-04-09 Updated bid_strategy section to clarify details on the sunsetting of auto_bid and target_bid
2020-04-09 Updated AdSquad spec daily_budget_micro, lowered from 20000000 to 5000000 (from £/€/$20 to 5)
2020-04-09 Updated AdSquad spec to clarify possible values of delivery_constraint
2020-04-02 Updated Commercials section to include videos longer than six seconds
2020-03-30 Updated targeting section to include multi-country targeting
2020-03-30 Updated targeting spec examples to include an example of multi-country targeting
2020-03-30 Added GAMES to placement_v2 including an example for GAMES placement via snapchat_positions
2020-03-30 Updated Commercials section based on new GAMES placement_v2 for snapchat_positions
2020-03-20 Added new section announcing upcoming breaking changes
2020-03-20 Added new section on bid_strategy and the new bid type MIN_ROAS
2020-03-20 Added new Creative types, AD_TO_CALL and AD_TO_MESSAGE
2020-03-20 Added new section for verifying phone number for AD_TO_CALL, AD_TO_MESSAGE Creative types
2020-03-20 Added new Insights and Dimensions section including new parameter report_dimension
2020-03-20 Updated placement_v2 section to include more examples and table comparing with placement
2020-03-20 Updated Ad Squad section with list of available Ad Types / Optimization Goal
2020-03-02 Updated Commercials section, two new countries Kuwait and Ireland
2020-03-02 Updated Creative section to list Filter and Lens
2020-02-13 Added docs for Lenses
2020-02-13 Updated Reach and Frequency to include additional launched countries
2020-02-13 Updated Audience source type to include MOBILE audiences
2020-01-21 Updated Authentication section - App set up and access to the API is now managed via Snap Business Manager
2019-12-19 Added docs for Dynamic Product Ads
2019-11-29 Added conversion_source_types parameter for breakout of conversions
2019-11-29 Added omit_empty parameter for reporting requests
2019-11-07 Added new section Commercials - How to set up and target Creatives to run as Commercials
2019-11-07 Updated Snap Audience Match - Update an Audience Segment
2019-11-07 Updated Targeting Demographics - Added min_age and max_age to Age Range
2019-11-07 Updated Targeting Section - Added enable_targeting_expansion
2019-11-07 Updated Measurement - Metrics and supported granularities table updated
2019-11-07 Updated Measurement section - Added 19 new Pixel conversion events
2019-11-07 Updated Measurement API patterns - Added Pagination
2019-11-07 Updated Ad Squad - pacing_type attribute at is now immutable
2019-11-07 Updated Audience Geofilters - Optimization goal IMPRESSIONS is now available
2019-11-07 Updated Bid Estimate - Added additional optimization goals
2019-11-07 Updated AdSquad - New measurement_provider_names DOUBLEVERIFY
2019-11-07 Updated AdSquad - New Third-Party Tracking Tags DOUBLEVERIFY
2019-11-01 Updated Ad - Upcoming changes to Third-party tracking fields
2019-10-03 Added new AdSquad optimization goal, video_views_15s
2019-10-03 Added new metrics video_views_time_based, video_views_15s
2019-10-03 Removed MOAT from Ad level third party tracking
2019-09-19 Updated Ad Account, Ad entities - added paying_advertiser_name for political ads
2019-09-19 Updated Campaign - added attribute candidate_ballot_information for political ads
2019-09-19 Updated Ad Account to include billing type attribute,
2019-09-10 Added new section under AdSquad - Third-Party tracking tags - MOAT
2019-09-10 Updated AdSquad - added attribute measurement_provider_names for Third-Party tracking
2019-09-10 Updated AdSquad - added parameter to return placement_v2
2019-09-10 Updated AdSquad - added content type GAMING
2019-09-10 Updated AdSquad - pacing_type is immutable once set
2019-09-10 Updated Campaign - added regulations attribute for Credit/Housing/Employment Ads
2019-08-09 Added On Demand Geofilter sunsetting announcement
2019-07-31 Added redirect_uri parameter to access token call
2019-07-31 Added docs for pacing_type
2019-07-31 Removed Innovid
2019-07-26 Added new section for Audit logs
2019-07-26 Updated pagination section to include change logs
2019-07-26 Updated metrics additional metrics available in real time
2019-07-26 Updated metrics removed WEEK and MONTH granularities
2019-07-18 Added docs for placement v2
2019-06-26 Added information on Entity Request Limits for Creating/Updating Entities
2019-06-26 Additional information on multipart media upload v2
2019-06-26 Pagination support for additional endpoints, All accounts under Organization, All Segments under Ad account
2019-06-26 Additional Optimization Goals for pixel and app added
2019-06-13 Updated multipart media upload to v2
2019-01-30 Changed daily_budget_micro to minimum value 20000000
2019-01-30 Added definition for response attribute finalized_data_end_time
2019-01-30 Updated campaign measurement_spec with relevant ad types
2019-01-30 Added clarification position_stats metric only available at LIFETIME granularity
2019-01-24 Updated the styling
2019-01-11 Added documentation for target cost bidding
2019-01-11 Added method for updating a Creative
2018-11-15 Added documentation for Collection creatives
2018-11-15 Added documentation for AdSquad mutability
2018-11-15 Removed targeting by country table in favor of the targeting by country endpoint
2018-11-06 Added Story Ad position metrics and updated Audience Filter bidding properties
2018-10-18 Added new Creative and Ad types for Lens with attachments
2018-10-18 Autobidding is allowed for Audience filters
2018-10-18 Added API method to retrieve SLC by country
2018-10-18 Added new source types PIXEL and FOOT_TRAFFIC_INSIGHTS for SAM audience
2018-10-08 Added documentation for Measurement for retrieving position metrics for Snap Ads within a Story Ad
2018-09-13 Added documentation for retrieving Placed Visitation Segments
2018-09-13 Added AUCTION as a buy_model type on Campaigns
2018-09-13 Added PHONE_SHA256 as a new schema for adding users to SAM segments
2018-09-12 Added documentation for Measurement for Ad types LENS, AD_TO_LENS, FILTER
2018-09-12 Added method for deleting an Audience segment
2018-09-12 Added method to retrieve roles for Ad Accounts for currently logged in user
2018-09-12 Added method for retrieving a thumbnail from Media of VIDEO type
2018-09-12 Called out our preferred gender targeting method in targeting examples
2018-09-12 Corrected the required fields for AdSquad creation and updating
2018-09-12 Corrected the http method for Audience Size v2
2018-08-01 Added documentation for Reach and Frequency buying
2018-08-01 Added documentation for fallback to webview for deeplink ads
2018-08-01 Added documentation for Audience Size v2
2018-07-01 Corrected minimum for radius targeting to 96 meters
2018-07-19 Added documentation for new optimization goals for pixel and app conversions
2018-07-19 Added documentation for new creative type and ad type AD_TO_LENS and media type LENS_PACKAGE
2018-07-19 Added documentation for min/max age targeting and modified targeting spec examples to include min_age and max_age
2018-07-19 Removed auto-fill SDK guidelines. Auto-fill no longer requires SDK to be installed
2018-07-06 Added documentation in API Patterns on how to retrieve paginated results when fetching many entities
2018-07-03 Added optimizaton goal STORY_OPENS
2018-06-26 Added documentation for Nielsen targeting categories
2018-06-26 Removed the word DLX from Advanced Demographics targeting options as it also includes Experian categories now
2018-06-26 Updated max radius for radius targeting to 100km
2018-06-26 Added documentation for auto bidding
2018-06-25 Added documentation for fetching a single audience segment by id
2018-06-13 Added documentation for audience insights
2018-06-13 Added documentation for new metric conversion_purchases_value
2018-06-13 Added note that new geofilter integrations will not be supported
2018-06-13 Added information about deprecated boolean flag for targeting dimensions
2018-06-13 Added link to supported currencies
2018-06-13 Ad Account timezones no longer need to be America/Los Angeles
2018-04-30 Added documentation for Story Ads, new creative types PREVIEW and COMPOSITE, new ad type STORY, new placement DISCOVER_FEED
2018-04-30 Added story_opens and story_completes metrics for Story Ads
2018-04-30 Added that for Story Ads the only optimization_goal supported is IMPRESSIONS
2018-04-30 Updated that Ad Scheduling is now available
2018-04-05 Added that Integral Ad Science (IAS) tags are now supported
2018-04-05 Added documentation for location categories
2018-04-05 Added documentation for point radius targeting
2018-03-15 Added measurement_spec into the campaign object attributes, required for all ads that need app tracking and post install conversion reporting
2018-03-15 Added notice that python SDK is not available yet and coming soon
2018-03-13 Added documentation on how to retrieve a preview for a Media
2018-03-08 Added documentation on how to retrieve a Snapcode preview for a Creative
2018-03-05 Added documentation that top snap media can now be of type IMAGE
2018-02-22 Added documentation for ad scheduling
2018-02-22 Updated that bid estimate can be used for all optimization goals
2018-02-22 Updated default retention_in_days for SAM is lifetime
2018-02-22 Updated that headline is required for geofilters and audience filters but never displayed
2018-02-22 Added FOOD, SPORTS, YOUNG_BOLD to included and excluded content types
2018-02-07 Updated call for generating a new access token from refresh token
2018-02-07 Updated that audience size endpoint returns estimated sizes
2018-02-07 Updated instructions for getting OAuth credentials
2017-11-30 Updated frequency cap time_interval maximum to 30 days or 720 hours
2017-11-28 Added documentation for attribution windows
2017-11-28 Added Paypal as a funding source option
2017-11-28 Updated that audience filters and geofilter media needs to be at least 50% transparent
2017-11-28 Removed granularity from Additional metrics table, refer Metrics and supported granularities table
2017-11-28 Removed goal_type from old API responses for Ad Squad object
2017-11-22 Updated MOAT tag
2017-11-20 Added lifetime_spend_cap_micro for the Campaign object
2017-11-20 Added DEEP_LINK to ad type options
2017-11-20 Added note that MOAT tagging is available for all snap ads products
2017-11-20 Updated geofilter and audience filter creative dimensions
2017-11-13 Added block_preload property for creatives with web view
2017-11-07 Removed pixel implementation details and added reference to Business Help Center guide for Snap Pixel
2017-11-07 Updated output for Get Pixel endpoint with pixel_javascript parameter
2017-11-07 Added new countries supported for Geofilters
2017-11-07 Updated impressions_composition and uniques_composition to impression_composition and unique_composition
2017-10-11 Updated that frequency caps can be edited once they are live
2017-10-10 Added documentation for frequency caps
2017-10-10 Added geopolygon support for geofilters
2017-10-10 Updated audience filter documentation to show zipcode targeting is allowed
2017-09-13 Updated fields for audience filter stats
2017-09-07 Added documentation for pixel stats endpoints
2017-09-07 Added documentation for reporting insights breakdowns
2017-09-07 Added new fields for Geofilter stats
2017-08-20 Added USER_STORIES placement option
2017-08-20 Added image specifications for app icon
2017-08-20 Added new countries: Oman, Bahrain, Malaysia, Philippines and Thailand
2017-08-20 Added note about campaign budgets being at least 0.25 of sum of its ad squad budgets
2017-08-20 Added minimum for ad squads daily budgets
2017-08-10 Added documentation for Audience Filters
2017-08-01 Added documentation for deep link creative type
2017-07-31 Added information about age_min targeting for geofilters
2017-07-31 Added geofilter schedule information. Geofilters can be bought 3 hours in advance on weekdays.
2017-07-31 Added note about max number of SAM segments allowed per ad account
2017-07-31 Updated third party tags section with examples and more information
2017-07-31 Updated language targeting example
2017-07-19 Added new fields upload_status and targetable_status for SAM segments
2017-07-12 Updated targeting geo matrix with new countries
2017-07-10 Added documentation for device make targeting
2017-07-10 Update documentation for creating an organization
2017-06-28 Added documentation and example for zipcode targeting
2017-06-28 Added note that deep_link_urls field is no longer needed
2017-06-21 Added new metrics fields video_views, screen_time_millis, avg_screen_time_millis
2017-06-20 Corrected examples for web view creatives to use “VIEW” call to action
2017-06-19 Removed pixel deletion
2017-06-16 Added that credit card funding sources can now be created via Business Manager
2017-06-16 Corrected content type enum from BEAUTY to BEAUTY_FASHION
2017-06-16 Added start_date and end_date fields for coupons in the funding source documentation
2017-06-12 Added that currency field on funding source object is only returned for line of credit and coupons
2017-06-09 Added documentation for included_content_types and excluded_content_types
2017-06-06 Added GBB for video views
2017-05-25 Added advertiser_organization_id to Ad Account attributes
2017-05-25 Corrected HTTP Request for creating pixels
2017-05-25 Updated targeting by country matrix with new countries
2017-05-25 Added documentation for new types of funding sources and updated GET fundingsources output
2017-05-25 Updated OS version targeting example to include os_version_min and os_version_max
2017-05-25 Added information that geofilters can now be bought 90 days in advance
2017-05-25 Updated geofilter radius limit
2017-05-18 Added documentation for language targeting
2017-05-18 Added OS version targeting and language example
2017-05-18 Added timestamp macro to supported macros for third party tracking urls
2017-05-11 Updated Pixel SDK code
2017-05-11 Added CONTENT placement
2017-05-11 Added OS version targeting
2017-05-11 Added information about creating ad accounts in Business Manager
2017-05-11 Removed old breaking change section
2017-05-11 Added documentation for conversion stats
2017-05-11 Updated old links
2017-05-03 Added documentation for Snap Pixel
2017-05-03 Added measurement spec field on the campaign object
2017-05-02 Modified MOAT tag example with new MOAT tag
2017-05-02 Added new countries support to the targeting options matrix
2017-05-02 Added new currecies supported
2017-05-02 Added details about DLXP targeting
2017-05-02 Added the stats granularity matrix
2017-05-02 Added Apsalar to the list of supported mobile measurement partner intergrations
2017-05-02 Added the supported countries for geofilters
2017-05-02 Corrected dimensions for geofilter creative spec
2017-04-20 Added default retention days for SAM
2017-04-20 Added min and max for geofilter targeting radius
2017-04-20 Added note that geofilters should run at least for an hour
2017-04-20 Added note that geofilters need to start and end by the hour
2017-04-20 Updated that geofilters need to be purchased at least 16 hours before intended delivery
2017-04-20 Clarified geofilter Ad Squads can only have one location in the targeting spec
2017-04-17 Updated SLC targeting abilities in the targeting by country matrix
2017-04-17 Updated SAM and Lookalike targeting abilities in the targeting by country matrix
2017-04-17 Added upload image media example for app icon and app icon specifications
2017-04-17 Added tracking_urls to attributes that can be updated for Ad object
2017-04-17 Added WATCH as CTA option for webview
2017-04-17 Added brand_name and headline to the creative example
2017-04-17 Added example for metro targeting
2017-04-07 Fixed example for geofilter price quote endpoint
2017-04-06 Added documentation for geofilter stats
2017-04-06 Added information about pausing geofilter ads
2017-04-04 Added docs for Geofilters
2017-03-29 Added note that Ad Squads targeting cannot be updated after review
2017-03-29 Added documentation for targeting options by country endpoint
2017-03-29 Added documentation for deep linking
2017-03-29 Added documentation for auto-fill
2017-03-17 Added example for third party view tracking
2017-03-17 Added documentation for lookalike type enum
2017-03-17 Added documentation for source_type ENGAGEMENT
2017-03-17 Fixed date for upcoming breaking changes to 1st April
2017-03-17 Added Finland to the targeting geo matrix
2017-03-15 Added GBB for APP_INSTALLS as an option coming soon
2017-03-09 Added list of allowed Third Party tracking URLs
2017-03-09 Added matrix for targeting types allowed by country
2017-03-09 Fixed example for targeting using carrier_id
2017-03-09 Fixed formatting issue in DLX targeting doc
2017-03-09 Fixed formatting in rate limits doc
2017-03-08 Added breaking change about Creative brand_name and headline
2017-03-08 Added Upcoming Breaking Changes section
2017-02-28 Fixed examples for bid estimate by targeting spec
2017-02-28 Added lifetime_spend_cap_micro
2017-02-28 Added DLXC examples
2017-02-28 Fixed errors in examples with bid_type
2017-02-28 Added delete and remove all users for SAM
2017-02-28 Added bid estimate API
2017-02-28 Update examples from daily_budget to daily_budget_micro
2017-02-15 Updated measurement metric availability details
2017-02-15 Added new CTA options for Web View Creative
2017-02-08 Added Mobile Measurement Setup Help Links to App Install Creative section
2017-02-06 Removed note regarding limited country availability
2017-02-02 Added Brand Name & Headline optional properties to Creative section
2017-01-18 Added OPTIMIZED crop option
2017-01-18 Added Bulk Fetch details for Ad Squads & Ads
2017-01-12 Added Third-Party Tracking details to Ad section
2017-01-05 Added targeting examples for DLX
2017-01-05 Added DLX Interests targeting details
2017-01-05 Added DLX Advanced Demographics targeting details
2017-01-05 Fixed typo in carrier targeting spec & example
2016-12-07 Added Audience Size section & usage examples
2016-12-07 Added Metro / DMA Targeting section & usage example
2016-12-07 Added Carrier Targeting section & usage example
2016-11-11 Added Goal-Based Bidding details to Ad Squad section
2016-11-02 Additional metrics (including attachment metrics) details updated
2016-11-02 Rate Limits section added
2016-09-23 Added Chunked Upload details to Media section
2016-09-20 Added Lookalike creation details to Snap Audience Match section
2016-09-20 Removed Creative Update section
2016-09-20 Added allowable “call_to_action” values for each Creative attachment type
2016-09-16 Changed “icon_media_id” property for App Install creative to Required
2016-09-16 Updated Ad Type options & Ad Type <-> Creative Type Mapping
2016-09-14 Added full web redirect OAuth2 Flow
2016-09-14 Added “review_status” and “review_status_reason” properties on Ad
2016-09-14 Added “total_budget_micro” and “budget_spent_micro” properties on Funding Source
2016-09-14 Added “breakdown” parameter to Measurement requests
2016-09-14 Added “test” parameter to Measurement requests for sample/fake stats response
2016-09-14 Added “regulated_content” property to Targeting on Ad Squad
2016-09-14 Removed “category_type” property from Interest Targeting on Ad Squad
2016-09-08 Updated targeting examples with updated age values
2016-09-01 Removed third party tracking URLs from Ad
2016-08-30 SAM - Added details on adding users + normalizing/hashing identifiers
2016-08-30 SAM - Removed “source_subtype” property
2016-08-30 Media objects now have a “download_link” property with full URL to file
2016-08-15 Snap Audience Segments ID property is now “id” instead of “segment_id”
2016-08-15 Updated Measurement examples
2016-08-15 Added Access Token Expiration section
2016-08-15 Fixed SCLS targeting examples
2016-08-15 Initial documentation released to partners

Breaking Changes Log

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",
                "delivery_constraint": "DAILY_BUDGET"
            }
        }
    ]
}

Multi-country targeting

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

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

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

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

March 2020

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

Deprecation of Insight parameters dimension and pivots

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

New bid_strategy attribute replaces auto_bid and target_bid

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

Deprecation of placement in favour of placement_v2

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