Pinterest Conversions API Connector

The Pinterest Conversions API (CAPI) Connector sends conversion events from Narrative directly to Pinterest’s Conversions API, enabling Pinterest to attribute conversions back to ad campaigns and optimize delivery against real outcomes.

Overview

The connector routes conversion data — checkouts, signups, leads, page visits, and more — from any dataset in Narrative to a Pinterest ad account. Events are matched against Pinterest user accounts using hashed customer information. This connector supports:

Web conversions (e.g., website purchases, page visits)
App conversions (Android and iOS)
Offline conversions (e.g., in-store purchases)

Events are batched and delivered on a schedule you configure. PII fields are SHA-256 hashed before transmission in accordance with Pinterest’s requirements. The Conversions API is a second interface of the same Pinterest app that delivers custom audiences — one installed connector, one set of profiles and ad accounts, two delivery paths.

Prerequisites

A Pinterest Business account with access to Pinterest Ads Manager and the ad account you want to deliver events to.
A Narrative dataset containing the conversion data you want to send.

Sending conversion events

Delivering conversion events to Pinterest 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 Pinterest Connector, you can reuse your existing profile and skip this step.

Navigate to the connector

In Narrative, go to Installed Apps and select Pinterest Connector.

Connect your Pinterest account

In the Profiles tab, click Connect and authorize Narrative to access your Pinterest Business account.

Select your ad account

In the Ad Accounts tab, choose the ad account where conversion events should be delivered.

Step 2: Create your dataset

Your dataset must be mapped to the pinterest_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 pinterest_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

Open your connector profile

Navigate to the Pinterest connector profile you created in Step 1.

Add a new connection

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

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.

Connect

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

The `pinterest_conversion_event` attribute

The pinterest_conversion_event attribute is Narrative’s standardized Rosetta Stone schema for conversion events sent to Pinterest. When you map your dataset columns to this attribute, Narrative handles transformation, hashing, batching, and delivery to Pinterest’s API.

Top-level fields

Narrative Field	Pinterest CAPI Field	Type	Required	Description
`pinterest_ad_account_id`	(routing)	`string`	Yes	The Pinterest ad account ID to deliver events to. Each row routes to the ad account it names.
`event_id`	`event_id`	`string`	Yes	Unique string for deduplication. Use an order number, transaction ID, or random string.
`event_name`	`event_name`	`string` (enum)	Yes	The type of conversion event. See Event names.
`event_time`	`event_time`	`timestamptz`	Yes	Timestamp when the event occurred.
`action_source`	`action_source`	`string` (enum)	Yes	Where the conversion occurred. See Action sources.
`event_source_url`	`event_source_url`	`string`	No	The browser URL where the event occurred.
`opt_out`	`opt_out`	`boolean`	No	If `true`, the user has opted out of tracking for this event.
`partner_name`	`partner_name`	`string`	No	Third-party partner name (`ss-<partner>`).
`language`	`language`	`string`	No	Two-character ISO 639-1 language code for the event.
`custom_data`	`custom_data`	`object`	No	Additional business data about the conversion. See Custom data fields.
`device_info`	`device_info`	`object`	No	Device context for app events. If present, `form_factor`, `os_family`, and `network_type` are required — Pinterest rejects the event without them.
`app_info`	`app_info`	`object`	No	App context for app events (app name, package name, version, store).

Custom data fields

Additional event data used by Pinterest for attribution and reporting.

Narrative Field	Type	Description
`custom_data.value`	`double`	Monetary value of the conversion
`custom_data.currency`	`string`	ISO 4217 currency code (e.g., `USD`)
`custom_data.order_id`	`string`	Transaction or order ID
`custom_data.content_ids`	`string[]`	Product SKUs or content IDs
`custom_data.content_name`	`string`	Name of the content or product
`custom_data.content_category`	`string`	Category of the content or product
`custom_data.content_brand`	`string`	Brand of the content or product
`custom_data.num_items`	`long`	Number of items in the conversion
`custom_data.search_string`	`string`	Search query. Use with `search` events
`custom_data.opt_out_type`	`string`	Type of opt-out for the event
`custom_data.predicted_ltv`	`double`	Predicted lifetime value of the conversion
`custom_data.contents`	`object[]`	Array of product objects. Each requires `id` (string). Optional: `item_name`, `item_brand`, `item_brand_id`, `item_category` (strings), `item_price` (double), `quantity` (long)

Supported user identifiers

In addition to the pinterest_conversion_event attribute, your dataset must include at least one of the following Rosetta Stone identifier attributes. Pinterest uses these to match conversion events to user accounts. All PII values are SHA-256 hashed by Narrative before transmission.

Identifier Attribute	Description
`sha256_hashed_email`	SHA-256 hashed email address
`hashed_email`	Hashed email address
`sha256_hashed_phone_number`	SHA-256 hashed phone number
`e164_phone_number`	Phone number in E.164 format
`telephone_number`	Phone number
`android_advertising_id`	Android advertising ID (GAID)
`apple_idfa`	Apple Identifier for Advertisers (IDFA)
`mobile_id_unique_identifier`	Mobile advertising ID
`unique_id`	Any unique user identifier
`narrative_id`	Narrative platform identity
`ip_address` + `user_agent`	Client IP address and user agent (both required together)

Pinterest requires every event to carry at least one of: a hashed email, a hashed mobile advertising ID, or the IP address + user agent pair. Other identifiers improve match quality but do not satisfy Pinterest’s minimum on their own, so make sure your dataset includes at least one of the three.

Match enrichment attributes

These optional attributes improve Pinterest’s match quality when included alongside a supported identifier:

Attribute	Description
`person_name`	Given and family name
`postal_address`	City, state/region, and postal code
`iso_3166_1_country`	Two-letter country code
`birthdate`	Date of birth
`hl7_gender`	Gender
`pinterest_click_id`	Pinterest click ID from an ad click
`pinterest_partner_id`	Pinterest partner ID

Only email, phone, and mobile ad ID attributes accept pre-hashed values. Name, address, and demographic attributes must be provided raw — Narrative normalizes and hashes them to Pinterest’s specification, so pre-hashed values in those fields will not match.

Reference

Event names

The event_name field accepts the following values.

Value	Description
`add_payment_info`	Payment information added
`add_to_cart`	Item added to cart
`add_to_wishlist`	Item added to wishlist
`app_install`	App installed
`app_open`	App opened
`checkout`	Purchase completed
`contact`	Contact initiated
`custom`	Custom event
`customize_product`	Product customized
`find_location`	Store location looked up
`initiate_checkout`	Checkout started
`lead`	Lead submitted
`page_visit`	Page viewed
`schedule`	Appointment scheduled
`search`	Search performed
`signup`	Account created
`start_trial`	Trial started
`submit_application`	Application submitted
`subscribe`	Subscription started
`view_category`	Category page viewed
`view_content`	Content viewed
`watch_video`	Video watched

Action sources

Value	Use When
`web`	Conversion happened on a website.
`app_android`	Conversion happened in an Android app.
`app_ios`	Conversion happened in an iOS app.
`offline`	Conversion happened offline (e.g., in a brick-and-mortar location).

Deduplication

Pinterest deduplicates events by event_id within a 48-hour window. If you send the same events through both a Pinterest conversion tag (pixel) and the Conversions API, use the same event_id in both so Pinterest removes the duplicates before reporting. Offline events are excluded from tag/API deduplication.

Batching

Events are delivered in batches of up to 1,000 per API call. Narrative validates each event against Pinterest’s field constraints before delivery, so a single invalid row does not block the rest of the batch.

Data privacy

Narrative normalizes and hashes all customer information fields (email, phone, name, address, birth date, gender) using SHA-256 before transmission, following Pinterest’s normalization rules for each field. Raw PII is never sent to Pinterest. IP address, user agent, click ID, and partner ID are passed through unhashed, as Pinterest requires.

Pinterest Connector

Deliver custom audiences to Pinterest for ad targeting

Meta Conversions API Connector

Send conversion events to Meta

Data Activation Overview

Understand how connectors deliver data

Hashing PII

Prepare identifiers for delivery

Overview

Connectors

Integrations

Workflow Reference

Webhook Reference

Security Reference

Architecture Reference

Error Reference

Deprecations

Model Inference Reference

Rosetta Stone Reference

UI Reference

SDKs

Glossary

Billing

Overview

Prerequisites

Sending conversion events

Step 1: Create a connector profile

Step 2: Create your dataset

Step 3: Add a connection

The `pinterest_conversion_event` attribute

Top-level fields

Custom data fields

Supported user identifiers

Match enrichment attributes

Reference

Event names

Action sources

Deduplication

Batching

Data privacy

Pinterest Connector

Meta Conversions API Connector

Data Activation Overview

Hashing PII

​Overview

​Prerequisites

​Sending conversion events

​Step 1: Create a connector profile

​Step 2: Create your dataset

​Step 3: Add a connection

​The pinterest_conversion_event attribute

​Top-level fields

​Custom data fields

​Supported user identifiers

​Match enrichment attributes

​Reference

​Event names

​Action sources

​Deduplication

​Batching

​Data privacy

​Related content

Pinterest Connector

Meta Conversions API Connector

Data Activation Overview

Hashing PII

Overview

Prerequisites

Sending conversion events

Step 1: Create a connector profile

Step 2: Create your dataset

Step 3: Add a connection

The `pinterest_conversion_event` attribute

Top-level fields

Custom data fields

Supported user identifiers

Match enrichment attributes

Reference

Event names

Action sources

Deduplication

Batching

Data privacy

Related content