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.

On the 23rd of July, 2023 all Marketing API endpoints that support pagination will be paginated and will have a default limit of 1000 rows even if you did not specify any pagintion parameters.
By the 23rd of July, 2023 you must support the pagination features supported by the API to continue consuming the API without any disruptions.
The limit parameter can still be passed to the API and can be used to specify a limit lower than 1000.

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

The Long form Video attachment and Audience Filters are due for deprecation on 1 February 2023, it will not be possible to create Longform Video attachments or Audience Filters after deprecation.
The snapchat_positions options GAMES and AUDIENCE_EXTENSION have been deprecated, these were found under placement_v2 which specifies the placement of Ads in the Snapchat client.
The reporting parameter platform_stats has been deprecated

Targeting auto-expansion changes

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

We are deprecating the attribute enable_targeting_expansion in favour of auto_expansion_options.
auto_expansion_options allows targeting to expand by interest via interest_expansion_option , and custom audiences via custom_audience_expansion_option
Both expansion options will be enabled by default when creating an Ad Squad.
Ad Squads that form part of a Campaign targeting Housing, Credit or Employment, should always have auto-expansion disabled.
Auto expansion is described in full in the Targeting section of our docs.

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

On the 27th of November all Marketing API endpoints that support pagination will be paginated and will have a default limit of 1000 rows even if you did not specify any pagintion parameters.
By the 27th of November you must support the pagination features supported by the API to continue consuming the API without any disruptions.
The limit parameter can still be passed to the API and can be used to specify a limit lower than 1000.

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:

One or more Funding Sources. A Funding Source references the Organization’s line of credit or a portion thereof.
One or more Ad Accounts. An Ad Account references one or more Funding Sources.

Ad Accounts are the primary vehicle for organizing all relevant advertising objects. An Ad Account owns:

One or more ad Campaigns (and all of its children).
One or more Media objects. Media are the most atomic objects - a single video file is a Media object.
One or more Creative objects. A Creative references at least one Media object along with metadata regarding how the creative should be presented to the user.
Zero or more Audience Segments. An Audience Segment is a targetable list of user 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!

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

API Patterns

The API has a consistent pattern for requests.

Get Many Entities

Pattern:

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

Example:

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

Get a Single Entity

Pattern:

GET /v1/{PLURAL_ENTITY_NAME}/{ENTITY_ID}

Example:

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

Pagination

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

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

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

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

Paginated calls are supported for these requests;

Get all Ads under an Ad Account/Campaign/Ad Squad
Get all Ad Squads under an Ad Account/Campaign
Get all Campaigns under an Ad Account
Get all Creatives under an Ad Account
Get all Media under an Ad Account
Get all Ad Accounts under an Organization
Get all Audience Segments under an Ad Account
Get all Mobile Apps under an Organization
Get all Billing Centers under an Organization
Get all Pixels under an Organization
Get all Interaction Zones under an Ad Account
Get all Dynamic Templates under an Ad Account
Get Zipcode targeting options
Get Audit logs

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

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

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

You must replace meowmeowmeow with your access token.

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

{
  "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

{
    "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

{
    "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"

"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"

{
  "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"

{
    "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"

{
  "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"

{
  "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"

{
  "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
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"

{
    "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"

{
    "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

{
    "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

{
    "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"

{
    "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"

{
    "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"

{
    "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"

{
    "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"

{
    "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

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

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

If the ad account will be used for housing, credit or employment advertising it needs to have the attribute regulations.restricted_delivery_signals set to true
If the ad account will be used for political advertising the attribute paying_advertiser_name needs to be filled out with the political organization or advocacy group who is paying for the ad (32 character limit)
If the Ad Account is owned by an agency buying ads on behalf of an advertiser the attribute agency_representing_client needs to be set to true
If the Ad Account is owned by an agency buying ads on behalf of an advertiser, and the Advertiser is based in France, or will target ads to an audience in France, the following settings will apply:
- The attribute agency_representing_client needs to be set to true
- The attribute client_paying_invoices needs to be set to true if the agency is paying the invoices, or false if the advertiser they represent is paying the invoices
- The attribute client_based_in_country needs to be set to fr
- The attribute agency_client_metadata needs to be set using the attributes name, email, address_line_1 , city, administrative_district_level_1, country, zipcode and tax_id

HTTP Request

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"

{
  "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"

{
  "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

{
    "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

{
  "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

{
    "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

{
    "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

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

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

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

Ad Account creation - Example 4

Ad Account - Setting up a test Ad Account

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

{
    "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"

{
    "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"

{
    "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

{
    "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"

{
    "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"

{
    "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"

{
    "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

{
    "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"

{
    "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

{
    "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

{
    "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

{
  "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"

{
    "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"

{
    "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"

{
  "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

{
  "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"

{
  "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"

{
  "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"

{
  "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.

They must have the same Goal-based Bidding optimization goal.
Dynamic Product Ads cannot be mixed with non-dynamic ad types.
Commercials cannot mixed with non-commercial ads.
Lens ads cannot be mixed with non-lens ad types.
Ad Squads that contain ads of multiple formats cannot enroll in SKAdNetwork tracking.
Ad Squads that contain ads of multiple formats do not support frequency capping using the cap_and_exclusion_config property if they are inside of Auction campaigns.

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.

IMPRESSIONS
SWIPES
APP_INSTALLS
PIXEL_PURCHASE
PIXEL_SIGNUP
APP_PURCHASE
APP_REENGAGE_OPEN

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'

{
    "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.

{
    "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.

{
    "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

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

{
    "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.

Opting an Ad Squad into SKAd tracking will only be possible at the point of creation (see existing example)
After the 7 September we are deprecating the ability to opt in an existing Ad Squad into SKAd tracking by means of updating it (see existing example)
After the 7 September we are deprecating the ability to opt out an Ad Squad out of SKAd tracking by means of updating it (see existing example)
You can withdraw an opted-in Ad Squad from SKAd tracking by pausing it and detaching the Apple Campaign ID using the newly introduced ecid_enroll_action, this will free up the Campaign ID for use in a different Ad Squad (see new example)
You can re-enable an Ad Squad into SKAd tracking by updating the ecid_enroll_action to attach an Apple Campaign ID and unpausing the Ad Squad (see new example).
In addition to the method that checks if an Apple Campaign ID is available, we have now introduced a new method that lists all Ad Squads that are visible to you that have an Apple Campaign ID attached to them.

SKAdNetwork prerequisites & restrictions

SKAdNetwork prerequisites

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

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.
A SKAdnetwork Campaign ID is available for the Snap App ID.
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:

The Optimization goals (optimization_goal) APP_REENGAGE_OPEN and APP_REENGAGE_PURCHASE are not available.
The bid strategies (bid_strategy) MIN_ROAS and TARGET_COST are not available.
Ad Squads that are delivering ads of multiple formats cannot enroll in SKAdNetwork.

SKAdNetwork Campaign ID check

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

{
    "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"

{
    "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

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

{
    "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

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"}}]}

{
    "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

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

{
    "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

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

{
    "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

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

{
    "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

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

{
    "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”;

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

Placement V2

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

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

The below table outlines the relationship between placement and placement_v2.

placement	placement_v2 - snapchat_positions
SNAP_ADS	INTERSTITIAL_USER, INTERSTITIAL_CONTENT, 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:

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

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

Squad Optimization Goals

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

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

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

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

Pixel; Ad Account has Snap Pixel created and installed on website, relevant Pixel events like ADD_TO_CART, SIGNUP and PURCHASE have been configured successfully
In-App events; App has been set to trigger and pass relevant events, ADD_TO_CART, SIGNUP and PURCHASE via the MMP † These optimization goals requires App Install State targeting for the App where the re-engagement takes place, see targeting example

Squad Optimization Goal Per Ad Type

This table outlines the Optimization Goals availability per Ad Type.

Optimization Goal	Ad Types
IMPRESSIONS	SNAP_AD, AD_TO_LENS, APP_INSTALL, COLLECTION, DEEP_LINK, FILTER, LENS, LENS_APP_INSTALL, LENS_DEEP_LINK, LENS_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

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

{
    "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.

Ad Squads that use ad scheduling must have a lifetime_budget_micro set instead of a daily_budget_micro
The schedule set in ad_scheduling_config cannot conflict with the flight dates of the Ad Squad
Ad Squads should have a minimum interval of 1 hour across any day they select to run on
Ad scheduling will respect the user’s timezone. The flight dates will continue to respect the ad account timezone. So an Ad Squad scheduled for Sunday morning 8-11 AM will show for a user based in Los Angeles between 8 AM and 11 AM Pacific time and for a New York based user between 8 AM - 11 AM Eastern Time which is 5AM - 8AM Pacific Time.
Ad scheduling is mutable
Ad scheduling config can supoort multiple ranges per day

Usage

"ad_scheduling_config": {
    "monday": {
        "hour_of_day": [1, 2, 3, 8, 9, 10]    
    },
    "tuesday": {
        "hour_of_day": [11, 12, 13]
    }
}

This would describe an ad running on Monday from 1am - 3am && 8am - 10am and Tuesday from 11am - 1pm. The possible values for the keys are: monday, tuesday, wednesday, thursday, friday, saturday, sunday

Attribute	Description	Type	Possible Values
hour_of_day	array of integers specifying the times of day	array of integers	0-23

Targeting Spec Examples

See the Targeting Spec Examples

Content Type

included_content_types and excluded_content_types can be used to specify more granular placement depending on the type of content.

Depending on the placement, included_content_types and excluded_content_types may or may not be specified.

placement	included_content_types	excluded_content_types
SNAP_ADS	Cannot be specified	Can be specified
CONTENT	Can be specified	Can be specified
USER_STORIES	Cannot be specified	Cannot be specified
DISCOVER_FEED	Cannot be specified	Cannot be specified

Create an Ad Squad

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

{
  "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

{
  "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"

{
  "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"

{
  "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"

{
  "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"

{
  "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

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

{
  "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

{
  "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"

{
  "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"

{
    "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"

{
  "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"

{
  "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"

{
  "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

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

Additional Ad Attributes

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

Approved Third Party Tracking URL domains

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

How to get tags

DCM and IAS: Refer to your DCM/IAS Account Manager to request tags or generate them using the campaign management tools.
mDAR: Clients should request their Snapchat Account Manager to provide a tag.

Notes

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

URL Macros

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

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

Media

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

Attributes

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

Create Media

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

{
  "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

{
  "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

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

HTTP Request

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

Parameters

Parameter	Default	Description
media_id		Media ID

Upload Large Media (Chunked)

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

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

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

Request and Parameters for INIT

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

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

Request and Parameters for ADD

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

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

Request and Parameters for FINALIZE

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

Parameter	Description
upload_id	Chunked Upload ID from INIT


1. Split the large file

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

2. Initialize a chunked upload request

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

3. Extract upload_id, add_path and finalize_path from response:

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

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

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

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

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


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

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

{
  "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"

{
  "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"

{
  "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"

{
    "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"

{
    "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

{
  "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

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

Mobile Measurement Partners - Setup Details

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

{
  "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

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

HTTP Request

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

Parameters

Parameter	Default	Description
ad_account_id		Ad Account ID

Create a Snap Ad with Deep Link attachment

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

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

Attributes

Attribute	Description	Required	Possible Values
ad_account_id	Ad Account ID	R
brand_name	Brand Name	R	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

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

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

{
  "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

{
    "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"

{
    "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

{
    "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

{
    "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

{
    "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

{
    "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

{
    "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

{
    "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

{
    "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

{
    "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"

{
  "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"

{
  "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"

{
    "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"
          }
        }]
    }'

{
    "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.

{
    "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.

{
    "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

{
    "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.

{
    "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

{
    "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

{
    "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

{
    "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

"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

"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

"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:

A Snap App ID for the App needs to be set up in order to verify your app setting up your Snap App ID.
The Ad Squad needs to have the event_sources attribute set up, the Snap App ID used in event_sources should match the Snap App ID used in the app_install_states

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

When using the Optimization Goal APP_REENGAGE_OPEN or APP_REENGAGE_PURCHASE, see targeting example
When using Dynamic Product Ads and product_audiences, see below table and targeting example

App Install state / Optimization Goals

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

App Install state / Product Audience

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

Targeting Dimensions

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

Targeting Type Support by Country

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

 {
  "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"

{
    "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"

{
  "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"

{
  "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"

{
  "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"

{
    "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"

{
  "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"

{
  "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"

{
  "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"

{
  "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"

{
    "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"

{
  "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"

{
  "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"

{
  "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"

{
    "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"

{
    "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"

{
    "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"

{
    "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"

{
    "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"

{
    "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"

{
    "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"

{
  "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"

{
  "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"

{
  "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"

{
    "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"

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"

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"

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"

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"

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}"

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"

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"

{
  "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"

{
  "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"

{
    "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

{
    "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

Normalize email addresses by trimming leading and trailing whitespace and converting all characters to lowercase before hashing
Normalize mobile advertiser id by using all lowercase. Do not remove hyphens.
Normalize phone numbers by including the country code, remove any double 0 in front of the country code, if the number itself begins with a 0 this should be removed. Also exclude any non-numeric characters such as whitespace, parentheses, ‘+’, or ‘-’.

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

Hashing Identifiers

Hash raw identifiers with lowercase hex SHA256 format.

Adding Users (Single-Key)

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"

{
  "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"

{
  "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"

{
  "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}"

{
    "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"

{
  "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

{
    "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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

{
  "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
Dimension/Granularity	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.

SKAdNetwork conversions reported at the Ad level or below may be modeled based on first party ad engagement signals using statistical methods. Modeling is only applied at the ad level. Please note that you should still take a patient approach to testing and optimization decisions including: waiting 48+ hours before adjusting Bids and Budgets, and starting with high Bids and Budgets to pass privacy thresholds. If you do not, you run the risk of prematurely pausing Ad creatives that may lead to strong performance.
The available granularities are DAY, TOTAL, and LIFETIME, HOUR granularity is not available.
The conversion window for a SKAd Network SWIPE (click) conversion is 30 day based on the time of conversion, all ad types support SWIPE conversions.
The conversion window for a SKAd Network VIEW conversion is 24 hours based on the time of conversion. A VIEW is defined as 3 seconds in length.
The ad types that currently support the VIEW conversion are; SNAP_AD, LONGFORM_VIDEO, APP_INSTALL, REMOTE_WEBPAGE, DEEP_LINK, COLLECTION
Reporting Insights are not available for SKAdNetwork metrics, the use of report_dimension is not possible.

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"

{
    "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"

{
    "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"

{
    "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"

{
    "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"

{
  "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"

{
  "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"

{
  "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"

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

This endpoint retrieves stats for the specified Ad.

HTTP Request

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

Parameters

Parameter	Default	Description
ad_id		Ad ID

Reporting Insights and Dimensions

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

Delivery Insights are estimated to protect user privacy. They are meant to provide directional guidance on audience performance.
Delivery Insights are only availble on days when there are at least 30 impressions.
Delivery Insights are only available from 1 January 2020. DAY, TOTAL, and LIFETIME granularities are supported, the HOUR granularity is not available for delivery insights. Some conversion reporting metrics are available from 1 May 2020.
Delivery insights for the combination of Country and Operating System are available from 24 October 2022 onwards.

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"

{
    "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"

{
    "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
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	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"

{
    "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

Results can be broken down by campaign, ad squad, and ad
Results can be broken down by date or total

Supported Metrics

product_impressions (number of impressions for a product ID)
swipes
spend (microcents local currency)

Report Requirements

Reports must be 1 day in length
Start & End Date must be specified

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.

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”

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"

{
  "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": ""
      }
    }
  ]
}

{
  "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 are available from the 1 April 2021
Available in all granularities (HOUR, DAY, TOTAL, LIFETIME)
Metrics cannot be broken down by Insights
Story Ads are not covered by these metrics

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"

{
    "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

{
   "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"

{
   "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"

{
   "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"

{
    "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"

{
    "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"

{
    "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"

{
    "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"

{
    "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

The advertiser will create a Lens with a target audience and a cost-per-impression bid.
When a user opens the Lens carousel, Snapchat will run a second price auction containing all the Lenses targeting that user.
The Lens that wins the auction will be inserted into the Lens section of the carousel.
If the Lens is swiped on/over by the user, then the advertiser will be billed for the impression. An advertiser will only be billed once per Lens carousel session: while a user can swipe back and forth over the Lens during the session, the advertiser will only be billed for the first swipe in the session.
If a user either posts the Lens to their story or sends the Lens in a Direct Snap, then the advertiser will not be charged for any of the resulting views.

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"

{
  "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

{
    "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

{
    "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

{
    "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

Create Lens with Deep Link 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_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

{
    "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

{
    "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

{
    "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"

{
    "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"

{
    "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"

{
    "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

{
  "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
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

{
  "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
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

{
  "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"

{
  "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"

{
  "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"

{
  "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"

{
    "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"

{
    "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"

{
    "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"

{
    "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"

{
    "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

Campaign status must be set to ‘ACTIVE’
buy_model must be set to ‘RESERVED’
objective must be set to ‘BRAND_AWARENESS’

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"

{
  "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.

Reach & Frequency Lenses and Single Image and Video ads are currently available in the Australia, Belgium, Brazil, Canada, Denmark, France, Germany, India, Ireland, Italy, Kuwait, Mexico, Netherlands, Norway, Saudi Arabia, Spain, Sweden, UAE, UK, and US.
Minimum reach of at least 500,000 unique users.
Booking / Set-Up Timing: No less than 12 hours in advance and no greater than 365 days from current time.
Radius targeting and LOI targeting are not permitted.
Customer List targeting is allowed but dependent on Customer List segments being available for forecasting.

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"

{
  "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

{
  "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

{
  "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.

Updating the AdSquad status to PAUSED
Deleting the AdSquad
Updating the Campaign status to PAUSED
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

Max # of catalogs per organization: 200
Max # of catalogs per batch: 10
Catalog name length: 1-375

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"

{
    "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

{
    "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"

{
    "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"

{
    "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"

{
    "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

"schedule": {
    "interval_type": "HOURLY",
    "timezone": "America/Los_Angeles",
    "minute": 15,
    "url": "https://example.com/product_feed.csv"
}

"schedule": {
    "interval_type": "WEEKLY",
    "timezone": "Europe/Berlin",
    "hour": 6,
    "day_of_week": "TUESDAY",
    "url": "https://example.com/product_feed.csv"
}

"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"

{
    "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

{
    "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"

{
    "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"

{
    "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"

{
    "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"

{
    "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"

{
    "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"

{
    "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.

Create a Product Feed without the schedule attribute.
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"

{
    "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


{
    "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


{
    "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

{
    "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

{
    "request_status": "SUCCESS",
    "request_id": "5ed5252800ff0e424ba54e30da0001737e616473617069736300016275696c642d36653163373061642d312d3335352d3000010115",
    "summary": {
        "total_products": {
            "count": "11",
            "relation": "EQ"
        }
    },
    "facets": [
        {
            "facet": {
                "property": "BRAND"
            },
            "values": [
                {
                    "name": "Rolo Ralph",
                    "count": "11"
                }
            ]
        }
    ]
}

Product Search

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

Example 1 - Product Search

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

{
    "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"
            }
        }
    ]
}

Example 2 - Product Search

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

{
    "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"
            }
        }
    ]
}

Example 3 - Product Search

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

{
    "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": {}
            }
        }
    ]
}

Example 4 - Product Search

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

{
    "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"
            }
        }
    ]
}

Hotel Search

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

Example 1 - Hotel Search

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

{
    "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",
            }
        },
    ]
}

Example 2 - Hotel Search

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

{
    "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",
            }
        },
    ]
}

Flight Search

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

Example 1 - Flight Search

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

{
    "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": {}
            }
        },
    ]
}

Example 2 - Flight Search

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

{
    "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

Max # of product sets per catalog: 50
Max # of product sets per batch: 50
Number of filter rules chained by a logical operator (AND, OR) per product set: 10
Product set name length: 3-255
List of Strings for all IS_ANY queries max length: 10
Any string filter value length: 1-255

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

{
    "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

{
    "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"

{
    "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"


{
    "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"


{
    "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"

{
    "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

{
    "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

{
    "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

{
    "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

{
    "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


{
    "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

{
    "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

{
    "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"

{
    "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"

{
    "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.

A fully dynamic Collection ad selects both the top snap and the creative elements dynamically based on the associated Product Set.
A partly dynamic Collection ad will have a static Top Snap Media (Video/Image), only the creative elements will be dynamically picked based on the associated product set.

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:

Creative Elements
Interaction Zone
Creative
Ad Squad
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

Deep Link attributes

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

Carousel and Slideshow Templates

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

Example 1 - Create a CAROUSEL 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": "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

{
    "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

{
    "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.

showcase_properties cannot be null
For Web_view and Deep_link interaction types, the corresponding web_view and deep_link Properties are required
The interaction_type in the creativeElement should match the interaction_type in showcase_properties
The product set ID must be the same in ad squad and the creative
Ad Squad type must be SNAP_ADS
The ad squad targeting must be set to US only
The ad squad optimization goal can be one of the following - IMPRESSIONS || SWIPES || VIDEO_VIEWS || VIDEO_VIEWS_15_SEC || PIXEL_PURCHASE || PIXEL_SIGNUP || PIXEL_PAGE_VIEW || PIXEL_ADD_TO_CART
The Ad Squad Billing Event must be IMPRESSIONS

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.

A non-dynamic Preview Creative, a non-dynamic Creative and ten Dynamic Ads that make up the story
A non-dynamic Preview Creative and a set of ten Dynamic Ads that make up the story
A dynamic Preview Creative, a non-dynamic Creative and ten Dynamic Ads that make up the story
A dynamic Preview Creative and a set of ten Dynamic Ads that make up the story

Assuming you have an existing Product feed and Product set, the order of creation from the the top of the hierarchy is the following;

Preview Creative
Static Creative (Optional)
10x Dynamic Creatives
Composite Creative
Ad Squad (including product_audiences)
Ad (Story type)

Product Feed - Interaction support

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

preview_media_id - The id of the Preview Media image used in the Discover Feed tab of Snapchat
logo_media_id - The id of the Logo Media Image which is overlaid on top of the Preview Media

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

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"
            }
        }
    ]
}

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 preview_creative_id attribute holds information about the Preview Creative.
The creative_ids attribute within composite_properties holds information about the Dynamic Creatives.
The creative_ids is an array which can consist of 1 non-Dynamic Creative and 10 Dynamic Creatives or just 10 Dynamic Creatives
If you use the combination of 1 non-Dynamic + 10 Dynamic Creatives, the non-dynamic Creative needs to be of one of the types APP_INSTALL, WEB_VIEW or DEEP_LINK.

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

"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

Legal Disclosure Properties

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

FIRST_NAME and LAST_NAME fields must be included
At least one of the EMAIL field or the PHONE_NUMBER field must be included.
The ADDRESS and POSTAL_CODE fields cannot both be included in the same form.

How to create a Lead Generation Ad

Creating a Lead Generation Ad consists of the following steps:

Create a header banner image for your form. (Only required if the form contains a banner header)
Create a Lead Generation Form creative.
Use the creative created in step 2 to create a Lead Generation ad.

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

{
    "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

{
    "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

{
    "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

If you are building a Web based tool using a UI where several users will log in to fetch data via the API it might make sense to make the redirect URL part of your application, and let the application fetch and read the GET parameter and then automatically proceed to the next step where the Application generates an access and refresh token for the user.
If you are building a “server to server” application, then you could specify any URL you control and that can display a GET parameter so that you may manually copy and save the code parameter from the URL and then execute the next step manually, using software such as POSTMAN.

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*

The user account which you are logged into needs to be an Organization admin
The URL where the Oauth App Dashboard can be found on the following URL where YOUR_ORGANIZATION_ID needs to be replaced with your Organization ID: https://business.snapchat.com/YOUR_ORGANIZATION_ID/settings/business-details

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.

You will need to set up a new Snapchat account for this purpose
You will need to log in with a user that has the Organisation Admin role at https://business.snapchat.com
- That user will be able to invite the new Snapchat account to the Organization and assign an appropriate Role based on the actions you want to carry out via the Snap Ads API, Roles and Permissions
Note that if you use the Organisation Admin role for the new Snapchat account this role comes with powerful permissions as it can Create/Edit/Delete entities in any of the Ad accounts under the org.

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.

Navigate to this URL in a browser https://accounts.snapchat.com
Log in as the user that granted access to the OAuth App in question
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
The page will show you a list of all Applications that has been authorised to use your Ads API permissions on your behalf.
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:

The user/token making the request does not have permission to access the resource.
The entity requested in the request doesn’t exist, this means either the entity was deleted or the entity ID hasn’t been entered correctly.

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

If you can request the Audit logs successfully for the entity you will be able to see the actions taken on this entity, if the entity has been deleted then the final action on the entity will be; "action": "DELETED"
If the Audit log request was successful, but all you get is an empty array, there is a possibility that the entity was deleted before audit logs were made available.
If the Audit log request was rejected with a “error_code”: “E3002” response it means you do not have permissions 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"
}

If the Audit log request was rejected with a “error_code”: “E3003” response it means the entity ID is incorrect, in other words there has never been an entity with that 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?

The user in question needs to be a Member of the Organization where the Ad Account lives, this also means they have to accept the invitation which is sent to the Member email
The user also needs to be a Member of the Ad Account
The user also needs to have the Role type reports in the 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

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-03-21	Announcement for Conversions API v3 and links to new docs site
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"

{
    "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

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

New `bid_strategy` attribute replaces `auto_bid` and `target_bid`

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

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

Deprecation of `placement` in favour of `placement_v2`

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

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