Conversions API
Parameters
Request fields for Teads Conversions API (CAPI).
Fields marked required are essential for CAPI to work as documented.
Top-level fields
| Field | Required | Description |
|---|---|---|
action | Yes | pageView, timeSpent, or conversion. |
click_id | Yes | Teads Click ID — see Getting started → Click ID for sources. Used for attribution and for the 5-minute pixel/CAPI deduplication window. |
buyer_pixel_id | Yes | Pixel ID from TAM Events Manager. Must match the website pixel and the API token used to authenticate the request. |
event_source_url | Yes | URL the user visited. Query parameters may be kept. |
privacy | Yes | Consent object (see privacy fields below). If omitted or consent_granted is missing, the event is rejected. |
user_session_id | No | Unique user+session id (UUID v4 recommended). A session lasts 30 minutes. You can reuse the pixel tfpsi cookie. |
event_time | No | Unix timestamp (seconds) of the conversion event. The current API version overrides this with the reception time. |
conversion_type | When action is conversion | Event defined in Events Manager. See types below. No spaces. |
conversion_name | When action is conversion | Generic label such as Completed Purchase. Do not use order IDs. If omitted, conversion_params.name is used (backward compatibility). |
conversion_params | No | Optional price, currency, and name (product or order id). One product name per event. |
action values
| Value | When to send |
|---|---|
pageView | Every visited page/URL. |
timeSpent | When the user leaves the page or switches tabs for the first time. Needed for sessions and qualified visits (GA4 engaged session). |
conversion | As soon as the conversion happens. Include conversion_type and conversion_name. |
conversion_type
Must match a conversion on the associated pixel:
| Type | TAM event |
|---|---|
ViewContent | View content |
Search | Search |
AddToWishlist | Add to wishlist |
AddToCart | Add to cart |
InitiateCheckout | Initiate checkout |
Lead | Lead |
CompleteRegistration | Complete registration |
Purchase | Purchase |
AppInstall | App install |
conversion_params
| Field | Type | Notes |
|---|---|---|
price | number | For example 14.54. |
currency | string | ISO 4217, for example USD. |
name | string | Product name or order ID. Not a list. Multi-item carts should use a generic conversion_name such as Completed Order. |
Pixel metadata product_name maps to CAPI conversion_params.name. Event
name and product name are limited to 100 characters in Events Manager.
privacy
| Field | Notes |
|---|---|
consent_granted | true if the user consented. false rejects the event. |
gdpr_applies | Whether GDPR applies. Send it explicitly. |
tcf_consent_string | IAB TCF v2. Required when gdpr_applies is true. |
us_privacy | IAB US Privacy (CCPA), for example 1YNN. |
gpp_string | IAB Global Privacy Platform string. |
opt_out | true for CCPA opt-out; the event is rejected. |
Teads reads partner consent signals and processes data only where consent is required and confirmed. See the FAQ → Privacy / GDPR for how consent is enforced across direct integration and server-side GTM (sGTM).