Skip to main content

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}

Create Access 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

All Parameters

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.

Was this page helpful?
Yes
No

AI-Powered Search