Yahoo is a global digital media and advertising company that operates a demand-side platform (DSP) for programmatic advertising across web, mobile, native, video, and connected TV inventory. The Yahoo DSP provides advertisers with audience targeting, campaign optimization, and conversion measurement tools powered by Yahoo ConnectID. The Yahoo Conversion API (CAPI) enables advertisers to send web and app conversion events directly to the Yahoo DSP server-to-server, serving as a direct replacement for Yahoo Dot pixels while using the same rules engine and attribution configured in a Yahoo DSP seat. By transmitting events server-side, Yahoo CAPI supports privacy-conscious measurement and improves resilience against browser-based tracking limitations.
Product Type: Advertising
Integration Type: Starter Kit & ID Sync
Event Source Type: Web and Mobile App
Event Scope: Full-Funnel Events
- Sends server-side conversion and engagement events directly to the Yahoo DSP via the Conversion API.
- Supports batching of events per request.
- Captures the Yahoo click identifier (
vmcid) for post-click attribution.
- Transmits hashed user identifiers (email, phone) and mobile advertising identifiers (
idfa, gpsaid) for user matching.
- Communicates GDPR and opt-out privacy signals alongside each event.
- Supports full-funnel events including product, cart, checkout, and order lifecycle actions.
- At least one user identifier (email, phone, device ID, or IP address) or a click identifier (
vmcid) is required for event matching. Sending multiple identifiers improves match rates.
- Email values must be trimmed, lowercased, and SHA-256 hashed, with the resulting hash in lowercase.
- Phone values must be normalized and SHA-256 hashed.
- Mobile advertising identifiers (
idfa for iOS, gpsaid for Android) are sent in their raw form and are selected based on device type.
- The action source is determined automatically as
app or web based on the presence of context.app.name, context.device.type, or context.os.name.
- The
country field is sent in Yahoo's expected two-character ISO format (e.g., US).
- The integration supports two of Yahoo's three privacy modes, determined automatically by the presence of a TCF consent string:
OPTOUT (default): Applied when no TCF consent string is present on the event. Excludes the user from optimization and does not include a consent string.GDPR: Applied when a TCF consent string is present at context.consent.tcf.tcString. The consent string is passed through as privacy.consent_string.
- Product events accept only a single category despite the array format; sending more than one category returns an error.
- The event timestamp cannot be set in the future or older than 30 days, or the event will be rejected.
- Yahoo's batch endpoint enforces a rate limit of 200 requests per second. The integration defaults to a batch size of 100 events per request to stay well under this limit.
- A
200 response does not guarantee that every event succeeded. Yahoo returns a COMPLETE or PARTIAL result, and partial responses include a breakdown of error types and counts that should be reviewed to confirm processing.
- Authentication uses an OAuth 2.0 client-credentials flow with a JWT client assertion. Credentials must be provisioned with Yahoo before events can be sent.
- It is recommended to not reuse a pixel ID that is currently in use on a site, to avoid duplicate conversion counts.
- The
vmcid click identifier is web-only and is sourced by the sync injector; it is not available on mobile. Mobile events still deliver using other identifiers such as email and phone.
- Individual events within a batch may fail even when the request returns a
200 status; there is no per-event identifier in the response, only aggregated error-type counts.
- Sync Available: Yes
- Required for Starter Kit: Yes
- Prerequisites: N/A
- Documentation: See Additional Yahoo CAPI Sync Documentation
- Captures the Yahoo click identifier (
vmcid) from a URL parameter.
- Stores the click identifier in first-party storage for a configurable lifetime.
- Attaches the resolved click identifier to server-side events for post-click attribution.
- CLIENT_ID and CLIENT_SECRET: Request these from your Yahoo representative. Provisioning requires generating a key pair and exchanging it with Yahoo; follow Yahoo's instructions here: Request Client Credentials
- PIXEL_ID: Create a Pixel ID in the Yahoo DSP under your Advertiser's Tracking tab. Follow Yahoo's instructions here: Create a Pixel ID
- From the integration library, add a Yahoo CAPI integration. Then, fill out the Connection Parameters:
| Connection Parameter | Description |
|---|
OAUTH2_REQUEST_URL | Authorization endpoint used to request the OAuth 2.0 access token. Defaults to Yahoo's production endpoint. Only change this if directed by Yahoo. |
CLIENT_ID | Client ID used to sign the JWT client assertion and request the access token. |
CLIENT_SECRET | Client secret used as the JWT signing key. |
PIXEL_ID | Pixel identifier used in the events endpoint path. |
- MetaRouter provides all of the event mappings that Yahoo CAPI integrations typically require. You may add custom events, parameters, or mappings in accordance with Yahoo's API documentation.
- In the Pipelines tab, add your Yahoo CAPI integration.
- Select the correct integration revision.
- Click Add Integration to finalize deployment.
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 |
|---|
eventTs Required | Integer: Event timestamp in seconds. | Expression – converts timestamp to seconds |
actionSource Required | String: Source of the event (app or web), derived from app, device, or OS context. | Expression – returns 'app' when app/device/OS context is present, else 'web' |
eventName Required | String: Normalized event name for track events, or the event type. | Expression – lowercases and replaces spaces with underscores in input.event, or returns input.type |
userData Required | Object: User identifiers for matching. Includes hashed email/phone, idfa/gpsaid by device type, IP address, and user agent. | Expression – builds from traits.email, traits.phone, context.device.advertisingId, context.ip, context.userAgent |
actionSourceUrl | String: URL where the event occurred. | context.page.url |
country | String: Two-character ISO country code (e.g., US) derived from location context. | Expression – converts context.location.country to ISO |
privacy | Object: Consent state. Sets GDPR with TCF consent string when available, otherwise OPTOUT. | Expression – builds from context.consent.tcf.tcString |
clickData.vmcid | String: Yahoo click identifier captured by the sync. | context.providers.yahooCAPI.vmcid |
| Output Key | Description | Expected Input |
|---|
actionSourceUrl | String: URL where the page event occurred. | properties.url |
| Output Key | Description | Expected Input |
|---|
eventData.price | Float: Total value calculated from product properties. | Expression – TOTAL_VALUE(input.properties.products) |
| Output Key | Description | Expected Input |
|---|
eventData.price | Float: Total value calculated from product properties. | Expression – TOTAL_VALUE(input.properties) |
eventData.products | Array: Product details including a single subcategory; only one category is accepted. | Expression – maps properties.category to subCategory |
| Output Key | Description | Expected Input |
|---|
eventData.price | Float: Total value calculated from product properties. | Expression – TOTAL_VALUE(input.properties) |
eventData.products | Array: Product details including a single subcategory; only one category is accepted. | Expression – maps properties.category to subCategory |
| Output Key | Description | Expected Input |
|---|
eventData.price | Float: Total value calculated from product properties. | Expression – TOTAL_VALUE(input.properties) |
eventData.products | Array: Product details including a single subcategory; only one category is accepted. | Expression – maps properties.category to subCategory |
| Output Key | Description | Expected Input |
|---|
eventData.price | Float: Total value calculated from product properties. | Expression – TOTAL_VALUE(input.properties) |
eventData.products | Array: Product details including a single subcategory; only one category is accepted. | Expression – maps properties.category to subCategory |
| Output Key | Description | Expected Input |
|---|
eventData.price | Float: Total cart value calculated from product properties. | Expression – TOTAL_VALUE(input.properties.products) |
| Output Key | Description | Expected Input |
|---|
eventData.price | Float: Checkout value. | properties.value |
| Output Key | Description | Expected Input |
|---|
eventData.price | Float: Final order total. | properties.total |
| Output Key | Description | Expected Input |
|---|
eventData.price | Float: Total value calculated from product properties. | Expression – TOTAL_VALUE(input.properties) |
eventData.products | Array: Product details including a single subcategory; only one category is accepted. | Expression – maps properties.category to subCategory |
| Output Key | Description | Expected Input |
|---|
eventData.price | Float: Updated order total. | properties.total |
| Output Key | Description | Expected Input |
|---|
eventData.price | Float: Refunded order total. | properties.total |
| Output Key | Description | Expected Input |
|---|
eventData.price | Float: Canceled order total. | properties.total |
These identifiers must be mapped to Yahoo in order for successful user matching to occur. Without these IDs, any events sent to Yahoo may not be accurately reflected in reporting.
| Attribute | Example | Sync Injector Required? |
|---|
vmcid Recommended | foo-123 | Yes |
email Recommended | b4c9a289323b21a01c3e940f150eb9b8c542587f1abfd8f0e1cc1ffc5e475514 | No |
phone Recommended | e1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1a2 | No |
idfa Recommended | AEBE52E7-03EE-455A-B3C4-E57283966239 | No |
gpsaid Recommended | 38400000-8cf0-11bd-b23e-10b96e40000d | No |
- Review the API response for each request. A 200 status alone does not confirm success: Yahoo returns either COMPLETE, meaning all events were ingested, or PARTIAL, meaning some events were rejected. For PARTIAL responses, review the breakdown of error types and counts to identify what failed.
- Because responses report only aggregated error-type counts and no per-event identifier, individual events within a batch can fail without being individually traceable in the response. Use the error-type breakdown to diagnose systemic issues.
- Coordinate with your Yahoo representative to confirm that events are being received and processed correctly on Yahoo's backend.
