Before you start
Ensure that you have read the Getting Started with CAPI guide first, to learn more about Teads CAPI and its pre-requisites.
Overview of Requirements:
You must already have Google Analytics 4 (GA4) deployed.
Teads Conversions API token or CAPI key, generated in TAM Events Manager.
Two containers in Google Tag Manager: Web container and Server container.
A custom domain (same as your domain website) to send data from the GTM client container to the GTM server container (optional but highly recommended to improve the tracking accuracy and performance).
Implementation Steps
1. Authenticate the requests sent to Teads
You must authenticate your request with your Teads Conversions API Token, by adding a header:
Authorization: Bearer <YOUR-TOKEN>
Here is the complete request (executed here through a curl command):
curl \
-X POST \
-H 'Authorization: Bearer [YOUR-TOKEN]' \
-d'{"action":"conversion","auctid":"52d7d822-c723-47f9-82ff-c19a152562ef","auctid":"0fb681dd-c20e-4c5f-bfac-1f175fb973d0","buyer_pixel_id":3,"conversion_params":{"price":14.54,"currency":"USD","name":"Completed Purchase"},"conversion_type":"Purchase","event_source_url":"http://www.my-advertiser.com/an/amazing/product/to/buy/","event_time":1519914000}' \
'https://ca.teads.tv/v1/test/event'
Important: Teads currently cannot support multiple product names within a single conversion name. If a user makes a purchase with more than one product, please use a generic conversion name such as “Completed Purchase”.
CAPI supports the following standard event types:
ViewContent
Search
AddToWishlist
AddToCart
Lead
CompleteRegistration
Purchase
AppInstall
Note:
For accurate campaign measurement and attribution, it is mandatory to include the Click ID URL parameter with each server request.
For advertisers using 3rd party click trackers with their TAM creatives, the click ID parameter, a.k.a. auctid, may need to be manually configured to forward as outlined in this article.
2. Test connectivity with Teads Conversions API
Before sending anything to the production environment, we highly recommend testing the requests you are configuring with our provided testing environment.
Note that it will not be possible to delete an event if it is received and ingested by our pipeline, so be sure to check everything prior to deployment using the testing environment.
Endpoint is accessible at https://ca.teads.tv/v1/test/event (POST endpoint).
The testing environment returns more details than production environments in case of an incorrect payload.
Testing environment is limited to 1 request per second per token.
3. Send production data to the Teads Conversions API
You must POST events at https://ca.teads.tv/v1/event
The events must be wrapped as JSON objects as shown in the example below:
{
"action":"conversion",
"auctid":"52d7d822-c723-47f9-82ff-c19a152562ef",
"user_session_id":"0fb681dd-c20e-4c5f-bfac-1f175fb973d0",
"buyer_pixel_id":1234,
"conversion_params":{
"price":14.54,
"currency":"USD",
"name":"Completed Purchase"
},
"privacy": {
"gdpr_applies": true,
"tcf_consent_string": "CPokAsAPokAsABEACBENC7CgAP_AAH_AAAwI",
"consent_granted": true
},
"conversion_type":"Purchase",
"event_source_url":"http://www.my-advertiser.com/an/amazing/product/to/buy?sort=ASC&page=2",
"event_time":1519914000
}
Important: Teads currently cannot support multiple product names within a single conversion name. If a user makes a purchase with more than one product, please use a generic conversion name like “Completed Purchase”.
For information on the parameters supported by CAPI, refer to this article. For more details on metadata, refer to the following article here.
4. How should the events be sent via the Teads Conversions API?
The action parameter is essential to identify the type of event.
"action":"pageView" = This measures every page view, it must be triggered for each visited page/URL.
"action":"timeSpent" = This measures the time the user has spent on the page. It is crucial for measuring sessions and defining a qualified visit (also known as Engaged Session in GA4). It must be triggered when the user leaves the page or switches tabs for the first time.
"action":"conversion" = This measures relevant actions users complete on your website. It must be triggered as soon as the event is reached, and use the "conversion_params" to specify:
"name" (mandatory - unique name for the event)
"conversion_type" (mandatory - from the list of supported event types)
ViewContent
Search
AddToWishlist
AddToCart
Lead
CompleteRegistration
Purchase
AppInstall
"price" and "currency" (optional metadata parameters available).
Note:
For accurate campaign measurement and attribution, it is mandatory to include the Click ID URL parameter with each server request.
For advertisers using 3rd party click trackers with their TAM creatives, the click ID parameter, a.k.a. auctid, may need to be manually configured to forward as outlined in this article.
5. Privacy and Consent signals
To ensure compliant event tracking, you must always include the privacy object with every event. This allows Teads to verify that user consent has been collected before processing.
"consent_granted": Set to true if the user has consented to tracking. Set to false if they have not — the event will be rejected.
"gdpr_applies": Whether GDPR applies to this user. We recommend always providing it explicitly.
"tcf_consent_string": IAB TCF v2 consent string. Required when gdpr_applies is true.
"opt_out": Set to true for CCPA opt-out — the event will be rejected.
"us_privacy": IAB US Privacy string, e.g. "1YNN".
"gpp_string": IAB GPP consent string.
Important: If the privacy object is omitted or consent_granted is not provided, Teads cannot confirm user consent and the event will be rejected.