📘
This integration is currently in beta. Contact your MetaRouter support team to get started.

What Is Teads?

Teads is a global advertising platform specializing in outstream video and display ads that appear within premium publisher content. They work with major media outlets to deliver high-quality, brand-safe inventory across desktop, mobile web, and in-app environments. Teads offers both direct and programmatic buying options, with advanced targeting, viewability optimization, and measurement tools. Advertisers can run campaigns focused on awareness, engagement, or conversions, and track performance through Teads’ analytics and reporting suite. Their technology is designed to provide a non-intrusive ad experience while maximizing reach and engagement.

Product Type: Advertising
Integration Type: Starter Kit & ID Sync
Event Source Type: Web
Event Scope: Full-Funnel Events

Capabilities

Sends conversion and engagement events directly to Teads via the Conversions API.
Captures the Teads click ID (auctid) from the landing-page URL for attribution.
Supports full-funnel events including page, product, cart, checkout, and purchase lifecycle actions.

Considerations

A CAPI token must be created in the TAM Events Manager before setup.
The auctid click ID is mandatory to send a request. This parameter is added automatically by TAM when creatives are configured and is captured by the Teads CAPI sync.
Teads cannot support multiple products for the conversion name. If a user purchases more than one product, a generic conversion name such as "New Purchase" is used.
A valid event requires the auctid identifier to be present; events without it are filtered out.
Authentication uses a Bearer token supplied through the CAPI token.
Before sending production data, test requests using the Teads testing environment, which returns more detailed responses for incorrect payloads. The testing environment is limited to 1 request per second per token.
Events ingested by the production pipeline cannot be deleted.
A separate Teads (postback URL) integration is available and is intended for managed service. If you work with Teads through a managed service, your Teads representative can advise on which integration best fits your setup.

Limitations

A single conversion name cannot represent multiple products; multi-product purchases must use a generic conversion name.

Identity Sync

Sync Available: Yes
Required for Starter Kit: Yes
Prerequisites: Configured TAM creatives to populate the auctid URL parameter
Documentation: See Additional Teads CAPI Sync Documentation

Sync Details

Captures the Teads click ID (auctid) from the landing-page URL.
Stores the click ID in first-party storage for a configurable cookie lifetime.
Appends the resolved click ID to server-side events under context.providers.teadsCAPI.
Required to associate conversion events with prior Teads ad clicks.

Starter Kit Setup Guide

1. Deploy the Teads Sync

To collect the sync values (e.g., auctid), you must implement a Teads ID sync. Refer to the following documentation to complete the setup: Teads CAPI - ID Sync Guide.

2. Gather Credentials

Ask vendor representatives for the following credentials:
- CAPI Token: Create a token (CAPI key) in the TAM Events Manager.
- Buyer Pixel ID: Provided by your Teads representative.

3. Add a Teads Integration

From the integration library, add a Teads integration. Then, fill out the Connection Parameters:

Connection Parameter	Description
`CAPI_TOKEN`	Sensitive Bearer token used to authenticate API requests. Create this token in the TAM Events Manager.
`BUYER_PIXEL_ID`	Buyer pixel identifier for the destination Teads account, included in event payloads.

4. Configure Event Mapping

MetaRouter provides all of the event mappings that Teads integrations typically require. You may add custom events, parameters, or mappings in accordance with Teads's API documentation.

5. Deploy to Pipeline

In the Pipelines tab, add your Teads integration.
Select the correct integration revision.
Click Add Integration to finalize deployment.

Event Mappings

Global

Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.

Output Key	Description	Expected Input
`auctid` Required	String: Teads click ID captured by the sync, used for attribution.	`context.providers.teadsCAPI.auctid`
`event_source_url`	String: Page URL where the event occurred.	`context.page.url`
`user_session_id`	String: Anonymous visitor ID used for session linking.	`anonymousId`
`event_time`	Integer: Event timestamp in seconds (UTC).	Expression – convert RFC3339 timestamp to epoch
`buyer_pixel_id`	Integer: Buyer pixel identifier for the destination account.	$$BUYER_PIXEL_ID$$

Event Specific

Page

Output Key	Description	Expected Input
`action` Required	String: Event action type.	Enrichment – `'pageView'`

Products Searched

Output Key	Description	Expected Input
`action` Required	String: Event action type.	Enrichment – `'conversion'`
`conversion_type` Required	String: Teads conversion type.	Enrichment – `'Search'`
`conversion_params.name`	String: Conversion name for reporting.	Enrichment – `'Products Searched'`

Product List Viewed

Output Key	Description	Expected Input
`action` Required	String: Event action type.	Enrichment – `'conversion'`
`conversion_type` Required	String: Teads conversion type.	Enrichment – `'ViewContent'`
`conversion_params.name`	String: Conversion name for reporting.	Enrichment – `'Product List Viewed'`
`conversion_params.price`	Float: Calculated total value from product properties.	Expression – `TOTAL_VALUE(input.properties.products)`
`conversion_params.currency`	String: ISO 4217 currency code.	`properties.currency` (uppercase, default USD)

Product Clicked

Output Key	Description	Expected Input
`action` Required	String: Event action type.	Enrichment – `'conversion'`
`conversion_type` Required	String: Teads conversion type.	Enrichment – `'ViewContent'`
`conversion_params.name`	String: Conversion name for reporting.	Enrichment – `'Product Clicked'`
`conversion_params.price`	Float: Price of the clicked product.	`properties.price`
`conversion_params.currency`	String: ISO 4217 currency code.	`properties.currency` (uppercase, default USD)

Product Viewed

Output Key	Description	Expected Input
`action` Required	String: Event action type.	Enrichment – `'conversion'`
`conversion_type` Required	String: Teads conversion type.	Enrichment – `'ViewContent'`
`conversion_params.name`	String: Conversion name for reporting.	Enrichment – `'Product Viewed'`
`conversion_params.price`	Float: Price of the viewed product.	`properties.price`
`conversion_params.currency`	String: ISO 4217 currency code.	`properties.currency` (uppercase, default USD)

Product Added

Output Key	Description	Expected Input
`action` Required	String: Event action type.	Enrichment – `'conversion'`
`conversion_type` Required	String: Teads conversion type.	Enrichment – `'AddToCart'`
`conversion_params.name`	String: Conversion name for reporting.	Enrichment – `'Product Added'`
`conversion_params.price`	Float: Price of the added product.	`properties.price`
`conversion_params.currency`	String: ISO 4217 currency code.	`properties.currency` (uppercase, default USD)

Cart Viewed

Output Key	Description	Expected Input
`action` Required	String: Event action type.	Enrichment – `'conversion'`
`conversion_type` Required	String: Teads conversion type.	Enrichment – `'AddToCart'`
`conversion_params.name`	String: Conversion name for reporting.	Enrichment – `'Cart Viewed'`
`conversion_params.currency`	String: ISO 4217 currency code.	`properties.currency` (uppercase, default USD)
`conversion_params.price`	Float: Calculated total value from cart products.	Expression – `TOTAL_VALUE(input.properties.products)`

Checkout Started

Output Key	Description	Expected Input
`action` Required	String: Event action type.	Enrichment – `'conversion'`
`conversion_type` Required	String: Teads conversion type.	Enrichment – `'Purchase'`
`conversion_params.name`	String: Conversion name for reporting.	Enrichment – `'Checkout Started'`
`conversion_params.currency`	String: ISO 4217 currency code.	`properties.currency` (uppercase, default USD)
`conversion_params.price`	Float: Calculated total value from product properties.	Expression – `TOTAL_VALUE(input.properties.products)`

Payment Info Entered

Output Key	Description	Expected Input
`action` Required	String: Event action type.	Enrichment – `'conversion'`
`conversion_type` Required	String: Teads conversion type.	Enrichment – `'Purchase'`
`conversion_params.name`	String: Conversion name for reporting.	Enrichment – `'Payment Info Entered'`

Order Completed

Output Key	Description	Expected Input
`action` Required	String: Event action type.	Enrichment – `'conversion'`
`conversion_type` Required	String: Teads conversion type.	Enrichment – `'Purchase'`
`conversion_params.name`	String: Conversion name for reporting.	Enrichment – `'New Purchase'`
`conversion_params.currency`	String: ISO 4217 currency code.	`properties.currency` (uppercase, default USD)
`conversion_params.price`	Float: Calculated total value from product properties.	Expression – `TOTAL_VALUE(input.properties.products)`

Promotion Clicked

Output Key	Description	Expected Input
`action` Required	String: Event action type.	Enrichment – `'conversion'`
`conversion_type` Required	String: Teads conversion type.	Enrichment – `'ViewContent'`
`conversion_params.name`	String: Conversion name for reporting.	Enrichment – `'Promotion Clicked'`

Promotion Viewed

Output Key	Description	Expected Input
`action` Required	String: Event action type.	Enrichment – `'conversion'`
`conversion_type` Required	String: Teads conversion type.	Enrichment – `'ViewContent'`
`conversion_params.name`	String: Conversion name for reporting.	Enrichment – `'Promotion Viewed'`

Required & Recommended Identifiers

These identifiers must be mapped to Teads in order for successful user matching to occur. Without these IDs, any events sent to Teads may not be accurately reflected in reporting.

Attribute	Example	Sync Injector Required?
`auctid` Required	`campaignTag-preview_a8db716c-1230-404f-a201-62cdcddf6ed9`	Yes
`user_session_id`	`b171a9b06ce011ecafcd1b209be8601b`	No

Integration Validation

Validation can include testing requests against the Teads testing environment (https://ca.teads.tv/v1/test/event) before sending production data, as it returns more detailed responses for incorrect payloads and helps confirm your payload structure is correct. Pointing the integration at the testing endpoint requires assistance from your MetaRouter contact.

Note that the testing environment is limited to 1 request per second per token, and once events are ingested by the production pipeline they cannot be deleted.

Coordinate with your Teads representative to confirm that events are being received and processed correctly on their backend.