Snapchat Ads

Send conversion events to Snapchat through the Snapchat Conversions API v3. This integration and the Snapchat Conversions API integration call the same API; use one of them.

Why route Snapchat Ads through Datafly Signal

• Conversions survive ad blockers and tracking prevention. Signal sends the event from your own infrastructure, so the conversions Snapchat optimises against are not filtered by the browser.
• Identifiers are hashed before they leave your infrastructure. Signal normalises and applies SHA-256 inside your own deployment, so Snapchat receives match keys, not raw personal data.
• Click and cookie identifiers are captured first-party and replayed on later conversions, so attribution survives when the landing-page cookie has expired.
• One consent decision governs every destination. Snapchat is gated by the same consent state as the rest of your stack, so a withdrawal applies everywhere at once.
• Presets for Retail, Travel, Lead Generation and Insurance. The mapping starts from a working configuration for your vertical, and every field can be changed afterwards.

Prerequisites

1. A Snapchat Business account and a Snap Pixel (Ads Manager > Events Manager). Copy the Pixel ID.
2. In Business Manager, open Business Details > Conversions API Tokens and generate a token. Enter it in the Access Token field (stored as api_key).

Configuration

Configure in Signal

1. In the Management UI, go to Integrations > Integration Library and select Snapchat Ads.
2. Choose a preset, fill in the fields above and choose the pipelines and consent categories (advertising destinations default to marketing).
3. Click Install Integration.

Or with the Management API:

curl -X POST http://localhost:8084/v1/admin/integration-catalog/snapchat_ads/install \
  -H "Authorization: Bearer YOUR_TOKEN" -H "Content-Type: application/json" \
  -d '{"name": "Snapchat Ads", "variant": "default", "config": {"pixel_id": "abc123de-f456-7890-gh12-ijkl34567890", "api_key": "eyJhbGciOi..."}, "delivery_mode": "server_side"}'

API endpoint

POST https://tr.snapchat.com/v3/{{pixel_id}}/events?access_token={{api_key}}

Authentication: ?access_token=<token> query parameter. Allow egress to tr.snapchat.com from the network your delivery workers run on.

Presets and event mapping

Every preset sends only the fields it maps (the strict output contract is on). Events not listed are not sent.

Retail (ecommerce)

Full retail funnel with Snap’s standard events: LIST_VIEW, SEARCH, VIEW_CONTENT, ADD_TO_WISHLIST, ADD_CART, START_CHECKOUT, ADD_BILLING and PURCHASE, with contents, content IDs, value and currency for Dynamic Ads.

Travel (travel)

Travel funnel with the Dynamic Travel Ads parameters: destination, flight and hotel searches, listing views and saves, booking start, payment and completed bookings.

Default (default)

Snapchat Conversions API v3 core funnel: page views, content views, search, add to cart, checkout, sign-ups, leads and purchases, with hashed email, phone and name, the Snap click ID and _scid cookie, IP and user agent, and an event ID for Pixel deduplication.

Lead Generation (lead_gen)

Lead-generation funnel: page views, search, sign-ups and leads (SIGN_UP, as Snap has no lead event) and newsletter subscriptions (SUBSCRIBE).

Insurance (insurance)

Insurance quote and policy funnel: quote start, quote request and quote completion as CUSTOM_EVENT_1 to 3 (label them in Snap Events Manager), leads as SIGN_UP, checkout, payment and policy purchase as PURCHASE with the policy number as the event ID, renewals as SUBSCRIBE.

Identity and hashing

Email, phone and names come from datafly.identify() traits (a legacy properties.email / properties.phone is read when no trait is set). Raw personal data is never sent.

Deduplication and consent

event_id carries the Signal event ID, or the order ID on purchases, which Snap matches against the Pixel’s client_dedup_id / transaction_id within 48 hours. event_time is sent in epoch milliseconds; Snap rejects events older than seven days.

Example: purchase (Default preset)

datafly.identify('crm-user-7', { email: 'jane.doe@example.com', phone: '07700 900123', first_name: 'Jane', last_name: 'Doe' });
datafly.track('purchase', {
  transaction_id: 'T_1001', value: 139.99, currency: 'GBP',
  items: [
    { item_id: 'SKU_1', item_name: 'Helmet', item_category: 'Motorbike', item_brand: 'Shoei', price: 120.00, quantity: 2 },
    { item_id: 'SKU_2', item_name: 'Gloves', price: 19.99, quantity: 1 }
  ]
});

Request Signal sends (rendered from the preset):

{
  "data": [
    {
      "action_source": "WEB",
      "custom_data": {
        "content_ids": [
          "SKU_1",
          "SKU_2"
        ],
        "content_type": "product",
        "contents": [
          {
            "brand": "Shoei",
            "id": "SKU_1",
            "item_price": 120,
            "quantity": 2
          },
          {
            "id": "SKU_2",
            "item_price": 19.99,
            "quantity": 1
          }
        ],
        "currency": "GBP",
        "num_items": "2",
        "order_id": "T_1001",
        "value": 139.99
      },
      "event_id": "T_1001",
      "event_name": "PURCHASE",
      "event_source_url": "https://shop.example.co.uk/p/123?utm_source=x",
      "event_time": 1758500000123,
      "integration": "datafly",
      "user_data": {
        "client_ip_address": "203.0.113.7",
        "client_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
        "em": "86e0b9e56c17cc4d12387e1949b85053fbe73bc3ce5a1188713a9d300cc6133d",
        "external_id": "a1a37b21e9d35da94d0ae0b42483e449206f1e24c3790d28c113fb5fb9045f93",
        "fn": "81f8f6dde88365f3928796ec7aa53f72820b06db8664f5fe76a7eb13e24546a2",
        "ln": "799ef92a11af918e3fb741df42934f3b568ed2d93ac1df74f1b8d41a27932a6f",
        "ph": "033134b911b137918338415ee3d20a064b24773d36a3b02e8b99fdd3fcd6b4cd",
        "sc_click_id": "scclick",
        "sc_cookie1": "scid-cookie"
      }
    }
  ]
}

Known limitations

• Snap has no lead event: generate_lead is sent as SIGN_UP. The insurance quote events use CUSTOM_EVENT_1 to CUSTOM_EVENT_3; name them in Snap Events Manager.
• snapchat and snapchat_ads deliver to the same API; use one of them.
• Name hashing trims and lowercases but does not strip punctuation as Snap documents (#1390).
• custom_data.num_items is the number of order lines, not the unit total (#1389).

Troubleshooting