Snapchat Leads Conversions API
Overview
Section titled “Overview”Signals sends updated lead information back to Snapchat, so campaigns running against Snapchat native lead forms can optimize towards leads that became qualified rather than towards raw form fills.
Use it when a lead is captured in a Snapchat lead form and its outcome is recorded somewhere else: a CRM, a file drop, a database or a warehouse. Signals reads the lead status from that system and reports it to your Snapchat pixel.
Choose Snapchat Offline Conversions API instead when the conversion is a purchase or a booking rather than a change in lead status.
Supported sources
Section titled “Supported sources”Sources supported by Snapchat Leads Conversions API
| Category | Supported |
|---|---|
| API | |
| CRM | |
| Database | |
| File & storage | |
| Warehouse |
Prerequisites
Section titled “Prerequisites”Before connecting Snapchat Leads Conversions API, make sure you have:
- A Snapchat Ads account.
- Access to Snapchat Business Manager and the Events Manager section.
- Leads whose Snapchat lead ID is stored in your CRM or other source system. Without it an update cannot be tied back to the original form submission.
- Server-side API permission on the account you intend to send to.
- A Pixel ID and an Access Token generated in Snapchat Ads Manager.
- A Datahash Studio account with the target project selected.
- A source connected in the same project holding the lead status data.
Authentication
Section titled “Authentication”In Studio, open Destinations, find Snapchat, and click the Leads Conversions API tile. This connector uses manual credentials only. There is no single sign-on path.
- Enter the Pixel ID and Access Token of the account you want to send to.
- Click Validate credentials.
- Click Finish.
| Field | What it is | Where to find it |
|---|---|---|
| Pixel ID | The identifier Snapchat assigns to each pixel created in Ads Manager. | ads.snapchat.com, then open the dropdown top left and go to Pixels. Open the pixel you are integrating; the ID appears under its name. |
| Access Token | A credential authorizing Datahash to send events to that pixel on your behalf. | Same account, then Business Details in the left panel. Scroll to Conversions API Tokens and click Generate Token. |
Manage instance
Section titled “Manage instance”To change the instance, open it from Manage Instances, use the menu in the top right and choose Edit, update the fields and click Finish. Cancel keeps the previous configuration running, so updates apply only after you finish.
Data & identifiers
Section titled “Data & identifiers”Signals sends the fields your source maps. Send identifiers already hashed where you can. Plain text also works: they are normalized and SHA-256 hashed before they reach Snapchat.
Required
Section titled “Required”| Field | When it is required |
|---|---|
| Snapchat lead ID | Always. The ID Snapchat generated when the lead form was submitted. It is what ties an update to the original lead. |
| Event name | Always. The lead status, for example Interested. |
| Event time | Always. |
| Last modified date | Always. The time the lead status changed. It is what separates one status change from the next on the same record. |
| Email address | Always. Hashed. |
| Phone number | Always. Up to three numbers per person, and at least one is required. Hashed. |
Recommended
Section titled “Recommended”All hashed. Each one you add raises the share of leads Snapchat can match.
| Field | Format |
|---|---|
| First name | Lowercase, trimmed, no punctuation. |
| Last name | Lowercase, trimmed, no punctuation. |
| City | Lowercase, trimmed, no punctuation. |
| State or region | Lowercase, trimmed, no punctuation. |
Optional
Section titled “Optional”| Field | Format |
|---|---|
| Email address 2 and 3 | Two further addresses per person. Hashed. |
| Gender | Hashed. |
| Country | Hashed. |
| Postcode | Hashed. |
| External ID | A unique ID of your own, such as a CRM record ID. Hashed. |
| Client user agent | Not hashed. |
| Client IP address | Not hashed. |
| Snapchat click ID | Not hashed. Where you hold it, it is the strongest single match signal available. |
| Currency and value | Send both together where the lead has a value attached. |
Best practices
Section titled “Best practices”- Make sure the Snapchat lead ID is populated on every record before you go live. It is the one field that cannot be substituted.
- Map as many identifiers as your source holds. Email and phone are required; name and location are the cheapest way to lift match rates beyond that.
- Check that the last modified date actually updates when a record changes, since it is what distinguishes one status change from the next.
- Send only the lead stages worth optimizing towards. Reporting every status change dilutes the signal Snapchat learns from.
Troubleshooting & FAQ
Section titled “Troubleshooting & FAQ”Leads rejected or unmatched. The Snapchat lead ID is missing or does not match a lead Snapchat generated. Without it the update cannot be tied to the original form submission.
No events appearing. Confirm a source is connected in the same project and sending. A valid destination on its own produces nothing.
Duplicate conversions. Usually a replayed batch, or a lead returning to a status it already reported.
Match rates are low. Add the recommended name and location fields, and check formatting at source before hashing.
Delivery stopped. The access token may have expired or been revoked. Generate a new one and re-validate.