ads

POST /v1/ads/events

The server events API — send a conversion once; it goes to every connected network.

All ads endpoints

All developer docs →

Zinn®, our Viking, hammering at his anvil beside an API endpoint sending events to several listeners.

Authentication

Send an API key as a bearer token. The key must carry the ads.manage permission; a key without it is refused with 403, not 404.

Where your organisation id goes

This endpoint takes org_id as a query parameter. Leave it out and the call covers your whole tenancy subtree; send it to narrow the call to one organisation.

Your organisation id is on the API keys screen in your dashboard, beside the key itself. It is the same id in every call you make.

Try it

Replace anything in angle brackets with your own values, and the key placeholder with a key from your dashboard.

curl -X POST https://api.zinndigital.com/v1/ads/events \
  -H "Authorization: Bearer zdk_live_…" \
  -H "Content-Type: application/json" \
  -d '{ "events": <AdsServerEventIn[]> }'

Signed in? The API console in your dashboard fills in your real organisation id and your own key, and runs the request against the live API so you can see the actual response. Open this endpoint in the API console

Details

Gated on ads.manage; audit action ads.server_events_received. docs/1006.d/features/za-129-server-events.md, za-129. Your server sends each conversion ONCE with your own event_id; it is stored once per organisation (a retry or a double send is a duplicate, listed in duplicate_event_ids) and then fanned out, in the background, to every connected ad account of the organisation (Google Ads offline / enhanced conversions, Microsoft offline conversions, the Meta Conversions API, the X Conversion API). event_id is the transaction / event id every network receives, so no network counts one conversion twice — send the same id from your browser pixel to dedupe the pair. A plain email is SHA-256-hashed at the door and dropped; never send other personal data. consent is kept as sent: Google receives it, and Meta and X are never sent an event whose consent is DENIED. Money is integer minor units plus an ISO 4217 currency. Up to 500 events per request (no limit on requests). Uploads follow each account's tracking settings (an upload action per kind, recovery on) and stop while an account is paused or its kill switch is on, or the subscription is not in good standing — they resume by themselves. 202 when any event was new; 200 when all were duplicates. A long-lived API key (zdk_…) holding ads.manage in the organisation authenticates here.

Parameters

NameTypeRequiredWhat it is
org_id (query)stringNo—

Request body

NameTypeRequiredWhat it is
org_idstringNo—
eventsAdsServerEventIn[]Yes—

Response

NameTypeRequiredWhat it is
createdintegerYes—
duplicatesintegerYesEvents whose event_id was already stored (or repeated in this request).
duplicate_event_idsstring[]YesThe first 50 duplicate ids.
fan_out_startedbooleanYesFalse only when nothing was new, or the background fan-out could not start (it then runs with the daily step).

Errors this endpoint can return

401 · 403 · 404 · 422 · 429