Teads Developer Portal

Submit a pageView, timeSpent, or conversion event. Limited to about 20 requests per second per token. Include click_id on every request.

Authorization

BearerAuth

AuthorizationBearer <token>

CAPI token generated in TAM Events Manager (pixel → Pixel code & settings → Generate API Token).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

action*string

pageView on every visited URL. timeSpent when the user leaves the page or switches tabs the first time (qualified visits). conversion when the user completes a defined action.

Value in

"pageView"
"timeSpent"
"conversion"

click_id*string

Teads Click ID. From the landing URL (click_id=) or the tfpai first-party cookie set by the Teads Universal Pixel. Required for attribution and 5-minute pixel/CAPI deduplication.

user_session_id?string

Optional session identifier (UUID v4 recommended). Groups events for 30 minutes. Can reuse the tfpsi cookie from the pixel.

buyer_pixel_id*integer

Pixel ID from TAM Events Manager. Must match the website pixel and the token.

conversion_type?ConversionType

Required when action is conversion. Must be a conversion defined in TAM Events Manager for the pixel. No spaces.

Value in

"ViewContent"
"Search"
"AddToWishlist"
"AddToCart"
"InitiateCheckout"
"Lead"
"CompleteRegistration"
"Purchase"
"AppInstall"

conversion_name?string

Generic identifier for the conversion, such as Completed Purchase. Required when action is conversion. Do not use order IDs. If omitted, conversion_params.name is used (backward compatibility).

conversion_params?

Optional conversion metadata. One product name per event.

event_source_url*string

URL the user visited. Query parameters may be kept.

Formaturi

event_time?integer

Unix timestamp (seconds) of the action. The first CAPI version overrides this with reception time.

privacy*

Consent signals. Teads processes data only where consent can be confirmed. Omit the object or set consent_granted false to reject the event.

Response Body

`application/problem+json`

curl -X POST "https://example.com/event" \  -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": 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  }'

Empty

Send a production event

Authorization

Request Body

Response Body

200

400application/problem+json

401

429

500

`application/problem+json`