Getting started

The Teads Conversions API (CAPI) shares conversion event data with Teads over a server-to-server connection. It is an alternative and a complement to pixel-based collection.

Why CAPI

• More accurate post-click conversions for optimization.
• Cookieless-ready: first-party cookies and Teads Click IDs, not third-party cookies.
• Server-side delivery bypasses browser ad blockers.
• Works when a JavaScript pixel is not viable.

CAPI tracks the same post-click event types as the pixel (visits, qualified visits, page views, bounce, time spent, and conversion events). Post-view measurement still requires the Teads Pixel.

Prerequisites

• Stay compliant with local privacy rules (for example GDPR consent). CAPI uses an analytics cookie for measurement, not a marketing cookie.
• Every event needs a Teads Click ID (click_id, also called auctid on creatives). If you use a third-party click tracker, forward the Click ID during creative setup.
• Desktop and mobile web only. CAPI does not support in-app events.

Authentication

CAPI requests carry a static API token in the standard Authorization request header (see the HTTP authentication overview for how such credentials are conventionally presented). This token is a static API credential scoped to a single pixel — it is not an OAuth 2.0 client credentials token or a JWT, and it does not expire on its own.

Generate a token

1. Open TAM Events Manager.
2. Find the pixel you want to connect.
3. Open Pixel code & settings (or API Conversions Available if that button is shown).
4. Click Generate API Token. If the option is missing, ask your Teads account manager.
5. Copy the token. You can rename or delete tokens from the same view.

The token must belong to the same pixel as buyer_pixel_id on every request. This token is not a TAM Reporting API key (Settings → API Keys) — the two are not interchangeable.

Authorization: Token <your-capi-token>
Content-Type: application/json

Both direct integration and server-side GTM (sGTM) use this same token and header.

Choose an integration

Test against the test endpoint (https://ca.teads.tv/v1/test/event) before sending to production (https://ca.teads.tv/v1/event) — see Endpoints for full details. Ingested events cannot be deleted.

Click ID

click_id is required on every request. Sources:

1. Landing URL (recommended): click_id= after a Teads ad click.
2. First-party cookie tfpai, set by the Teads Universal Pixel.

Without Click ID, CAPI cannot attribute the visit to a Teads ad.

If creatives send users through a third-party click tracker (Campaign Manager 360, Adform, and similar), configure Click ID forwarding in TAM Creative Editor so auctid reaches the landing page. Flashtalking forwards automatically. Direct landings need no extra setup.

Deduplication with the pixel

When both the JavaScript pixel and CAPI fire for the same Teads Click ID within 5 minutes, Teads keeps one post-click event.

Dedup only applies across different environments (browser vs server) for a similar event. Example: 1 pixel conversion + 2 CAPI conversions with the same Click ID in 5 minutes → 1 of those is dropped (the client/server pair). You still keep the extra CAPI-only event.

Event types

CAPI can send:

• Visits / qualified visits (via pageView + timeSpent)
• Page view of URL, bounce rate, time spent
• Conversion events: ViewContent, Search, AddToWishlist, AddToCart, InitiateCheckout, Lead, Purchase, CompleteRegistration, AppInstall

Those conversion types must already exist on the pixel in Events Manager (no spaces in the type name).