Using the API
The Basics To create a conversion event, send a POST event to:
Web Endpoint
Using a Pixel ID
https://tr.snapchat.com/v3/{PIXEL_ID}/events?access_token={TOKEN}
App Endpoint
Using a Snap App ID
https://tr.snapchat.com/v3/{SNAP_APP_ID}/events?access_token={TOKEN}
Structure of JSON Body
Send all event data in the Body of the request, as a JSON string.
The main request body contains a data array which can contain an app_data, user_data, and custom_data object for each event.
Request Body Example:
{
"data": [
{
"event_name": "Purchase",
"event_time": 1705508777,
"action_source": "MOBILE_APP",
"data_processing_options": "['LMU']",
"app_data": {
"advertiser_tracking_enabled": 1,
"extinfo": [
"a2",
"com.some.app",
"771",
"Version 7.7.1",
"10.1.1",
"OnePlus6",
"en_US",
"GMT-1",
"TMobile",
"1920",
"1080",
"2.00",
"2",
"128",
"8",
"USA/New York"
]
},
"user_data": {
"em":
["7b17fb0bd173f625b58636fb796407c22b3d16fc78302d79f0fd30c2fc2fc068"],
"ph":
["959995162a8d9712427ae9c39676cde79bbfc9f560bc3911ec9edcf1f169e5f6"]
},
"custom_data": {
"currency": "USD",
"value": "142.52",
"referrer_url": "www.example.com",
"brands": "example_brand",
"custom_id": "example_id",
"sign_up_method": "example_method"
}
}
]
}
Request Body Example - Partner
If you are a partner, or an advertiser using a partner integration, include the integration parameter with the value of your partner or connector, within the data array.
{
"data": [{
"integration": "partner_name_abc", // integration name
"event_name": "Purchase",
"event_time": 1705508777,
...
}]
}
Required Parameters
For best signal integrity and quality we require these parameters, for each event in the data array:
- App events: app_data (including extinfo)
- user_data (with one of the parameters below for matching)
- event_name
- action_source
- event_time
- event_source_url
At least one of the following to match your events to Snapchatters:
- em (hashed email)
- ph (hashed phone number)
- client_ip_address & client_user_agent
- madid (Mobile Advertising ID) for app events only
Recommended Parameters
In addition to the above, the below parameters are strongly recommended:
- sc_cookie1
- sc_click_id
If the event_name is PURCHASE, then the following parameters are also required:
- currency
- value
Example CAPI Event Request
curl --location 'https://tr.snapchat.com/v3/{{pixel_id}}/events?access_token={{access_token}}' \
--header 'Content-Type: application/json' \
--data '{
"data": [
{
"event_name": "PAGE_VIEW",
"event_time": 1709761985,
"user_data": {},
"action_source": "WEB",
"event_source_url": "https://..."
}
]
}'
Example Response
{
"status": "VALID",
"reason": "Events have been processed successfully."
}
Validate a Conversion event
This endpoint validates if a conversion event is constructed properly:
Web Validate Endpoint
POST https://tr.snapchat.com/v3/{pixel_id}/events/validate
App Validate Endpoint
POST https://tr.snapchat.com/v3/{snap_app_id}/events/validate
Deduplication
We recommend our web advertisers implement Conversions API alongside a Pixel integration, and our app advertisers to implement Conversions API alongside an MMP integration. Our systems support receiving redundant data; however, we recommend adopting the following guidelines to ensure accurate reporting and that events are only attributed once.
- Send event_id on all events on all integrations (e.g. CAPI + Pixel)
- This is a unique id which will be used for deduplication against pixel events. For reference, for Snap Pixel non purchase events, these can map to client_dedup_id and for purchase events, these can map to transaction_id values in this parameter.
- These values can be created at time of event, but should match for all calls via Snap Pixel, third party, or direct CAPI calls.
Please always ensure timestamps are accurate.
Sending 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:
- You can parse the &ScCid= query parameter from an ad’s destination URL and send this value in the event’s sc_click_id field.
- You can pass the full destination URL into the event’s event_source_url field and the Conversions API will automatically extract the click ID and associate it with the event.
Supplemental parameters
When sending the click ID, we also highly recommend including the sc_cookie1 or external_id parameters as follows.
- If you are using the Snap Pixel, we recommend sending the sc_cookie1 and event_source_url parameters in the event. The sc_cookie1 parameter should contain the _scid cookie value.
- If you are not using the Snap Pixel and have your own cookie, you can pass your cookie ID into the external_id field.
Including the sc_click_id, sc_cookie1, or external_id 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:
A user swipes on an ad and views its landing page at the URL:
https://www.mywebsite.com/landing-page?utm_source=snapchat&ScCid=7b3a7917-a82a-47e8-9728-e1b3b045abb2
The Click ID value would be 7b3a7917-a82a-47e8-9728-e1b3b045abb2
, and should be sent with every event in the sc_click_id
field.
This value should also be stored in any preferred method to be used on all subsequent events, on all pages, for that session.
Alternatively if &ScCid=7b3a7917-a82a-47e8-9728-e1b3b045abb2
is appended to every url visited, Snap will automatically extract the Click ID.
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 'advertiser_tracking_enabled' 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 'advertiser_tracking_enabled' 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.