# Conversions API

Send server-side conversions to an X Pixel event with POST /v1/events, matched on the twclid click id, email, phone or IP.

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

Send server-side conversions to X with [`POST /v1/events`](/products/conversions-api) on your `xads` account. X counts them against one conversion event of the [X Pixel](/platforms/x-ads/tracking-tag).

## Before you start

The connected X user needs Account Administrator or Ad Manager access on the ad account that owns the pixel.

`destinationId` is the pixel event's `siteEventId`, `tw-<pixel>-<event>`. [`GET /v1/ads/conversions/destinations`](/conversions/list-ad-conversion-destinations) lists every event of each ad account's pixel.

## Send a conversion event

The call maps to X's `POST /12/measurement/conversions/{pixelId}`, in batches of 500.

| Field | X |
|-------|---|
| `destinationId` | The pixel event, for example `tw-rbhhj-rcfms`. It decides what is counted, so `eventName` is ignored. |
| `user` | Needs `clickIds.twclid`, `email`, `phone`, or `ipAddress` plus `userAgent`. Email and phone are hashed before they leave Zernio. |
| `user.clickIds.twclid` | The click id X adds to ad links, sent as is. The [website tag](/products/server-side-tracking) captures it for you. |
| `eventId` | Sent as `conversion_id`, so X keeps one copy when the pixel reports the same conversion. |
| `eventTime` | Up to 90 days after the click. |
| `value`, `currency`, `items` | Sent as `value`, `price_currency` and `contents`. |
| `consent.adUserData: "DENIED"` | Sends only `twclid`. An event without one is refused. |

<Tabs items={['Node.js', 'Python', 'curl']}>
<Tab value="Node.js">
```typescript
const { data } = await zernio.conversions.sendEvents({
  body: {
    profileId: '66a1f0c2a4b9d3e8f1a2b3c4',
    destinations: [{ accountId: '66b2e19d8c3f5a7e9d0b1c2d', destinationId: 'tw-rbhhj-rcfms' }],
    events: [{
      eventName: 'Purchase',
      eventTime: 1804150800,
      eventId: 'order_1042',
      value: 59.9,
      currency: 'USD',
      user: { email: 'ana@example.com', clickIds: { twclid: '26nk6e3rdhbmfvqlsnsl0a2hvb' } }
    }]
  }
});
```
</Tab>
<Tab value="Python">
```python
data = client.conversions.send_events(
    profile_id="66a1f0c2a4b9d3e8f1a2b3c4",
    destinations=[{"accountId": "66b2e19d8c3f5a7e9d0b1c2d", "destinationId": "tw-rbhhj-rcfms"}],
    events=[{
        "eventName": "Purchase",
        "eventTime": 1804150800,
        "eventId": "order_1042",
        "value": 59.9,
        "currency": "USD",
        "user": {"email": "ana@example.com", "clickIds": {"twclid": "26nk6e3rdhbmfvqlsnsl0a2hvb"}},
    }],
)
```
</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": "tw-rbhhj-rcfms" }],
    "events": [{
      "eventName": "Purchase",
      "eventTime": 1804150800,
      "eventId": "order_1042",
      "value": 59.9,
      "currency": "USD",
      "user": { "email": "ana@example.com", "clickIds": { "twclid": "26nk6e3rdhbmfvqlsnsl0a2hvb" } }
    }]
  }'
```
</Tab>
</Tabs>

Response (`200`):

```json
{
  "eventsReceived": 1,
  "stored": true,
  "testCode": null,
  "destinations": [
    { "accountId": "66b2e19d8c3f5a7e9d0b1c2d", "destinationId": "tw-rbhhj-rcfms", "platform": "xads", "eventsSent": 1, "eventsFailed": 0, "failures": [] }
  ],
  "queuedDestinations": 0
}
```

X has no test mode: every event reaches the live account. Test on a pixel event you do not bid on.

## If it fails

| Error | Cause | Fix |
|-------|-------|-----|
| `INVALID_EVENT` in `failures` | No match key, or the event is more than 90 days after the click | Send `twclid`, `email`, `phone`, or `ipAddress` plus `userAgent`, within 90 days. |
| `X_REJECTED` in `failures` | X refused the batch | Read the failure's message. Throttled batches are retried. |
| Destination `error`: must be an X Pixel event id | `destinationId` is not a pixel event | Use a `siteEventId` from the destinations list. |
| Destination `error`: no access to this X Pixel | The X user lacks access to the pixel's ad account | Grant Account Administrator or Ad Manager access. |
| Destination `error`: reconnect X Ads | X rejected the token | Reconnect X Ads. |

## Related

- [Send events](/conversions/send-events): the unified event shape, every field.
- [X Pixel](/platforms/x-ads/tracking-tag): the pixel and its conversion events.
- [Platforms](/products/conversions-api/platforms): what each platform gets from an event.