Send DealOracle a conversion from your backend. We attach the ad identity the visitor left in their browser — the Meta and Google click IDs, their real IP and user agent — and forward the completed event to every ad platform you have connected.
Why not post to the ad platforms yourself? Your server knows the money. The browser knew the ad. Without fbc and fbp, the platforms receive a sale they cannot credit to a campaign. We store those from the pixel and join them to your order.
This is the online lane: events default to action_source: "website", so Meta counts them as website conversions. Offline and CRM conversions (a phone sale, a status change in your CRM) keep flowing through the Leads API — the two lanes are separate on purpose.
Endpoint
POST https://api.dealoracle.io/functions/v1/server-events
X-Api-Key: <your account API key>
Content-Type: application/json
It is the same API key the Leads API uses. You will find it in the app under Integrations > Webhooks (the "API, MCP & Webhooks" page), in the API Key section.
The whole request
{
"user_data": { "email": "[email protected]", "phone": "+1 252 531 2453" },
"custom_data": { "value": 240, "order_id": "RC-10482" }
}
That is it. event_name defaults to Purchase, event_time defaults to now, and currency defaults to USD. Add client_id when your API key owns more than one client account (agency keys usually do) — without it the call returns 400. From the email and phone we find that person's pixel history, pull their ad click IDs and device details, and send the conversion.
order_id is optional but strongly recommended — it is the deduplication key. Use whatever unique order identifier your own system already has.
What one call does
- Sends the conversion to every ad platform you have connected, enriched with the click IDs and device details from that person's visit.
- Creates or updates the lead in Lead Manager, attributed to the campaign and ad that produced them, with first and last touch recorded.
- Records the revenue on that lead, which feeds the revenue, AOV and LTV figures on your Oracle dashboard.
Response
{
"ok": true,
"duplicate": false,
"event_id": "srv:Purchase:RC-10482",
"value": 240,
"currency": "USD",
"matched_visitor": true,
"matched_by": "email",
"enriched": ["fbc", "fbp", "client_ip_address", "client_user_agent"],
"provided_by_you": ["gclid"],
"lead_id": "8f3c...",
"lead_created": false,
"revenue_recorded": true,
"dispatched": true
}
enriched is exactly what we added that your payload did not have. matched_visitor: false means we could not find that person in the pixel data — the event still goes out, with only what you sent.
Optional fields
| Field | Notes |
|---|---|
client_id | Required when your API key owns more than one client account (agency keys usually do). Omit it only when the key owns exactly one. |
event_name | Defaults to Purchase. Use Lead, InitiateCheckout, or any event you have mapped. |
event_time | Unix seconds, milliseconds, or ISO 8601. Must be within the last 7 days — Meta rejects an entire request containing anything older. |
event_source_url | The page the conversion happened on. We fall back to the visitor's last known page. |
action_source | Defaults to website. Only change it if the conversion genuinely happened elsewhere. |
custom_data.currency | Defaults to USD. |
test_mode | true validates and enriches, and sends nothing anywhere. Use it for your first call. |
You can also pass click IDs you already hold (fbc, fbp, fbclid, gclid, ttclid, msclkid, client_ip_address, client_user_agent) inside user_data. Yours always win — we only fill in what you do not have.
Deduplication
Send the same order_id twice and the second call returns duplicate: true with nothing sent, for 30 days. Redeliver your webhooks freely — a retry can never become a second conversion.
Errors
| Status | Meaning |
|---|---|
| 401 | Missing or invalid API key |
| 403 | That key does not own the client_id |
| 404 | Unknown client_id |
| 422 | Validation failed — the errors array names each problem |
| 429 | Rate limited (120 requests per minute) |
Before you go live
Events only reach a platform when an event mapping exists for that event_name on your account (Conversion Setup, on the Event Streams page). If nothing is mapped, the call succeeds and reports that nothing was dispatched — check your mappings first.
Start with "test_mode": true. The response shows exactly which click IDs we would attach to that customer, without sending anything.