API & webhooks for developers
This is the developer-facing integration of OXIAE. With a clear REST API you submit requests, read out leads and status and drive accounts programmatically. With webhooks you receive every important event in real time on your own endpoint, signed, repeatable and idempotent.
What makes OXIAE special: with every call and every event, provenance and consent travel along by default, with a complete audit trail. So you not only build faster, you also deliver a demonstrably compliant data stream, without having to build extra infrastructure for it yourself.
What the REST API does
The OXIAE API is a predictable REST API with JSON over HTTPS, clear resources and clear error messages. You use the same API whether you submit leads as a supplier or receive leads as a buyer. Under the hood, three core resources run.
Leads
The heart of the API. Create, read and update requests, including contact details, provenance and the consent proof that belongs to every lead.
GET /v1/leads
Status
Track the lifecycle of a lead: received, verified, matched, accepted or rejected. Every status change is traceable in the audit trail.
GET /v1/leads/{id}/status
Accounts
Manage labels, buyers and suppliers programmatically. Drive routing, scopes and webhook subscriptions from your own system.
GET /v1/accounts
If you mainly submit, the Supply API is your starting point. If you receive leads, look at the Demand API. The full reference is in the documentation.
Authentication
You choose the authentication that fits your integration. In both cases you work with scopes and with separate keys per environment, so you never accidentally mix up test traffic and production.
Bearer API key
The fastest route for server-to-server integrations. Send your key along as Authorization: Bearer sk_live_…. Keys are scoped and per environment (sk_test_ for sandbox, sk_live_ for production).
OAuth 2.0
For integrations where a user grants access on behalf of an account. Walk through the OAuth flow, receive an access token and refresh it with a refresh token, with the same scopes as an API key.
Sandbox vs. live
Every environment has its own keys and its own data. In the sandbox you send unlimited test leads without consequences; only once everything checks out do you switch to your live key.
Steps, scopes and token lifetimes are described in the documentation. You revoke a leaked key instantly from your dashboard, without affecting other integrations.
Core endpoints
A handful of endpoints covers the vast majority of what you need. Everything is paginated, filterable and returns clear HTTP status codes.
| Method | Endpoint | What it does |
|---|---|---|
| POST | /v1/leads | Submit a new request, with contact, provenance and consent in a single call. Returns a lead id and the first status. |
| GET | /v1/leads | Retrieve a paginated list of leads. Filter on status, label, period or buyer with query parameters. |
| GET | /v1/leads/{id} | Read one lead in full, including the complete consent and provenance object and the associated audit events. |
| GET | /v1/leads/{id}/status | Request the current status of a lead without loading the entire payload: handy for polling as an alternative to webhooks. |
| GET | /v1/accounts | View your labels, buyers and suppliers, with the routing and scope settings that apply per account. |
| POST | /v1/webhooks | Register or manage a webhook endpoint and subscribe it to the events you need. |
Webhooks & events
Instead of polling, you let OXIAE keep your systems up to date in real time. Register an endpoint, subscribe it to the events you need and receive a signed payload the moment something happens.
A new request has arrived and has passed the first validation.
The applicant’s consent has been registered with text, timestamp, IP and source.
The lead has been linked to a buyer via the routing rules.
A payout or acceptance has been completed and booked in the audit trail.
Reliable delivery
A webhook is only valuable once it arrives, is correct and is not processed twice. That is why signing, retries, idempotency and rate limits are built in, so you do not have to solve that complexity yourself.
Signed with HMAC-SHA256
Every webhook carries the header X-OXIAE-Signature with an HMAC-SHA256 signature over the raw payload. Verify it with your endpoint secret and reject anything that does not match.
Retries with exponential backoff
If your endpoint does not respond with a 2xx, we repeat the delivery with growing intervals (a few seconds up to a few hours) for 24 hours, before the delivery is marked as failed.
Idempotency via event_id
Every event carries a unique event_id. Store processed ids and ignore repeats, so a retry never leads to duplicate processing.
Rate limits
The API applies a generous limit per API key. When you exceed it you get a 429 with a Retry-After header; respect it and fall back on exponential backoff.
This is what it looks like in code
Three concrete examples: you submit a lead with consent and provenance, you receive a signed webhook, and you verify that signature before you trust the payload.
# Submit a new lead via the REST API
curl -X POST https://api.oxiae.com/v1/leads \
-H "Authorization: Bearer sk_live_…" \
-H "Content-Type: application/json" \
-d '{
"contact": {
"name": "Sanne de Vries",
"email": "sanne@example.com",
"phone": "+31 6 12345678"
},
"provenance": {
"source": "google-ads",
"campaign": "legal-aid-q2",
"label": "legal-desk",
"landing_page": "https://request.example.com/start"
},
"consent": {
"given": true,
"text": "I give permission to be contacted.",
"timestamp": "2026-06-26T09:41:07Z",
"ip": "84.12.x.x"
}
}'
# Response
{
"id": "lead_8f21",
"status": "received",
"received_at": "2026-06-26T09:41:08Z"
}// Incoming webhook on your endpoint
// Headers:
// X-OXIAE-Event: match.found
// X-OXIAE-Signature: sha256=3a7f…b2e1
// X-OXIAE-Delivery: dlv_77c0
{
"event_id": "evt_5c93",
"type": "match.found",
"created": "2026-06-26T09:41:12Z",
"data": {
"lead_id": "lead_8f21",
"buyer_id": "buy_204",
"provenance": {
"source": "google-ads",
"campaign": "legal-aid-q2"
},
"consent": {
"given": true,
"timestamp": "2026-06-26T09:41:07Z"
}
}
}// Verify the signature before you trust the payload (Node.js)
import crypto from "node:crypto";
function verify(rawPayload, signature, secret) {
const expected = "sha256=" + crypto
.createHmac("sha256", secret)
.update(rawPayload, "utf8")
.digest("hex");
// Constant-time comparison against timing attacks
return crypto.timingSafeEqual(
Buffer.from(expected),
Buffer.from(signature)
);
}
// in your handler:
// const ok = verify(req.rawBody, req.header("X-OXIAE-Signature"), secret);
// if (!ok) return res.status(401).end();How to build your first integration
From zero to live in four clear steps. You always start in the sandbox and only switch to your live key once everything checks out.
Create an API key
Generate a scoped API key for the sandbox (sk_test_…) in your dashboard. Choose the scopes your integration needs: read only, deliver only, or both.
Make your first call
Send a POST to /v1/leads or a GET to /v1/leads with your Bearer key. You immediately see the JSON response, including lead id, status and the provenance and consent fields.
Register a webhook endpoint
Register your endpoint via POST /v1/webhooks and subscribe it to the events you need. Keep the endpoint secret to verify the X-OXIAE-Signature.
Go live
Does everything work in the sandbox? Swap your sk_test_ key for your sk_live_ key and put the integration live. From that moment, requests flow through in real time, with retries and audit trail as a safety net.
Provenance & consent travel along over the API
On this channel, compliance is not a separate track but part of the data model. Every lead resource carries a provenance and a consent object, and every event you receive via a webhook contains the same context.
When submitting
Send your consent (text, timestamp, IP) and provenance (source, campaign, label) along in the POST. OXIAE validates them and refuses a lead without valid consent.
When receiving
When you read out a lead or event, the complete consent proof is in the payload. You do not have to fetch or reconstruct it separately anywhere.
Demonstrable
Every call and delivery is logged. Via the audit trail you can prove afterwards exactly what happened to a lead.
Read more about the legal basis at consent & provenance and the exact field definitions in the documentation.
Security
An integration is only as secure as its weakest link. That is why encryption, access control and logging are the standard in OXIAE, not something you have to switch on yourself.
Encrypted over TLS
All API and webhook traffic runs exclusively over TLS 1.2 or higher. Unencrypted connections are refused, so data never travels readable over the wire.
IP allowlisting
Limit inbound API traffic to your own trusted IP addresses and receive webhooks from a fixed, published IP range that you can allowlist in your firewall.
Scoped, revocable keys
Give every integration only the scopes it needs (read only, deliver only, or both) per environment. Revoke a leaked key instantly without affecting other integrations.
Everything in the audit trail
Every call, status change and webhook delivery is logged. So afterwards you can prove exactly what happened to a lead, including provenance and consent.
Frequently asked questions about the API & webhooks
The questions developers ask most often when building on OXIAE.
Which authentication does the API support?
Server-to-server you connect with a scoped Bearer API key (Authorization: Bearer sk_live_…). For integrations where a user grants access on behalf of an account, you use OAuth 2.0 with access and refresh tokens. In both cases you work with scopes and with separate keys for sandbox and live.
What is the difference between the sandbox and the live environment?
The sandbox (keys with prefix sk_test_) has its own data and consequence-free test leads, so you can experiment without limits. Only once everything checks out do you swap for your live key (sk_live_). That way you never accidentally mix up test traffic and production.
How do I know for sure that a webhook really comes from OXIAE?
Every webhook carries the header X-OXIAE-Signature with an HMAC-SHA256 signature over the raw payload. Compute the same signature with your endpoint secret and compare in constant time. If it does not match, respond with 401 and ignore the payload.
What happens if my endpoint is temporarily unreachable?
If we do not get a 2xx back, we repeat the delivery with exponential backoff for 24 hours. Every event carries a unique event_id; store processed ids and ignore repeats, so a retry never leads to duplicate processing.
Do provenance and consent really travel along via the API?
Yes. Every lead resource carries a provenance and a consent object, and every webhook event contains the same context. When submitting, OXIAE refuses a lead without valid consent; when receiving, the complete consent proof (text, timestamp, IP) is already in the payload.
Are there rate limits?
Yes, a generous limit applies per API key. When you exceed it you get a 429 with a Retry-After header. Respect it and fall back on exponential backoff. The exact limits are in the documentation.
Can I use webhooks instead of polling?
We recommend that. Register an endpoint via POST /v1/webhooks and subscribe it to the events you need (lead.received, consent.recorded, match.found, payout.processed). If you do want to poll, you can do so via GET /v1/leads/{id}/status.
Build your first integration today
Create a sandbox key, make your first call and go live with provenance and consent delivered by default, or book a demo and let us help you on your way.