[go: up one dir, main page]
NAV Navbar

Conversions API

cURL

Introduction

Welcome to the Snapchat Marketing API!

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

Conversions API Version 2

The documentation below is for version 2 of Snapchat’s Conversions API.

For our latest Conversions API, Version 3, please see https://docs.snap.com/api/marketing-api/Conversions-API.

V2 Endpoint V3 Endpoint
//tr.snapchat.com/v2/conversion //tr.snapchat.com/v3/{ID}/events

Conversions API V2

The Snapchat Conversions API allows you to pass web, app, and offline events to Snap via a Server-to-Server (S2S) integration. Similar to our other integrations, Snap Pixel and App Ads Kit SDK (AAK), by passing these events, you can access post-view and post-swipe campaign reporting to measure performance and incrementality. Depending on the data shared and timeliness of integration, it’s also possible to leverage events passed via Conversions API for solutions such as custom audience targeting, campaign optimization, Dynamic Ads, and more.

Note that events can have a date (timestamp) of maximum 37 days back to be eligible to be reported via the Conversions API.

Snap also has partnerships with 3rd party partners, who may already be integrated with the Conversions API. Please reach out to us if there are new partners we should integrate with.

Announcements

✨ Conversions API Version 3 ✨

The new Conversions API V3 is now live.

New Version 3 Endpoint: //tr.snapchat.com/v3/{ID}/events

Business SDK

The Business SDK is an SDK that facilitates requests and authentication processes with CAPI as if they were local functions of the supported languages. This will largely simplify the integration for you as we bundle the dedicated CAPI client, hashing libraries, and code examples into one SDK that is available in multiple languages.

This should be your first step before beginning the CAPI installation process. We highly recommend using Business SDK if you are starting a new CAPI integration.

We currently support the following languages: Go, Java, PHP, Python and Ruby.

Conversions API Video Tutorial

We have created a video tutorial for developers that are getting started with the Snapchat Conversions API. We recommend watching this video as a first step before working with the API.

You can find the tutorial on the Business Help Center.

Auth requirements

As of May 2022,

If you are an advertiser integrating with the API for your organization you can use static long lived token. This method of Auth does not need the 3 legged OAuth flow, and it does not expire. These tokens are generated in Business Manager and can be created and managed in the UI directly.

If you are a 3rd party, integrating with the Conversions API to be used by our mutual customers please use the OAuth flow for Conversions API.

Static Long Lived Tokens

  1. First log into Business Manager and navigate to the Business Details page.

  2. Once on this page, under the OAuth Apps section, you will now see a new section called the Conversions API Tokens. Here you can click on the Generate Token button to generate a new token. Please note that you must be a Organization Admin to view this section of the page. Conversions API Token

  3. You can then copy the token and use it the same way as you would use the OAuth token by including this token in the header eg. - “Authorization: Bearer << Newly generated Conversions API token >>”“

  4. You may generate multiple tokens and can also delete these tokens to invalidate them. These tokenAds do not expire and you do not need to refresh access.

  5. You may make as many requests as needed. f you are using a Long Lived Token, we recommend a 1000 QPS limit for sending us requests. You may send up to 2000 events per batch request, and can thus send up to 2M events/sec.

  6. You can only send events for the pixel and app IDs that belong to the Org where the token has been generated. For example: If your token belongs to Org1 and Pixel ID to Org2. Any API requests using this token from Org1 for the pixel ID from Org2 will fail.

OAuth for Conversions API

This authorization flow works similar to the rest of the APIs, with one major difference. This API requires a different OAuth scope - "snapchat-offline-conversions-api”
Please refer to the Authorization section of this doc for more details.

Please note that the standard API Rate Limits of 10 req/sec apply. You may send up to 2,000 events per batch request and can thus send up to 20,000 req/sec.

Conversions API Concepts

Below are important Conversions API concepts to read through before beginning you integration.

Data Hygiene

In the following sections, we’ll reference a few terms we’ll define now, such as normalizing and hashing identifiers.

How to Normalize Identifiers

How to Hash Identifiers

Example for Phone numbers

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

Additional Data Formatting Guidelines

Event Time: Provide the UNIX timestamp, calculated in seconds or milliseconds, of the conversion event. UNIX timestamp allows us to reach consensus on a moment of time, regardless of what timezone. For example, if it is currently October 08, 2021 3:18 PM UTC, this translates to “1633684680” in seconds or “1633684680000” in milliseconds. If your event time is a UNIX timestamp in milliseconds format (13 digits), please keep it as is and send it to us as milliseconds, we encourage and recommend sending us timestamp in milliseconds.

Conversion Parameters

Important: See Parameters Best Practices for which parameters are essential for getting a user match.

Attribute Description Possible Value
pixel_id The Pixel ID for the Ad Account in question. Required for web and offline events. Example: f5932083-b4da-436e-b63c-94b659dde332
app_id The unique ID (app_id) assigned for a given application. It should be numeric for iOS, and the human interpretable string (example: com.snapchat.android) for Android. Required for app events.
Set Up and Manage Your Snap App ID		 Example: The app_id for Snapchat is 447188370 (iOS) and com.snapchat.android (Android)
snap_app_id The Snap App ID associated with your app (a unique code generated in Ads Manager and included in your MMP dashboard). Required for app events. Example: 07b517bb-9cdb-42ef-ba77-9dd9a9eb2dc1
event_type Event type required for all web, app, and offline events. PURCHASE, SAVE, START_CHECKOUT, ADD_CART, VIEW_CONTENT, ADD_BILLING, SIGN_UP, SEARCH, PAGE_VIEW, SUBSCRIBE, AD_CLICK, AD_VIEW, COMPLETE_TUTORIAL, LEVEL_COMPLETE, INVITE, LOGIN, SHARE, RESERVE, ACHIEVEMENT_UNLOCKED, ADD_TO_WISHLIST, SPENT_CREDITS, RATE, START_TRIAL, LIST_VIEW, APP_INSTALL, APP_OPEN, CUSTOM_EVENT_1, CUSTOM_EVENT_2, CUSTOM_EVENT_3, CUSTOM_EVENT_4, CUSTOM_EVENT_5
event_conversion_type Where the event took place. Required for all web, app, and offline events. Use the appropriate value accordingly. OFFLINE, WEB, MOBILE_APP
event_tag Custom event set label. Not currently surfaced in measurement or audience generation, but may become usable in the future. Examples: in-store, weekend sales, back-to-school campaign
timestamp The Epoch timestamp for the conversion happening. We can handle second level or millisecond level granularity. However, we do encourage requests to provide millisecond level granularity. Required for all web, app, and offline events. Please note: Please note: The timestamp cannot be more than 37 days in the past Example: 1633684680
hashed_email Lowercase SHA256 hash of normalized email. Highly recommended for all web, app, and offline events when available. Example:
Before: Person@Example.com
Change to lower case: person@example.com
After hashing:
542d240129883c019e106e3b1b2d3f3cb3537c43c425364de8e951d5a3083345
hashed_mobile_ad_id Lowercase SHA256 hash of normalized MAID (IDFA or AAID). Recommended for all app events when available. Example:
Mobile ad id: 402DA762-201E-42C1-961B-C1fA6CBCF566
Change to lower case: 402da762-201e-42c1-961b-c1fa6cbcf566
Before hashing: 402da762-201e-42c1-961b-c1fa6cbcf566
After hashing:
b0f80a7d2c969156849f3cc97094c0fcbc2691692ef8c9feb8cda6a0a0b74a35
hashed_idfv Lowercase SHA256 hash of normalized IDFV. Highly recommended for app events. Example:
Upper case C305F2DB-56FC-404F-B6C1-BC52E0B680D8
Lowercase c305f2db-56fc-404f-b6c1-bc52e0b680d8
After SHA-256 hash f18c8b858e52b0c49f7db8f813538db0ecdc513357efd62c525784a9beb617d6
hashed_phone_number Lowercase SHA256 hash of normalized phone number. Highly recommended for all web, app, and offline events when available. Example:
Before normalisation +44 844 412 4653
After normalisation 448444124653
After SHA-256 hash: dc008fda46e2e64002cf2f82a4906236282d431c4f75e5b60bfe79fc48546383
user_agent User agent of the device that was used. Recommended for all web and app events when available. Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0
hashed_ip_address SHA256 hash of the IP Address of the device (not server). We support both IPv4 and IPv6 for both web and app. Recommended for all web and app events when available. Example;
104.124.214.254
After SHA-256 hash: 4d8c26c5d5502d0a1731905e362d0ba908ee2b66110b2a3b7e61d24961f18e0e
item_category Item or Category. Can be single category or an array. Example:
"shoes"
or ["coats, Shoes, umbrellas"]
item_ids International Article Number (EAN) when applicable, or other product or category identifier. This can be a single item ID, an array, or a list of item IDs to be separated by “,” or “;” Examples:
"sku001"
or "sku001,sku002,sku003"
or "sku001;sku002;sku003"
or ["sku001;sku002;sku003"]
description A string description for additional info This is a free form text description with no specific format. Note: max 1024 characters
number_items Number of items Examples: "1", "1,2,3", "1;2;3"
price Value of the purchase. We allow list of prices to be separated with “,” or “;” 123,145,500 etc.
Note: If a list is provided we will total up the prices server side
currency Standard ISO 4217 code Supported currencies:
USD, AED, AUD, BGN, BRL, CAD, CHF, CLP, CNY, COP,CZK, DKK, EGP, EUR, GBP, GIP, HKD, HRK, HUF, IDR, ILS, INR, JPY, KRW, KWD, KZT, LBP, MXN, MYR, NGN, NOK, NZD, PEN, PHP, PKR, PLN, QAR,RON, RUB, SAR, SEK, SGD, THB, TRY, TWD, TZS, UAH, VND, ZAR, ALL, BHD, DZD, GHS, IQD, ISK, JOD, KES, MAD, OMR, XOF
transaction_id Transaction ID or order ID tied to the conversion event. This is an important field to include for deduplication
level Represents a level in the context of a game
client_dedup_id If you are reporting events via more than one method (Snap Pixel, App Ads Kit , Conversions API) you should use the same client_dedup_id across all methods, this will be used within a 48 hour scope of the first occurrence.
search_string The text that was searched for Example:
shoes
umbrellas
coats
page_url The URL of the web page where the event took place. Must include protocol (eg http, https) Example: https://www.example.com/purchase
sign_up_method A string indicating the sign up method. Example:
Email
Twitter etc
att_status Used to indicate an OPT_IN or OPT_OUT for MOBILE_APP events. For users of iOS 14.5 and above, please set this parameter to the user’s ATT Authorization Status. For all other iOS users, please set this to AUTHORIZED. AUTHORIZED, DENIED, RESTRICTED, NOT_DETERMINED
data_use Used to indicate an OPT_IN or OPT_OUT for WEB events. For users of iOS 14.5 and above that are OPT_OUT, set this parameter’s value to a list that has a single element of the value lmu. Otherwise, do not set this parameter. ['lmu']
device_model The user’s device model. iPhone12Pro, iPhone11ProMax, GalaxyS20Ultra5G
os_version The user’s OS version. 14.4.1, 15.6, 12
click_id The ID value stored in the landing page URL’s &ScCid= query parameter. Using this ID improves ad measurement performance. We also encourage advertisers who are using click_id to pass the full url in the page_url field. For more details, please refer to Sending a Click ID 7b3a7917-a82a-47e8-9728-e1b3b045abb2
uuid_c1 If you are using the Pixel SDK, you can access a 1st party cookie by looking at the _scid value under your domain. We highly recommend you pass this, as doing so will increase your user match rate. Example: 57cf8a96-99ff-4260-a6b0-219820d2860e
advertiser_cookie_1 If you are not using the Pixel SDK and have your own cookie, you can send your cookie ID in this field to help improve match rates. This field is used as an alternative to uuid_c1. Refer to Sending a Click ID for more details. 57cf8a96-99ff-4260-a6b0-219820d2860e
brands Brands associated with the item_ids in the conversion event. This parameter’s value should be formatted as a list of strings. ["brand1", "brand2"]
delivery_method Indicates the delivery method of the order. Please set to either in_store, curbside, or delivery in_store, curbside, delivery
customer_status Indicates the registration status of the customer. Suggested values to pass include new, returning, or reactivated new, returning, activated
hashed_first_name_sha First name hashed in SHA256 format. Please use only one of hashed_first_name_sha or hashed_first_name_sdx a8cfcd74832004951b4408cdb0a5dbcd8c7e52d43f7fe244bf720582e05241da
hashed_first_name_sdx Soundex representation of the converted user’s first name. Please use only one of hashed_first_name_sha or hashed_first_name_sdx. J500
hashed_middle_name_sha Middle name hashed in SHA256 format. Please use only one of hashed_middle_name_sha or hashed_middle_name_sdx. d93006ec2e4339d770a7afd068c1f1e789a52df12f595e529fd0f302fc1e5ec7
hashed_middle_name_sdx Soundex representation of the converted user’s middle name. Please use only one of hashed_middle_name_sha or hashed_middle_name_sdx. M340
hashed_last_name_sha Last name hashed in SHA256 format. Please use only one of hashed_last_name_sha or hashed_last_name_sdx. fd53ef835b15485572a6e82cf470dcb41fd218ae5751ab7531c956a2a6bcd3c7
hashed_last_name_sdx Soundex representation of the converted user’s middle name. Please use only one of hashed_last_name_sha or hashed_last_name_sdx. D000
hashed_city_sha City associated with the conversion hashed in SHA256 format. This can come from a shipping or billing address. Please use only one of hashed_city_sha or hashed_city_sdx. ced2e77f732fbf327f53e1f9748078c778b190ed9cf376a7df469a92d2ad62d3
hashed_city_sdx Soundex representation of the city associated with the conversion. Please use only one of hashed_city_sha or hashed_city_sdx. S535
hashed_state_sha State or region associated with the conversion hashed in SHA256 format. This can come from a shipping or billing address. Please use only one of hashed_state_sha or hashed_state_sdx. 4b650e5c4785025dee7bd65e3c5c527356717d7a1c0bfef5b4ada8ca1e9cbe17
hashed_state_sdx Soundex representation of the State or region associated with the conversion. Please use only one of hashed_state_sha or hashed_state_sdx. C416
hashed_zip Zip or postal code associated with the conversion hashed in SHA256 format. This can come from a shipping or billing address. e222c384dd83ac669bcd1da281ffea2e60bab298f8c0673d35bc0b704e345282
hashed_dob_month Birth month of the converted user. Must be hashed using SHA256 format. 37082e68df858e0ba76442174128811135890ae4c2c5df8b6f31aef5885d0be7
hashed_dob_day Day of the month that the converted user was born. Must be hashed using SHA256 format. 5f9c4ab08cac7457e9111a30e4664920607ea2c115a1433d7be98e97e64244ca
country Country associated with the conversion. Must be provided as a two letter ISO 3166 alpha-2 country code. US, GB, JP
region State or region associated with the conversion. If the country is US, provide a two letter State code (CA, WA), otherwise provide the full region name. CA, WA
partner_id Unique identifier provided by a partner, allowlist only.

Parameters Best Practices

Required Parameters

At least one of the following parameters is required in order to successfully pass data via the Conversions API.

Sending a request without one of these parameters will result in an error. When possible, we recommend passing all of the above parameters to improve performance.

Recommended Parameters

We also highly recommend passing the following parameters, if available, as this will increase your match rate. Please keep in mind that these parameters must be sent in addition to one of the required parameters above, otherwise an error will occur.

In addition to one of the above parameters, we now also recommend passing one or a combination of the below parameters to help improve match rates. In order to pass these to us, we recommend using the Pixel SDK or Business SDK. This data will be passed to us in plaintext and hashed via the SDK.

For the best performance, you should always send additional parameters if they are available.

Validate a Conversion event

This endpoint validates if a conversion event is constructed properly

POST https://tr.snapchat.com/v2/conversion/validate

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{
    "pixel_id": "67d34640-b7a4-42a8-b821-6434d70f08a4",
    "timestamp": "1642815764",
    "event_conversion_type": "OFFLINE",
    "event_type": "PURCHASE",
    "event_tag": "offline",
    "page_url": "https://www.example.com",
    "price": "43",
    "hashed_email" : "8c2a47d3bdb8d3096a6479f53eac3b724291db5f1c31611100f675be5537329d"
}' \
  https://tr.snapchat.com/v2/conversion/validate

The above command returns JSON structured like this:

{    
    "status": "SUCCESS",
    "reason":"All records processed"
}

Create a Conversion event

This endpoint creates a conversion event and posts it to Snap

POST https://tr.snapchat.com/v2/conversion

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{
    "pixel_id": "67d34640-b7a4-42a8-b821-6434d70f08a4",
    "timestamp": "1642815764",
    "event_conversion_type": "OFFLINE",
    "event_type": "PURCHASE",
    "event_tag": "offline",
    "page_url": "https://www.example.com",
    "price": "43",
    "hashed_email" : "8c2a47d3bdb8d3096a6479f53eac3b724291db5f1c31611100f675be5537329d"
}' \
  https://tr.snapchat.com/v2/conversion

The above command returns JSON structured like this:

{    
    "status": "SUCCESS",
    "reason":"All records processed"
}

Test Event Tools

The Conversions API provides Test Event Tool endpoints that allow advertisers to send test events and validate them. Advertisers can verify that their events were constructed properly and have successfully reached our servers in near real-time without sending actual production events. The Test Event Tools endpoints are as follows:

All of the Test Event Tool endpoints support OAuth access tokens for authorization. They can also accept the long-lived access token as long as the given pixel or app is owned by the organization that generated the long-lived token

In addition to viewing your test event data using these API endpoints, you can also view your test events in the Events Manager. For more information, please refer to the Validating with Event Testing article on our Business Help Center.

Sending a Test Event

HTTP Request

POST https://tr.snapchat.com/v2/conversion/validate

This endpoint is used to send test events that do not get counted as production data. Test event data can be viewed using the other Test Event Tool endpoints.

Response Fields

Field Description
validated_fields List of fields that were successfully validated by the test tool.
warning_records List of warnings that indicate potential issues with the event and its parameters.
error_records List of problems that would prevent Snap from processing the event if it were sent was a production event.

Successful Requests

If a request is valid, its response will contain the fields that were sent so that you can confirm that the event data was received correctly.

Successful Request

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{
    "pixel_id": "67d34640-b7a4-42a8-b821-6434d70f08a4",
    "timestamp": "1642815764",
    "event_conversion_type": "OFFLINE",
    "event_type": "PURCHASE",
    "event_tag": "offline",
    "page_url": "https://www.example.com",
    "price": "43",
    "hashed_email" : "8c2a47d3bdb8d3096a6479f53eac3b724291db5f1c31611100f675be5537329d"
}' \
  https://tr.snapchat.com/v2/conversion/validate

Successful Response

{
    "status": "SUCCESS",
    "reason": "All records processed",
    "validated_fields": [
        {
            "validated_fields": {
                "pixel_id": "67d34640-b7a4-42a8-b821-6434d70f08a4",
                "price": "43.0",
                "event_conversion_type": "OFFLINE",
                "event_type": "PURCHASE"
            },
            "record_index": 1
        }
    ]
}

Success with Warnings

Test event requests that are valid but have potential problems will contain warnings in the response. The warnings represent issues that might interfere with the processing of the request.

Successful request that generates warnings

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{
    "pixel_id": "67d34640-b7a4-42a8-b821-6434d70f08a4",
    "timestamp": "1642815764",
    "event_conversion_type": "OFFLINE",
    "event_type": "PURCHASE",
    "event_tag": "offline",
    "page_url": "https://www.example.com",
    "currency": "not a real currency",
    "price": "43",
    "hashed_email" : "8c2a47d3bdb8d3096a6479f53eac3b724291db5f1c31611100f675be5537329d"
}' \
  https://tr.snapchat.com/v2/conversion/validate

Successful response with warnings

{
    "status": "SUCCESS",
    "reason": "All records processed",
    "warning_records": [
        {
            "reason": "Unrecognized or unsupported currency",
            "record_indexes": [
                1
            ]
        }
    ],
    "validated_fields": [
        {
            "validated_fields": {
                "pixel_id": "67d34640-b7a4-42a8-b821-6434d70f08a4",
                "price": "43.0",
                "event_conversion_type": "OFFLINE",
                "event_type": "PURCHASE"
            },
            "record_index": 1
        }
    ]
}

Failed Requests

A Test Event that receives a failure response would not be accepted by the Conversions API if it were sent as a real production event. Validated fields will not appear in the response and errors will be shown. Non-fatal warning messages may also appear in addition to these errors based on the validity and quality of the data provided.

Request that will fail

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{
    "pixel_id": "67d34640-b7a4-42a8-b821-6434d70f08a4",
    "timestamp": "0",
    "event_conversion_type": "OFFLINE",
    "event_type": "not a real event type",
    "event_tag": "offline",
    "page_url": "https://www.example.com",
    "price": "43",
    "hashed_email" : "8c2a47d3bdb8d3096a6479f53eac3b724291db5f1c31611100f675be5537329d"
}' \
  https://tr.snapchat.com/v2/conversion/validate

Failure response

{
    "status": "FAILED",
    "reason": "All records failed",
    "error_records": [
        {
            "reason": "Timestamp is invalid",
            "record_indexes": [
                1
            ]
        },
        {
            "reason": "Unrecognized event type",
            "record_indexes": [
                1
            ]
        }
    ],
    "warning_records": []
}

Viewing Test Event Logs

HTTP Request

GET https://tr.snapchat.com/v2/conversion/validate/logs?asset_id={{pixel_id or snap_app_id}}

This endpoint is used to view logs for test events that were sent for a given pixel or app in the last 24 hours. If no test events were found for the requested Pixel ID or Snap App ID, a “No logs found.” message will be returned in the response.

Note that the outermost timestamp field reflects the millisecond UTC timestamp of server receipt but the timestamp within each event’s metadata reflects the timestamp that was sent by the advertiser in the request body. Failed requests will not include event metadata and have a status of INVALID

Response Fields

Field Description
logs List of logs for events sent for the given Pixel or App in the past 24 hours.

Log Fields

Field Description
timestamp Timestamp when the request was received by Snap.
status Shows if request was valid. Can be VALID, INVALID, or VALID_WITH_WARNINGS.
integration Indicates if the test request was sent directly to Snap or through a third party integration.
warning_records List of warnings flagging potential issues with the request.
error_records List of problems that prevent Snap from processing the event.
event_metadata List of metadata that was sent with the event.

Example Request

curl -X GET -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
https://tr.snapchat.com/v2/conversion/validate/logs?asset_id=67d34640-b7a4-42a8-b821-6434d70f08a4' \
  https://tr.snapchat.com/v2/conversion/validate

Example Response

{
    "status": "SUCCESS",
    "reason": "Logs for asset id processed.",
    "logs": [
        {
            "timestamp": "1662068356738",
            "status": "INVALID",
            "integration": "DIRECT",
            "warning_records": [
                "Unrecognized or unsupported currency"
            ],
            "error_records": [
                "Timestamp is invalid",
                "Unrecognized event type"
            ]
        },
        {
            "timestamp": "1661179000000",
            "event_type": "PURCHASE",
            "event_conversion_type": "OFFLINE",
            "status": "VALID_WITH_WARNINGS",
            "integration": "DIRECT",
            "event_metadata": {
                "pixel_id": "67d34640-b7a4-42a8-b821-6434d70f08a4",
                "page_url": "https://www.example.com",
                "hashed_email": "8c2a47d3bdb8d3096a6479f53eac3b724291db5f1c31611100f675be5537329d",
                "event_type": "PURCHASE",
                "event_conversion_type": "OFFLINE",
                "event_tag": "offline",
                "timestamp": "1661179000",
                "price": "43",
                "currency": "AAA",
                "data_use": "[]"
            },
            "warning_records": [
                "Unrecognized or unsupported currency"
            ]
        },

        {
            "timestamp": "1659042175000",
            "event_type": "PURCHASE",
            "event_conversion_type": "OFFLINE",
            "status": "VALID",
            "integration": "DIRECT",
            "event_metadata": {
                "pixel_id": "67d34640-b7a4-42a8-b821-6434d70f08a4",
                "page_url": "https://www.example.com",
                "hashed_email": "8c2a47d3bdb8d3096a6479f53eac3b724291db5f1c31611100f675be5537329d",
                "event_type": "PURCHASE",
                "event_conversion_type": "OFFLINE",
                "event_tag": "offline",
                "timestamp": "1659042175",
                "price": "43",
                "data_use": "[]"
            }
        }
    ]
}

Viewing Stats for Test Events

HTTP Request

GET https://tr.snapchat.com/v2/conversion/validate/stats?asset_id={{pixel_id or snap_app_id}}

This endpoint is used to view the number of test events that were received for the specified Pixel ID or App within the past hour and the timestamp of the last test event that the Conversions API received within the past 24 hours. If no data is available for either metric, the value will be 0.

Example Request

curl -X GET -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
https://tr.snapchat.com/v2/conversion/validate/stats?asset_id=67d34640-b7a4-42a8-b821-6434d70f08a4

Response Fields

Field Description
latest_event_ts Timestamp of last test event that the Conversions API received within the past 24 hours. This timestamp indicates the time that the Conversions API received the event.
event_count_past_hour Number of test events received within the past hour.

Example Response

{
    "status": "SUCCESS",
    "reason": "Stats for asset id processed.",
    "stats": {
        "test": {
            "latest_event_ts": 1662068356738,
            "event_count_past_hour": 7
        }
    }
}

Using the API

Conversions API requests are tied to Unique Identifiers that link the server events back to your Snapchat ad account. We use your Pixel ID for web and offline events, and your Snapchat App ID for app events.

We highly recommend passing data in real time. To unlock campaign optimization, we recommend you send events as soon as they occur and ideally within an hour of the event occurring.

Deduplication

Request Body

{
   "pixel_id":"783c04c9-cd00-485a-ab54-02f0832dfc24",
   "timestamp":"1645723911000",
   "event_type":"VIEW_CONTENT",
   "event_conversion_type":"WEB",
   "page_url":"https://www.example.com/tunneling",
   "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.0.5 Safari/605.1.15",
   "hashed_ip_address":"1150a143ae46d77bca2f9f4429f8c65d4d746edc37b769b044659b820493d0db",
   "client_dedup_id": "6V5xX1T0n9pC42luElKD",
}

Request Body - Purchase Event

{
   "pixel_id":"783c04c9-cd00-485a-ab54-02f0832dfc24",
   "timestamp":"1645723911000",
   "event_type":"VIEW_CONTENT",
   "event_conversion_type":"WEB",
   "page_url":"https://www.example.com/tunneling",
   "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.0.5 Safari/605.1.15",
   "hashed_ip_address":"1150a143ae46d77bca2f9f4429f8c65d4d746edc37b769b044659b820493d0db",
   "client_dedup_id": "6V5xX1T0n9pC42luElKD",
   "transaction_id": "ghFDxpY55VYx0SgtU5o2"
}

There are many ways to send conversion values to Snap. Our systems support receiving redundant data; however, we recommend reviewing the following guidelines to ensure accurate reporting, and that events are only attributed once. Regardless of your use case, please always ensure timestamps are accurate.

To help with identifying duplicate events there are 2 parameters we recommend sending to CAPI. These values can be created at time of event, but should match for all calls via Snap Pixel, third party, or direct CAPI calls.

Example - Using a timestamp and random number

const date = Date.now();
const client_dedup_id = Math.round(date * (Math.random() * 1));

UUID

Another easy way to get a unique ID generated is to use an uuid, like uuidv4 available via npm. There are also UUID classes available in Java and Python

Unique for every unique event

Remember, client_dedup_id can be any string, as long as it is unique for every event, and the same id is used for every event tracker (Pixel, CAPI, MMP, etc.).

Grouping Events & API Rate Limits

Opt-outs

Snap supports different ways to indicate a user’s consent status, depending on the event’s event_conversion_type.

MOBILE_APP Events

When reporting events triggered by users on iOS 14.5 and above, we highly recommend you leverage the ‘att_status’ parameter to ensure the event is processed according to your user’s ATT status. This can be obtained from your iOS application code using the App Tracking Transparency framework.

WEB Events

For WEB events, you can mark an event as an opt out event by setting the data_use parameter to a list that contains a single value of “lmu”.

Please note that the att_status parameter did not exist in the past and opt out events were indicated using the data_use parameter for all event conversion types. If your implementation is like this, we recommend updating it to use the att_status parameter to report MOBILE_APP opt out events as a best practice. However, for backward compatibility, you will still be allowed to report MOBILE_APP opt outs using the data_use parameter.

ATT Opt Out for Web Events

{
    ...

    "data_use": "['lmu']",

    ...
}

Sending a Click ID

When a user clicks or swipes up on a Snapchat ad, the query parameter, &ScCid= is appended to the outgoing URL. This parameter’s value is known as the Click ID. Sending this value in a Conversions API event can improve measurement performance. There are two ways send this value in an event:

Supplemental parameters

When sending the click ID, we also highly recommend including the uuid_c1 or advertiser_cookie_1 parameters as follows.

Including the uuid_c1 or advertiser_cookie_1 parameter allows us to associate a user’s actions to a click_id even after they have navigated away from the initial landing page. Although optional, including one of these parameters can significantly improve matching performance.

Click ID Example Scenario

Take the following example scenario:

You can record a PAGE_VIEW event with a Click ID for this user by sending the payload in the right column. Note that we have also sent the _scid cookie value in the uuid_c1 parameter.

Sending Click ID in an event payload

{
    "pixel_id": "5be1069f-8a96-444c-9e3f-37e25ca2d27d",
    "event_type": "PAGE_VIEW",
    "click_id": "7b3a7917-a82a-47e8-9728-e1b3b045abb2",
    "page_url": "http://www.mywebsite.com/?utm_source=snapchat&utm_media=social&utm_campaign=my_campaign&ScCid=7b3a7917-a82a-47e8-9728-e1b3b045abb2",
    "uuid_c1": "bf9f9606-b8a3-4643-8f58-1d613a3539d8" 
    ...
}

Testing and Monitoring Events

Please refer to the Events manager guide to learn how to test and monitor events. Also, please refer to the Conversion API FAQ if you have any questions.

Errors

Error Code Error Message
001 Invalid access token
002 Request data is too large
003 Failed to parse request body
004 Invalid offline event set ID
005 All records failed
006 Some records could not be processed
101 Cannot determine request type. Check the app_id and pixel_id parameters
102 Timestamp is invalid
103 Unrecognized event type
104 Unrecognized event conversion type
105 Invalid value for payment_info_available. Must be 1 or 0
106 Invalid value for success. Must be 1 or 0
107 Invalid value for limit_ad_tracking. Must be 1 or 0
108 Invalid pixel request, pixel_id and snap_app_id in the same record
109 hashed_ip_address hash value is invalid
110 hashed_email hash value is invalid
111 hashed_phone_number hash value is invalid
112 hashed_mobile_ad_id hash value is invalid
201 Missing event type
202 Missing event conversion type
203 Missing timestamp parameter
204 Incoming pixel requests must have at least one valid hashed user identification parameter to perform the match
205 Incoming appinstall requests must have hashed_mobile_ad_id to perform the match
206 Missing event tag parameter
207 Missing Snap App ID. Please reach out to your Snap rep to setup a Snap App ID
301 Failed to process event
901 Unable to construct event
902 No valid header
903 No valid values found
904 Unable to construct event
000 Unknown error

Pixel ID or Snap App ID

Depending on the type of events you will be reporting to Snap, you will need to set up and use either a Pixel ID or a Snap App ID. The ID you use for your events also decides the parameters you should be passing when you send events.

This table outlines the parameters you should be passing with your events.

Property ID Description
Website pixel_id Events taking place on a web property. If you are passing the same events via a Pixel on your website, you should use the pixel_id to ensure all events are entering the same pipeline for deduplication.
Mobile App snap_app_id Events taking place within an App
Offline pixel_id Measure events that take place in-store, over the phone or online (but are not pixelable).

Sending your first event

These are examples of how you should structure a basic Conversion API request. Note the differences between the first request which uses the Pixel ID and the second request which uses a Snap App ID.

Snap Pixel - Pixel ID

Request URL: https://tr.snapchat.com/v2/conversion

Request Body:

{
   "pixel_id":"783c04c9-cd00-485a-ab54-02f0832dfc24",
   "timestamp":"1645723911000",
   "event_type":"VIEW_CONTENT",
   "event_conversion_type":"WEB",
   "event_tag": "badger_tunneling",
   "page_url":"https://www.example.com/tunneling",
   "hashed_email":"20e468ca5f7903e80fe3aa79ac3b8f1436f99163a9802b55891f38be95b7959e",
   "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.0.5 Safari/605.1.15",
   "hashed_ip_address":"1150a143ae46d77bca2f9f4429f8c65d4d746edc37b769b044659b820493d0db"
}

Mobile App - Snap App ID

Request URL https://tr.snapchat.com/v2/conversion

Request Body:

{
   "snap_app_id":"fb5b83ec-c593-4a64-9c6d-a0eb9da0edba",
   "app_id":"447188370",
   "timestamp":"1636574053",
   "event_type":"PAGE_VIEW",
   "event_conversion_type":"MOBILE_APP",
   "event_tag": "instore",
   "hashed_mobile_ad_id":"9ec84f2eddcff338084a8c51808a45034c9286dc427a4cb01b8688b7b823be28",
   "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/13.0.5 Safari/605.1.15",
   "hashed_ip_address":"1150a143ae46d77bca2f9f4429f8c65d4d746edc37b769b044659b820493d0db"
}

Expected Response

The API should return a 200 OK Response Status and should have a request body that is similar to the one in the right column.

{
   "status": "SUCCESS",
   "reason": "All records processed"
}

Advanced Conversions

In order to optimize Advanced Conversions, we recommend you pass eligible events triggered by all users to Snap. You should indicate if an event was triggered by an ATT Opt Out user by using the Limited Data Use parameter data_use with the value ['lmu']

Example:

{
   "snap_app_id":"fb5b83ec-c593-4a64-9c6d-a0eb9da0edba",
   "app_id":"447188370",
   "timestamp":"1636574053",
   "event_type":"PURCHASE",
   "event_conversion_type":"MOBILE_APP",
   "event_tag": "in_game_purchase",
   "hashed_mobile_ad_id":"5ec54f2eddcff338084a8c51808a45034c9216dc427a4cb01b8688b7b823be28",
   "data_use":"['lmu']"
}

Parameters for Event Type/Platform

In addition to required parameters in Parameters Best Practices, below is a list of additional parameters you should pass with each event (WEB, MOBILE_APP, OFFLINE). For the best performance, you should always send the additional parameters if they are available.

WEB Parameters

The state of a user logged in/not logged in to your web property is likely to determine what parameters can be sent. A logged in user may often have the email/phone number available.

Event Required Parameters For Full Functionality
PURCHASE pixel_id, page_url, item_category, item_ids, number_items, price, currency, transaction_id
ADD_CART pixel_id, page_url, item_category, item_ids, number_items, price, currency
SIGN_UP pixel_id, page_url, sign_up_method
SEARCH pixel_id, page_url, search_string
All other events pixel_id, page_url

MOBILE_APP Parameters

Events triggered by ATT Opt Out users are recommended to make use of the data_use parameter in order to be processed via a privacy-centric data processing pipeline for Advanced Conversions.

Event Required Parameters For Full Functionality
PURCHASE snap_app_id, app_id, transaction_id, item_category, item_ids, number_items, price, currency
ADD_CART snap_app_id, app_id, item_category, item_ids, number_items, price
SIGN_UP snap_app_id, app_id, sign_up_method
SEARCH snap_app_id, app_id, search_string
All other events snap_app_id, app_id

OFFLINE Parameters

Offline events track events that take place in the physical world (or non-pixelable online events). These events will likely not have a page URL and IP addresses attached to them.

For that reason, it’s required to pass either the hashed email and/or hashed phone number for all events that are reported.

Event Required Parameters For Full Functionality
PURCHASE pixel_id, transaction_id, item_category, item_ids, number_items, price, currency
ADD_CART pixel_id, item_category, item_ids, number_items, price, currency
SIGN_UP pixel_id, sign_up_method
SEARCH pixel_id, search_string
All other events pixel_id

Conversion API Examples

App Install Conversion

This endpoint creates an app install conversion event and posts it to Snap

POST https://tr.snapchat.com/v2/conversion

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{
    "app_id": "447188370",
    "snap_app_id": "3984298349849",
    "timestamp": "1521504154084",
    "event_type": "APP_INSTALL",
    "event_conversion_type": "MOBILE_APP",
    "event_tag": "appsignups",
    "transaction_id": "3409181200909",
    "hashed_mobile_ad_id": "9543d100cf0775a3926d66cfbc557941a79c81370b019e5c927063e99b8e4aaa",
    "hashed_email": "f13ff72f0a7cf3f0d187f4e4f6c41110e4bbd2d7560ede70ca68bd0b8b7fdc15",
    "hashed_phone_number": "d10cad0775a3926d66cfbc557941a79c81370b019e5c927063e99b8e4aaa",
    "hashed_idfv": "d10cad0775a3926d66cfbc557941a79c81370b019e5c927063e99b8e4aca",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
    "hashed_ip_address": "d10cad0775a3926d66cfbc557941a79c81370b019e5c927063e99b8e4bbb",
}' \
  https://tr.snapchat.com/v2/conversion

The above command returns JSON structured like this:

{    
    "status": "SUCCESS",
    "reason":"All records processed"
}

App Purchase Conversion

This endpoint creates an app purchase conversion event and posts it to Snap

POST https://tr.snapchat.com/v2/conversion

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{
    "app_id": "447188370",
    "snap_app_id": "3984298349849",
    "timestamp": "1521504154084",
    "event_type": "PURCHASE",
    "event_conversion_type": "MOBILE_APP",
    "event_tag": "retention",
    "price": "43",
    "currency": "usd",
    "transaction_id": "3409181200909",
    "hashed_mobile_ad_id": "9543d100cf0775a3926d66cfbc557941a79c81370b019e5c927063e99b8e4aaa",
    "hashed_email": "f13ff72f0a7cf3f0d187f4e4f6c41110e4bbd2d7560ede70ca68bd0b8b7fdc15"
    "hashed_phone_number": "d10cad0775a3926d66cfbc557941a79c81370b019e5c927063e99b8e4aaa",
    "hashed_idfv": "9543d100cf0775a3926d66cfbc557941a79c81370b019e5c927063e99b8e4aaa",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
    "hashed_ip_address": "9543d100cf0775a3926d66cfbc557941a79c81370b019e5c927063e99b8e4aaa",
}' \
  https://tr.snapchat.com/v2/conversion

The above command returns JSON structured like this:

{    
    "status": "SUCCESS",
    "reason":"All records processed"
}

Web Page View Conversion

This endpoint creates a web page view conversion event and posts it to Snap

POST https://tr.snapchat.com/v2/conversion

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{
    "pixel_id":"67d34640-b7a4-42a8-b821-6434d70f08a4",
    "timestamp": "1521504154084",
    "event_type": "PAGE_VIEW",
    "event_conversion_type": "WEB",
    "event_tag": "web_traffic",
    "user_agent": Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
    "hashed_ip_address": "d100cf0775a3926d66cfbc557941a79c81370b019e5c927063e99b8e4aad",
}' \

  https://tr.snapchat.com/v2/conversion

The above command returns JSON structured like this:

{    
    "status": "SUCCESS",
    "reason":"All records processed"
}

Web Add to Cart Conversion

This endpoint creates an add to cart conversion event and posts it to Snap

POST https://tr.snapchat.com/v2/conversion

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{
    "pixel_id":"67d34640-b7a4-42a8-b821-6434d70f08a4",
    "timestamp": "1521504154084",
    "event_type": "PURCHASE",
    "event_conversion_type": "WEB",
    "event_tag": "backtoschool",
    "price": "43",
    "currency": "usd",
    "page_url":"https://www.example.com/products/bikes/",   
    "item_category": "bikes",
    "item_ids": "sam001",
    "hashed_email": "f13ff72f0a7cf3f0d187f4e4f6c41110e4bbd2d7560ede70ca68bd0b8b7fdc15",
    "hashed_phone_number": "d10cad0775a3926d66cfbc557941a79c81370b019e5c927063e99b8e4aaa",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
    "hashed_ip_address": "d100cf0775a3926d66cfbc557941a79c81370b019e5c927063e99b8e4ccc",
}' \
  https://tr.snapchat.com/v2/conversion

The above command returns JSON structured like this:

{    
    "status": "SUCCESS",
    "reason":"All records processed"
}

Offline Purchase Conversion

This endpoint creates an offline purchase conversion event and posts it to Snap

POST https://tr.snapchat.com/v2/conversion

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{
    "pixel_id":"67d34640-b7a4-42a8-b821-6434d70f08a4",
    "timestamp": "1521504154084",
    "event_type": "PURCHASE",
    "event_conversion_type": "OFFLINE",
    "event_tag": "instore",
    "price": "43",
    "currency": "usd",
    "transaction_id": "3409181200909",
    "hashed_email": "f13ff72f0a7cf3f0d187f4e4f6c41110e4bbd2d7560ede70ca68bd0b8b7fdc15",
    "hashed_phone_number": "d10cad0775a3926d66cfbc557941a79c81370b019e5c927063e99b8e4aaa",
}' \
  https://tr.snapchat.com/v2/conversion

The above command returns JSON structured like this:

{    
    "status": "SUCCESS",
    "reason":"All records processed"
}

Grouped Request Example

This endpoint creates a grouped conversion event and posts it to Snap

POST https://tr.snapchat.com/v2/conversion

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '[
    {
        "pixel_id":"67d34640-b7a4-42a8-b821-6434d70f08a4",
        "timestamp":"1521504154084",
        "event_type":"PURCHASE",
        "event_conversion_type":"WEB",    
        "version":"2.0",   
        "event_tag": "sale",   
        "page_url":"https://www.example.com",   
        "price": "43",
"currency": "usd",
"transaction_id": "38479127391273",
"hashed_email": "9543d100cf0775a3926d66cfbc557941a79c81370b019e5c927063e99b8eaaaa"
        },{
        "pixel_id":"67d34640-b7a4-42a8-b821-6434d70f08a4",
        "timestamp":"1521504154784",
        "event_type":"PAGE_VIEW",
"event_conversion_type":"WEB",   
        "version":"2.0",   
        "event_tag": "offline",   
        "page_url":"https://www.example.com/products/",
"hashed_email": "a843d100cf0775a3926d66cfbc557941a79c81370b019e5c927063e99b8eaaaa"
        },{
        "pixel_id":"67d34640-b7a4-42a8-b821-6434d70f08a4",
        "timestamp":"1521504154984",
        "event_type":"VIEW_CONTENT",
"event_conversion_type":"WEB",  
        "version":"2.0",   
        "event_tag": "offline",   
        "page_url":"https://www.example.com/products/bikes/",   
        "item_category": "bikes",
        "item_ids": "sam001",
"hashed_email": "05a3d100cf0775a3926d66cfbc557941a79c81370b019e5c927063e99b8eaaaa"
    }
]' \
  https://tr.snapchat.com/v2/conversion

The above command returns JSON structured like this:

{    
    "status": "SUCCESS",
    "reason":"All records processed"
}

Brands Parameter Example

This is an example of a Conversions API request that uses the brands parameter.

curl -X POST -H "Content-Type: application/json" \
  -H "Authorization: Bearer meowmeowmeow" \
  -d '{
    "pixel_id":"67d34640-b7a4-42a8-b821-6434d70f08a4",
    "timestamp": "1676512408",
    "event_type": "PURCHASE",
    "event_conversion_type": "WEB",
    "event_tag": "backtoschool",
    "price": "43",
    "currency": "usd",
    "page_url":"https://www.example.com/products/bikes/",   
    "item_ids": ["sku001","sku002"],
    "brands": ["brand01", "brand02"],
    "hashed_email": "43b71251d26a9aca17e4f8a09e6dbe300633390199f59efd589a8f41886a3c45",
    "hashed_phone_number": "77534a92996d566bbb02067376549b2e1f4a09bca54cbe3c4bab51f3e36e1ea8",
    "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
    "hashed_ip_address": "c5eb5a4cc76a5cdb16e79864b9ccd26c3553f0c396d0a21bafb7be71c1efcd8c"
}' \
  https://tr.snapchat.com/v2/conversion

The above command returns JSON structured like this:

{    
    "status": "SUCCESS",
    "reason":"All records processed"
}
cURL
Company
HomeBlogJobsPress InquiriesTwitter
Download
Snapchat for iOSSnapchat for Android
Community
SupportCommunity GuidelinesSafety CenterSnapcodesGeofilters
Business
AdvertisingInquiriesAdvertising PoliciesBrand GuidelinesPromotions Rules
Legal
Terms of ServicePrivacy PolicyPrivacy CenterCookie PolicyCopyrightMemories Terms of ServiceOn-Demand Geofilters Terms and Conditions
Hi! We use cookies on this website to help operate our site and for analytics purposes. For more on how we use cookies and your cookie choices, go here! By continuing to use our services, you are giving us your consent to use cookies.