# Conversions API

Connect a Snap Pixel with its Conversions API token, then send server-side events to it with POST /v1/events.

import { Tab, Tabs } from 'fumadocs-ui/components/tabs';

Send server-side events to a Snap Pixel with [`POST /v1/events`](/products/conversions-api). Snapchat Ads connects with the pixel's id and a Conversions API token, not with a sign-in.

## Before you start

In Snapchat Ads Manager, copy the Snap Pixel ID from Events Manager. Then generate a Conversions API token under Business Details of the organization that owns the pixel.

## Connect the pixel

`POST /v1/connect/snapchat-ads/credentials` checks the token against the pixel with Snapchat, then saves a `snapchatads` account. Nothing is saved when Snapchat refuses it.

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.connect.snapchat.connectSnapchatAdsCredentials({
  body: {
    profileId: '66a1f0c2a4b9d3e8f1a2b3c4',
    pixelId: '1a2b3c4d-5e6f-4a8b-9c0d-1e2f3a4b5c6d',
    accessToken: 'eyJhbGciOi...'
  }
});
```
</Tab>
<Tab value="Python">
```python
data = client.connect.snapchat.connect_snapchat_ads_credentials(
    profile_id="66a1f0c2a4b9d3e8f1a2b3c4",
    pixel_id="1a2b3c4d-5e6f-4a8b-9c0d-1e2f3a4b5c6d",
    access_token="eyJhbGciOi...",
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/connect/snapchat-ads/credentials" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "66a1f0c2a4b9d3e8f1a2b3c4",
    "pixelId": "1a2b3c4d-5e6f-4a8b-9c0d-1e2f3a4b5c6d",
    "accessToken": "eyJhbGciOi..."
  }'
```
</Tab>
</Tabs>

## Send a conversion event

The call maps to Snap's `POST /v3/{pixelId}/events`, in batches of 2,000. `destinationId` is the connection's Snap Pixel ID.

| Field | Snapchat |
|-------|----------|
| `eventName` | Standard names map to Snap's: `Purchase` = `PURCHASE`, `Lead` and `CompleteRegistration` = `SIGN_UP`, `AddToCart` = `ADD_CART`. Snap's own names are sent as is. Any other name is refused: use `CUSTOM_EVENT_1` to `CUSTOM_EVENT_5`. |
| `user` | Needs `email`, `phone`, or `ipAddress` plus `userAgent`. Personal fields are hashed before they leave Zernio. |
| `user.clickIds.sccid`, `scid` | The `ScCid` click id and the `_scid` cookie, sent as `sc_click_id` and `sc_cookie1`. Read them on your site and pass them. |
| `sourceUrl` | Required on website events. |
| `value`, `currency` | Required on a purchase. |
| `actionSource` | `web` stays `WEB`, other sources become `OFFLINE`. App events are refused: they go to a Snap App ID. |
| `eventTime` | Up to 7 days old. |
| `testCode` | Any value sends the events to Snap's validate endpoint: checked, not recorded. |
| `consent.adUserData: "DENIED"` | Leaves out the hashed fields. IP, user agent and click ids are still sent. |

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.conversions.sendEvents({
  body: {
    profileId: '66a1f0c2a4b9d3e8f1a2b3c4',
    destinations: [{ accountId: '66b2e19d8c3f5a7e9d0b1c2d', destinationId: '1a2b3c4d-5e6f-4a8b-9c0d-1e2f3a4b5c6d' }],
    events: [{
      eventName: 'Purchase',
      eventTime: 1804150800,
      eventId: 'order_1042',
      sourceUrl: 'https://shop.example.com/thank-you',
      value: 59.9,
      currency: 'USD',
      user: { email: 'ana@example.com', ipAddress: '203.0.113.7', userAgent: 'Mozilla/5.0 ...' }
    }]
  }
});
```
</Tab>
<Tab value="Python">
```python
data = client.conversions.send_events(
    profile_id="66a1f0c2a4b9d3e8f1a2b3c4",
    destinations=[{"accountId": "66b2e19d8c3f5a7e9d0b1c2d", "destinationId": "1a2b3c4d-5e6f-4a8b-9c0d-1e2f3a4b5c6d"}],
    events=[{
        "eventName": "Purchase",
        "eventTime": 1804150800,
        "eventId": "order_1042",
        "sourceUrl": "https://shop.example.com/thank-you",
        "value": 59.9,
        "currency": "USD",
        "user": {"email": "ana@example.com", "ipAddress": "203.0.113.7", "userAgent": "Mozilla/5.0 ..."},
    }],
)
```
</Tab>
<Tab value="curl">
```bash
curl -X POST "https://zernio.com/api/v1/events" \
  -H "Authorization: Bearer $ZERNIO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "profileId": "66a1f0c2a4b9d3e8f1a2b3c4",
    "destinations": [{ "accountId": "66b2e19d8c3f5a7e9d0b1c2d", "destinationId": "1a2b3c4d-5e6f-4a8b-9c0d-1e2f3a4b5c6d" }],
    "events": [{
      "eventName": "Purchase",
      "eventTime": 1804150800,
      "eventId": "order_1042",
      "sourceUrl": "https://shop.example.com/thank-you",
      "value": 59.9,
      "currency": "USD",
      "user": { "email": "ana@example.com", "ipAddress": "203.0.113.7", "userAgent": "Mozilla/5.0 ..." }
    }]
  }'
```
</Tab>
</Tabs>

Snapchat keeps one copy when the Snap Pixel sends the same `eventId`.

## If it fails

| Error | Cause | Fix |
|-------|-------|-----|
| `INVALID_EVENT` in `failures` | An unknown event name, no match key, no `sourceUrl`, a purchase without value, or an event older than 7 days | Read the failure's message and fix that event. |
| Connect refused | Snapchat did not accept the token for this pixel | Generate the token in the organization that owns the pixel. |
| Destination `error`: reconnect Snapchat Ads | The token was revoked | Connect again with a new token. |
| Destination `error`: must be this connection's Snap Pixel ID | `destinationId` is another pixel | Connect that pixel separately. |

## Related

- [Send events](/conversions/send-events): the unified event shape, every field.
- [Platforms](/products/conversions-api/platforms): what each platform gets from an event.
- [Server-side tracking](/products/server-side-tracking): website events with IP, user agent and page URL.