Pinterest Conversions API Connector - Narrative I/O Knowledge Base

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.

Guides

Sending Conversion Events to Pinterest

Connect a dataset of conversion events

Setting Up API Access for Pinterest

Prerequisites, API keys, and profiles for the API guides

Sending Conversion Events to Pinterest via the API

Send conversion events with an API key

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.

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.

API connection settings

A connection’s quick_settings pick the interface and set how the connection delivers. The fields depend on the interface.

Conversion events (`conversion_events`)

Field	What it does	Allowed values	Default
`test_mode_enabled`	Sends events to Pinterest as test events	`true`, `false`	`false`
`historical_data_enabled`	Whether the connection also sends events already in the dataset	`true`, `false`	`false`

Each event names its ad account in pinterest_ad_account_id, so the connection has no ad account setting. The connection sends events up to 7 days old.

Existing and new rows

A connection delivers every snapshot written to the dataset after the connection is created. The historical_data_enabled quick setting decides whether the connection also delivers data that was already in the dataset when you created it:

With historical_data_enabled set to true, the connection first delivers data already in the dataset, then keeps delivering new snapshots as they land.
With historical_data_enabled set to false, the connection delivers only snapshots written after it was created.

How far back the first delivery reaches depends on the connector, and each connector’s guide states it. For Pinterest, historical_data_enabled delivers the dataset’s snapshots from the 30 days before the connection was created, as one delivery. After that, each new snapshot is delivered as it lands. A conversion connection sends each event in each snapshot it delivers. Uploading the same events again in a new snapshot sends them again.

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

Guides

Sending Conversion Events to Pinterest

Setting Up API Access for Pinterest

Sending Conversion Events to Pinterest via the API

Prerequisites

The pinterest_conversion_event attribute

Top-level fields

Custom data fields

Supported user identifiers

Match enrichment attributes

Reference

Event names

Action sources

Deduplication

Batching

API connection settings

Conversion events (conversion_events)

Existing and new rows

Data privacy

Related content

Pinterest Connector

Meta Conversions API Connector

Data Activation Overview

Hashing PII

The `pinterest_conversion_event` attribute

Conversion events (`conversion_events`)