PubMatic Conversions API Connector - Narrative I/O Knowledge Base

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 — one installed connector, one profile, two delivery paths.

Guides

Sending Conversion Events to PubMatic

Connect a dataset of conversion events

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.

The `pubmatic_conversion_event` attribute

The 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.
`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 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.

PubMatic Connector

Deliver audience segments to PubMatic for programmatic advertising

Meta Conversions API Connector

Send conversion events to Meta

Data Activation Overview

Understand how connectors deliver data

Hashing PII

Prepare identifiers for delivery

Overview

Guides

Sending Conversion Events to PubMatic

Prerequisites

The pubmatic_conversion_event attribute

Top-level fields

Supported user identifiers

Reference

Event types

File delivery

Privacy signals

Related content

PubMatic Connector

Meta Conversions API Connector

Data Activation Overview

Hashing PII

The `pubmatic_conversion_event` attribute