Skip to main content
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.

​
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.
1

Navigate to the connector

In Narrative, go to Installed Apps and select PubMatic Connector.
2

Create a profile

Create a profile with your PubMatic account details.

​
Step 2: Create your dataset

Your dataset must be mapped to the 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 for user matching. Any dataset that contains the required attributes in the correct schema is eligible for delivery.
See the attribute schema below for the full list of event fields, and Supported user identifiers for the identity attributes your dataset must include.

​
Step 3: Add a connection

1

Open your connector profile

Navigate to the PubMatic connector profile you created in Step 1.
2

Add a new connection

Click Add Connection and select Deliver Conversion Events as the connection type.
3

Configure delivery options

  • 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.
4

Connect

Click Connect to activate. Events will begin delivering on the next scheduled run.

​
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

​
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.
Hashed identifiers must use SHA256. See Hashing PII for Upload for formatting requirements.

​
Reference

​
Event types

The event_type field accepts the following values.

​
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

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