> ## Documentation Index
> Fetch the complete documentation index at: https://docs.narrative.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Yahoo Conversions API Connector
> Send conversion events to Yahoo DSP for ad attribution and campaign optimization
The Yahoo Conversions API (CAPI) Connector sends conversion events from Narrative directly to Yahoo's conversion ingestion API, enabling Yahoo DSP to attribute conversions back to ad campaigns and optimize delivery against real outcomes.
## Overview
The connector routes conversion data — purchases, signups, leads, and more — from any dataset in Narrative to a Yahoo pixel (dot tag). Events are matched against Yahoo user accounts using hashed emails, hashed phone numbers, mobile advertising IDs, and Yahoo PXIDs.
Events are batched and delivered on a schedule you configure. PII fields are SHA-256 hashed before transmission in accordance with Yahoo's requirements.
The Conversions API is a second interface of the same Yahoo app that delivers [audiences](/reference/connectors/yahoo-dsp) — one installed connector, one profile, two delivery paths.
## Prerequisites
* A **Yahoo DSP account** with a pixel (dot tag) configured. The pixel's numeric ID is where your events are delivered.
* A Narrative dataset containing the conversion data you want to send.
## Sending conversion events
Delivering conversion events to Yahoo involves three steps: creating a connector profile, preparing your dataset, and adding a connection.
### Step 1: Create a connector profile
If you already deliver audiences through the Yahoo DSP Connector, you can reuse your existing profile and skip this step.
In Narrative, go to **Installed Apps** and select **Yahoo DSP Connector**.
Enter your Yahoo DSP API credentials.
### Step 2: Create your dataset
Your dataset must be mapped to the [`conversion_event`](https://app.narrative.io/platform/rosetta-stone/attributes/conversion_event) Rosetta Stone attribute. The recommended approach is to map your source data to this attribute and then materialize it using Data Studio or NQL.
The connector requires your dataset to include `conversion_event` **and** at least one [supported user identifier](#supported-user-identifiers) for user matching. Any dataset that contains the required attributes in the correct schema is eligible for delivery.
See the [attribute schema](#the-conversion_event-attribute) below for the full list of event fields, and [Supported user identifiers](#supported-user-identifiers) for the identity attributes your dataset must include.
### Step 3: Add a connection
Navigate to the Yahoo connector profile you created in Step 1.
Click **Add Connection** and select **Deliver Conversion Events** as the connection type.
* **Pixel ID** *(optional)* — A default Yahoo pixel ID to deliver events to. Rows that carry their own `yahoo_pixel_id` route to that pixel instead.
* **Deliver all data** — Toggle on to deliver all data currently in the dataset. If off, only new data written after the connection is created will be delivered.
Click **Connect** to activate. Events will begin delivering on the next scheduled run.
## The `conversion_event` attribute
The [`conversion_event`](https://app.narrative.io/platform/rosetta-stone/attributes/conversion_event) attribute is Narrative's platform-neutral Rosetta Stone schema for conversion events. When you map your dataset columns to this attribute, Narrative handles transformation, hashing, batching, and delivery to Yahoo's API.
### Fields
| Narrative Field | Type | Required | Description |
| -------------------------------- | ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `yahoo_pixel_id` | `long` | **Yes**\* | The Yahoo pixel (dot tag) ID to deliver events to. Each row routes to the pixel it names. *Optional per row if a default Pixel ID is set on the connection.* |
| `event_id` | `string` | **Yes** | Unique string for deduplication. Use an order number, transaction ID, or random string. |
| `event_name` | `string` | **Yes** | The type of conversion event, matching the event names configured in your Yahoo DSP account. |
| `event_timestamp` | `timestamptz` | **Yes** | Timestamp when the event occurred. |
| `source` | `string` | **Yes** | Where the conversion occurred (action source). |
| `price.value` | `double` | **Yes** | Monetary value of the conversion. |
| `category` | `string` | No | Product category of the conversion. |
| `sub_category` | `string` | No | Product sub-category of the conversion. |
| `postal_address.address_region` | `string` | No | Region or state where the event occurred. |
| `postal_address.address_country` | `string` | No | Country where the event occurred. |
| `source_uri` | `string` | No | The URL where the event occurred. |
| `custom_fields` | `string` | No | JSON object of additional custom key/value pairs, passed to Yahoo as custom event data. |
Rows are validated individually: a row with a missing required field or malformed timestamp is skipped and counted, without blocking the rest of the delivery.
***
## Supported user identifiers
In addition to the `conversion_event` attribute, your dataset must include at least one of the following Rosetta Stone identifier attributes. Yahoo uses these to match conversion events to user accounts. All PII values are SHA-256 hashed by Narrative before transmission.
| Identifier Attribute | Description |
| ----------------------------- | -------------------------------------------------------------------------------- |
| `raw_email` | Email address (hashed by Narrative) |
| `hashed_email` | Hashed email address |
| `sha256_hashed_email` | SHA-256 hashed email address |
| `telephone_number` | Phone number (hashed by Narrative) |
| `e164_phone_number` | Phone number in E.164 format (hashed by Narrative) |
| `sha256_hashed_phone_number` | SHA-256 hashed phone number |
| `android_advertising_id` | Android advertising ID (GAID) |
| `apple_idfa` | Apple Identifier for Advertisers (IDFA) |
| `mobile_id_unique_identifier` | Mobile advertising ID |
| `yahoo_pxid` | Yahoo partner match ID (PXID) |
| `partner_match_ids` | Partner match IDs whose `type` resolves to a Yahoo PXID |
| `unique_id` | Any unique user identifier whose `type` resolves to one of the identifiers above |
| `narrative_id` | Narrative platform identity |
Hashed identifiers must use SHA256. See [Hashing PII for Upload](/guides/ingestion/hashing-pii) for formatting requirements. PXIDs are automatically prefixed with Narrative's Yahoo partner ID so Yahoo can attribute their source.
***
## Reference
### Routing
Events are grouped by pixel ID and delivered per pixel. A single dataset can serve multiple pixels: set `yahoo_pixel_id` on each row, or leave it off and set a default Pixel ID on the connection.
### Deduplication
Narrative tracks the events already delivered for each connection and skips them on subsequent runs, so re-delivering a dataset does not double-count conversions. Provide a stable `event_id` (order number, transaction ID) per event.
### Batching
Events are delivered in batches to Yahoo's ingestion API. Batch sizes are tuned automatically based on the size of your events.
***
## Data privacy
Narrative hashes all customer information fields (email, phone number) using SHA-256 before transmission. Raw PII is never sent to Yahoo.
***
## Related content
Deliver audience data to Yahoo DSP for programmatic advertising
Send conversion events to Meta
Understand how connectors deliver data
Prepare identifiers for delivery