Conversion API

Send conversions to Thrad directly from your backend — the most reliable path, since it bypasses the browser entirely.

Unlike the Tag’s conversion call, the server endpoint trusts you via your API key instead of a signed click — so you don’t need to pass sig / exp. You do need to pass the click_id your site captured on landing (we use it to join the conversion back to the original ad).

Endpoint

POST https://events.thrad.ai/api/conversion
Authorization: Bearer <YOUR_API_KEY>
Content-Type: application/json
Idempotency-Key: order_123          ← optional but recommended

Request

curl -X POST https://events.thrad.ai/api/conversion \
  -H "Authorization: Bearer $THRAD_API_KEY" \
  -H "Idempotency-Key: order_123" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id":         "clk_xyz",
    "conversion_time":  "2026-05-26T12:34:56Z",
    "conversion_value": 99.99,
    "currency":         "USD",
    "order_id":         "order_123",
    "event_type":       "purchase_completed"
  }'

Body

Field	Type	Required	Notes
`click_id`	string	yes	The click ID captured by the Tag on the original landing URL.
`conversion_time`	ISO-8601 datetime	yes	When the conversion happened.
`conversion_value`	number	yes	Monetary value of the conversion.
`currency`	string (3)	yes	3-letter ISO (`USD`, `EUR`, …).
`event_type`	string	no	Defaults to `"purchase_completed"`. Use other names for non-purchase conversions (`subscription_created`, `trial_started`, `lead_created`, …).
`order_id`	string	recommended	Used for deduplication when no `Idempotency-Key` is sent.
`event_id`	string	no	Explicit dedup key. The `Idempotency-Key` header takes precedence if both are sent.
`tag_id`	string	no	Override if you operate multiple tags under one partner key.
`page_url`, `referrer`, `user_agent`	string	no	Browser context, when known.
`session_id`, `client_id`	string	no	Your stable user identifiers.

Any additional keys are accepted and stored under params.extra.

Response

{ "status": "ok" }

Or, when a duplicate is detected:

{ "status": "duplicate" }

Deduplication

Two layers, in priority order:

Idempotency-Key header — strongest. The same key + click_id + event_type within the dedup window returns duplicate and writes nothing.
order_id — used as a fallback dedup key when no idempotency header is sent. This makes retries of a payment-webhook handler safe.

Always send one of the two. Without either, a retried HTTP request will create a second conversion row.

Errors

Status	Body	Cause
`401`	`Missing bearer token` / `Invalid API key`	Auth. See Authentication.
`404`	`Click not found`	The `click_id` you sent doesn’t exist in our click store.
`400`	`Click missing bid id`	The click record exists but can’t be attributed to a bid.
`422`	Pydantic validation error	Required field missing or wrong type.

Events API