# Conversions API

Send offline conversions to a Microsoft Advertising goal with POST /v1/events, matched on the msclkid click id, email or phone.

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

Send conversions to Microsoft Advertising with [`POST /v1/events`](/products/conversions-api) on your `microsoftads` account. Each event is uploaded to one offline conversion goal.

## Before you start

The ad account needs an offline conversion goal. Create it in Microsoft Advertising under Conversions › Conversion goals, with the type Offline.

`destinationId` is `accounts/{adAccountId}/conversionGoals/{goalId}`. [`GET /v1/ads/conversions/destinations`](/conversions/list-ad-conversion-destinations) lists the goals of every ad account in scope.

## Send a conversion event

The call maps to Microsoft's `ApplyOfflineConversions`, in batches of 1,000. Zernio reads the goal's name at send time, so a renamed goal keeps working.

| Field | Microsoft Advertising |
|-------|-----------------------|
| `destinationId` | The goal. It decides what is counted, so `eventName` is ignored. |
| `user` | Needs `clickIds.msclkid`, `email` or `phone`. Email and phone are hashed before they leave Zernio. |
| `user.clickIds.msclkid` | The click id Microsoft adds to ad links, sent as `MicrosoftClickId`. The [website tag](/products/server-side-tracking) captures it for you. |
| `eventTime` | Up to 90 days after the click. |
| `value`, `currency` | Sent as `ConversionValue` and `ConversionCurrencyCode`. |
| `consent.adUserData: "DENIED"` | Leaves out email and phone, so the event needs its `msclkid`. |

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

Response (`200`):

```json
{
  "eventsReceived": 1,
  "stored": true,
  "testCode": null,
  "destinations": [
    { "accountId": "66b2e19d8c3f5a7e9d0b1c2d", "destinationId": "accounts/180012345/conversionGoals/987654", "platform": "microsoftads", "eventsSent": 1, "eventsFailed": 0, "failures": [] }
  ],
  "queuedDestinations": 0
}
```

Microsoft answers per conversion, so one refused event does not fail the batch.

Microsoft has no test mode and no dedup id: every event is recorded. Send each conversion once, and test on a goal you do not bid on.

## If it fails

| Error | Cause | Fix |
|-------|-------|-----|
| `INVALID_EVENT` in `failures` | No `msclkid`, email or phone, or the event is more than 90 days after the click | Send one of them, within 90 days. |
| `MICROSOFT_EVENT_FAILED` in `failures` | Microsoft refused that conversion | Read the failure's message, fix the event and resend it. |
| Destination `error`: must be an offline conversion goal | `destinationId` is not a goal | Use a goal from the destinations list. |
| Destination `error`: no offline conversion goal | The goal was deleted or belongs to another ad account | Pick the goal again from the destinations list. |
| Destination `error`: reconnect Microsoft Ads | Microsoft rejected the sign-in | Reconnect Microsoft Ads. |

## Related

- [Send events](/conversions/send-events): the unified event shape, every field.
- [Platforms](/products/conversions-api/platforms): what each platform gets from an event.
- [Microsoft Ads analytics](/platforms/microsoft-ads/analytics): conversions per campaign.