> ## 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.
# PubMatic Conversions API Connector
> Send conversion events to PubMatic for ad attribution and campaign optimization
The PubMatic Conversions API (CAPI) Connector sends conversion events from Narrative to PubMatic, enabling PubMatic to attribute conversions back to ad campaigns and optimize delivery against real outcomes.
## Overview
The connector routes conversion data — purchases, signups, site visits, and more — from any dataset in Narrative to a PubMatic advertiser. Events are matched using hashed emails and mobile advertising IDs alongside your own user identifier.
Unlike API-based conversion connectors, PubMatic ingests conversions as files: Narrative writes your events to compressed CSV files following PubMatic's conversion data contract and uploads them to PubMatic over SFTP on a schedule you configure. One file is produced per advertiser.
The Conversions API is a second interface of the same PubMatic app that delivers [audience segments](/reference/connectors/pubmatic) — one installed connector, one profile, two delivery paths.
## Prerequisites
* A **PubMatic advertiser account**. The advertiser ID is the numeric ID your events route to.
* A Narrative dataset containing the conversion data you want to send.
## Sending conversion events
Delivering conversion events to PubMatic 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 PubMatic Connector, you can reuse your existing profile and skip this step.
In Narrative, go to **Installed Apps** and select **PubMatic Connector**.
Create a profile with your PubMatic account details.
### Step 2: Create your dataset
Your dataset must be mapped to the [`pubmatic_conversion_event`](https://app.narrative.io/platform/rosetta-stone/attributes/pubmatic_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 `pubmatic_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-pubmatic_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 PubMatic connector profile you created in Step 1.
Click **Add Connection** and select **Deliver Conversion Events** as the connection type.
* **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 `pubmatic_conversion_event` attribute
The [`pubmatic_conversion_event`](https://app.narrative.io/platform/rosetta-stone/attributes/pubmatic_conversion_event) attribute is Narrative's standardized Rosetta Stone schema for conversion events sent to PubMatic. When you map your dataset columns to this attribute, Narrative handles transformation, file generation, and SFTP delivery following PubMatic's conversion data contract.
### Top-level fields
| Narrative Field | Type | Required | Description |
| -------------------- | --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `advertiser_id` | `long` | **Yes** | The PubMatic advertiser ID to deliver events to. Each row routes to the advertiser it names; one file is produced per advertiser. |
| `user_id` | `string` | **Yes** | Your identifier for the converting user. |
| `event_type` | `string` (enum) | **Yes** | The type of conversion event. See [Event types](#event-types). |
| `timestamp_utc` | `timestamptz` | **Yes** | Timestamp when the event occurred, in UTC. |
| `privacy` | `object[]` | **Yes** | Privacy signals for the event. Each entry requires `type` (e.g., `gdpr`, `ccpa`), `is_applicable` (boolean), and `consent_string`. |
| `event_url` | `string` | No | The URL where the event occurred. |
| `order_id` | `string` | No | Transaction or order ID. |
| `order_value` | `double` | No | Monetary value of the order. |
| `order_currency` | `string` | No | ISO 4217 currency code for the order value. |
| `item_count` | `long` | No | Number of items in the order. |
| `revenue` | `double` | No | Revenue attributed to the event. |
| `revenue_currency` | `string` | No | ISO 4217 currency code for the revenue. |
| `event_funnel_stage` | `string` | No | Funnel stage of the event. |
| `ip_address` | `string` | No | IP address where the event occurred. |
| `country` | `string` | No | Country of the event. |
| `region` | `string` | No | Region or state of the event. |
| `metro` | `string` | No | Metro area of the event. |
| `city` | `string` | No | City of the event. |
| `zip` | `string` | No | Postal code of the event. |
| `custom_fields` | `string` | No | Additional custom data. |
***
## Supported user identifiers
In addition to the `pubmatic_conversion_event` attribute, your dataset must include at least one of the following Rosetta Stone identifier attributes. They are delivered alongside your `user_id` as external user identifiers, which PubMatic uses to match the event to users.
| Identifier Attribute | Delivered As | Description |
| ----------------------------- | ------------ | ----------------------------------------------------------------------- |
| `sha256_hashed_email` | HEM | SHA-256 hashed email address |
| `hashed_email` | HEM | Hashed email address |
| `android_advertising_id` | MAID | Android advertising ID (GAID) |
| `apple_idfa` | MAID | Apple Identifier for Advertisers (IDFA) |
| `mobile_id_unique_identifier` | MAID | Mobile advertising ID |
| `unique_id` | — | Any unique user identifier whose `type` resolves to one of the above |
| `narrative_id` | — | Narrative platform identity (resolves to matched emails and mobile IDs) |
Hashed identifiers must use SHA256. See [Hashing PII for Upload](/guides/ingestion/hashing-pii) for formatting requirements.
***
## Reference
### Event types
The `event_type` field accepts the following values.
| Value | Description |
| ---------------- | ------------------ |
| `add_to_cart` | Item added to cart |
| `app_install` | App installed |
| `begin_checkout` | Checkout started |
| `login` | User logged in |
| `purchase` | Purchase completed |
| `search_item` | Search performed |
| `signup` | Account created |
| `site_visit` | Site visited |
| `view_cart` | Cart viewed |
| `view_item` | Item viewed |
### File delivery
Events are written as gzip-compressed CSV files following PubMatic's conversion data contract and uploaded to PubMatic's SFTP endpoint:
* Events are grouped by `advertiser_id` — one file per advertiser, with all event types mixed in the same file.
* Files larger than 500 MB uncompressed are split into multiple files.
### Privacy signals
PubMatic requires a privacy signal on every event. Each `privacy` entry carries a regulation `type` (e.g., `gdpr`, `ccpa`), whether it `is_applicable` to the event, and the associated `consent_string`. Include one entry per applicable regulation.
***
## Related content
Deliver audience segments to PubMatic for programmatic advertising
Send conversion events to Meta
Understand how connectors deliver data
Prepare identifiers for delivery