For more information about Teads Conversions API, refer to the Getting started with CAPI guide.
The following parameters are supported via Teads Conversions API.
Note: While some of these are optional, all of the parameters marked as *required are essential for Teads CAPI to work as intended.
action (*required): Must be one of the following values:
pageView
timeSpent
conversion
auctid (*required): Refers to Teads Clicks ID. It is used to attribute and deduplicate events received from both the Teads Universal Pixel (JavaScript) and the Teads Conversions API (CAPI) within a 5-minute timeframe. There are 2 ways to retrieve it:
From the URL (recommended): If a user lands on the website after clicking on a Teads ad, the URL should include the auctid= value, which refers to the Teads Click ID.
From Teads 1st Party Cookie: A first-party cookie named tfpai containing the auctid value to forward, will have been set by the Teads Universal Pixel on your website.
user_session_id (optional): This ID is used to identify all events associated with the same user immediately after interacting with a Teads ad. It should be a unique string identifier for a given user and session (we recommend using a UUID version 4). A session includes all user events within a 30 minute timeframe. You can reuse the value of the tfpsi cookie set by the Teads Universal Pixel for this purpose.
buyer_pixel_id (*required): This ID must match the one used in the pixel in TAM Events Manager, and should also match the ID of the pixel if there is one installed on the same website. The token sent with the requests must also be associated with the relevant pixel ID in TAM Events Manager.
conversion_params: Parameters related to the triggered conversion:
name (required) - note that we currently can’t support multiple product names as conversion name. For purchases with more than one product, please use a generic conversion name like “Completed Purchase”)
price (optional)
currency (optional)
conversion_type (required for a conversion action, but not for pageView or timeSpent actions)
Must be a conversion defined in TAM Events Manager for the associated pixel, and match one of the default supported event names (no spaces allowed):
ViewContent
Search
AddToWishlist
AddToCart
InitiateCheckout
Lead
CompleteRegistration
Purchase
AppInstall
event_source_url (*required): the URL visited by the user when acting. All query parameters can be kept.
event_time (optional): the timestamp in epoch seconds of the reported action. It will be overridden with reception time in the first version of Teads Conversions API (CAPI).
privacy (*required): Privacy and consent signals associated with the event. If provided, Teads will verify consent before processing any data in regions like the EU/UK. If consent cannot be confirmed, the event will be rejected.
gdpr_applies: Whether GDPR applies to this user. tcf_consent_string: IAB TCF v2 consent string. Required for GDPR regions — without it, the event will be rejected if GDPR applies.
us_privacy: IAB US Privacy string (CCPA). E.g. "1YNN".
gpp_string: IAB Global Privacy Platform (GPP) consent string.
consent_granted: Explicit consent flag from the advertiser. Set to false if the user has not consented — the event will be rejected.
opt_out: Set to true if the user has opted out of tracking (e.g. CCPA). The event will be rejected.