> ## 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.
# Pinterest Conversions API Connector
> Send conversion events to Pinterest for ad attribution and campaign optimization
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](/reference/connectors/pinterest) — 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.
In Narrative, go to **Installed Apps** and select **Pinterest Connector**.
In the **Profiles** tab, click **Connect** and authorize Narrative to access your Pinterest Business 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`](https://app.narrative.io/platform/rosetta-stone/attributes/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](#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-pinterest_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 Pinterest 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 `pinterest_conversion_event` attribute
The [`pinterest_conversion_event`](https://app.narrative.io/platform/rosetta-stone/attributes/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-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](#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-`). |
| `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](#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.
***
## Related content
Deliver custom audiences to Pinterest for ad targeting
Send conversion events to Meta
Understand how connectors deliver data
Prepare identifiers for delivery