Conversions API
Direct integration
POST JSON events to the Teads Conversions API.
Send JSON from your backend. Read Getting started first and generate a CAPI token in Events Manager.
Authentication
Requests use the static API token described in
Getting started → Authentication,
sent as the standard Authorization header:
Authorization: Bearer <your-capi-token>
Content-Type: application/jsonEndpoints
| Environment | Method | URL | Rate limit |
|---|---|---|---|
| Test | POST | https://ca.teads.tv/v1/test/event | ~1 request / second / token |
| Production | POST | https://ca.teads.tv/v1/event | ~20 requests / second / token |
Test returns more detail on invalid payloads. Events cannot be deleted after ingest, so validate on test first.
Test request
curl \
-X POST \
-H 'Authorization: Bearer <your-capi-token>' \
-H 'Content-Type: application/json' \
-d '{
"action": "conversion",
"click_id": "52d7d822-c723-47f9-82ff-c19a152562ef",
"user_session_id": "0fb681dd-c20e-4c5f-bfac-1f175fb973d0",
"buyer_pixel_id": 3,
"conversion_type": "Purchase",
"conversion_name": "Completed Purchase",
"conversion_params": {
"price": 14.54,
"currency": "USD",
"name": "Blue T-Shirt SFRED1451"
},
"privacy": {
"gdpr_applies": true,
"tcf_consent_string": "CPokAsAPokAsABEACBENC7CgAP_AAH_AAAwI",
"consent_granted": true
},
"event_source_url": "http://www.my-advertiser.com/an/amazing/product/to/buy/",
"event_time": 1519914000
}' \
'https://ca.teads.tv/v1/test/event'Production payload
{
"action": "conversion",
"click_id": "52d7d822-c723-47f9-82ff-c19a152562ef",
"user_session_id": "0fb681dd-c20e-4c5f-bfac-1f175fb973d0",
"buyer_pixel_id": 1234,
"conversion_type": "Purchase",
"conversion_name": "Completed Purchase",
"conversion_params": {
"price": 14.54,
"currency": "USD",
"name": "Blue T-Shirt SFRED1451"
},
"privacy": {
"gdpr_applies": true,
"tcf_consent_string": "CPokAsAPokAsABEACBENC7CgAP_AAH_AAAwI",
"consent_granted": true
},
"event_source_url": "http://www.my-advertiser.com/an/amazing/product/to/buy?sort=ASC&page=2",
"event_time": 1519914000
}Include click_id on every request. Multi-item purchases should use a
generic conversion_name such as Completed Order — CAPI does not accept
multiple product names in one event.
Status codes
| HTTP | Meaning |
|---|---|
200 | Event received and sent to the pipeline. |
400 | Missing or incorrect payload (RFC 7807). |
429 | Too many requests. |
5xx | Unexpected error. Retry. |
Field definitions: Parameters.