Pinterest CAPI

What Is Pinterest CAPI?

Pinterest is a visual discovery and bookmarking platform where users can find, save, and share ideas and inspirations. It allows users to create and organize collections of images, known as "pins," into thematic boards. These pins can link back to the original source, making Pinterest a powerful tool for discovering new content, planning projects, and finding creative inspiration. The platform is widely used for ideas on fashion, recipes, home decor, and more, catering to both personal interests and professional marketing.

Pinterest Conversion API (CAPI) is a tool that helps businesses track user interactions on their websites more accurately by sending events directly from their servers to Pinterest. This API enables better measurement of conversion actions, such as purchases or sign-ups, without relying solely on browser-based tracking, which can be affected by ad blockers or cookie restrictions. By using CAPI, businesses can gain deeper insights into the performance of their Pinterest campaigns, improve ad targeting, and optimize their marketing strategies for better results.

What are the benefits of integrating MetaRouter with Pinterest CAPI?

  • Enhanced Data Accuracy: CAPI reduces the impact of ad blockers and cookie restrictions, ensuring more reliable tracking of user interactions and conversions.
  • Improved Data Security: Direct server-to-server communication provides a more secure way of transmitting data compared to browser-based methods.
  • Comprehensive Event Tracking: CAPI allows for tracking a wider range of user interactions and conversion events, offering deeper insights into campaign performance.
  • Better Ad Targeting and Optimization: With more accurate and complete data, businesses can refine their ad targeting and optimization strategies, leading to more effective marketing efforts.

Getting Started - From Your Pinterest Account

Ad Account ID & Access Token:

  1. Log in to Pinterest Business Manager.
  2. Click on the upper-left drop down menu.
  3. Click on “Conversions” under the “Business” column.
  4. Under “API for Conversions”, Select “Conversion access token”, and click Generate new token.
  5. Your Ad Account ID will be displayed along with the new token.

Pixel ID:

  1. Continuing in Pinterest Business Manager, click on the upper-left drop down menu.
  2. Click on “Conversions” under the “Business” column.
  3. On the left-hand navigation, click on “Tag Manager”.
  4. There is an option to click on “Install the Pinterest tag manually” that will let you view your Tag ID on the upper-right side of the screen. This ID will be used as your Pixel ID in the sync.

Getting Started - From Your MetaRouter Account

Adding a Pinterest CAPI integration.

From the integration library, add a Pinterest CAPI integration. Then, fill out the Connection Parameters:

Connection ParameterDescription
AD_ACCOUNT_IDYour Pinterest ad account ID.
ACCESS_TOKENYour conversion access token.

Adding a Pinterest CAPI Sync

To gather the epik value, you must add a Pinterest CAPI sync.

  1. From the Pipelines page, find the pipeline associated with the web property you’d like to add a sync to. Hover over the three dot dropdown and select “Build AJS File.”

  2. In the Identity Syncs section, select the Pinterest CAPI sync.

  3. Fill out the following fields:

    1. Pixel ID - Enter your Tag ID.

    2. Cookie Lifetime (in days) - Default is 45 days.

    3. Custom Event Property Value - Default is “MetaRouterSync” but is customizable.

    4. Extra Pinterest PixelID - String array of additional pixels that should be fired. This field is optional. Note this must be a valid JSON of string IDs.

      [
      "2613210818064",
      "2613210818065",
      "2613210818066"
      ]
  4. Scroll down and click the Save and Build File button.

  5. Deploy your AJS file to propagate changes to your web property.


Event Mappings

MetaRouter provides all of the event mappings that Pinterest CAPI integrations typically require. You may add custom events, parameters or mappings in accordance with Pinterest CAPI’s API documentation.

Global

Global mappings will be applied to all events. If your parameter names do not match the Expected Inputs provided, you will need to overwrite the Inputs provided with your own.

Output Key

Description

Expected Input

partner_name Required

Type: String
The third party partner name responsible to send the event to Conversions API on behalf of the advertiser. The naming convention is "ss-partnername" lowercase. E.g ‘ss-shopify’

Enrichment - MetaRouter

custom_data.opt_out_type
Required

Type: String
Indicates whether the user has opted out of tracking.

Enrichemnt - LDP

action_source
Required

Type: String
Describes the source of the action or event.

N/A - Expression

event_time
Required

Type: Integer
Records the timestamp of when the event occurred in Unix time.

N/A - Expression

event_id
Required

Type: String
A unique identifier for the event, used for deduplication.

messageId

event_source_url

Type: String
The URL of the webpage where the event occurred.

context.page.url

user_data.em
Required

Type: Array
User email address, hashed.

N/A - Expression

user_data.client_ip_address
Required

Type: String
The IP address of the user.

context.ip

user_data.client_user_agent
Required

Type: String
The user agent string of the user's browser.

context.userAgent

user_data.ct

Type: Array
User city, hashed.

N/A - Expression

user_data.st

Type: Array
User state, hashed.

N/A - Expression

user_data.zp

Type: Array
User zip code, hashed.

N/A - Expression

user_data.country

Type: Array
The country of the user, typically in hashed format.

N/A - Expression

user_data.external_id
Highly Recommended

Type: String
An external ID for the user, often used to match user data with data held in other systems.

anonymousId

user_data.click_id
Highly Recommended

Type: String
A unique identifier for the user's click, often used for tracking ad clicks.

context.providers.pinterestCAPI.epik


Event Specific

page

Output Key

Description

Expected Input

event_name Required

Type: String
Name of the event.

Enrichment - page_visit


products_searched

Output Key

Description

Expected Input

event_name Required

Type: String
Name of the event.

Enrichment - search

custom_data.search_string
Required

Type: String
The search string used by the user.

properties.query


product_list_viewed

Output Key

Description

Expected Input

event_name Required

Type: String
Name of the event.

Enrichment - view_category

custom_data.content_ids
Required

Type: Array
List of content IDs involved in the transaction.

N/A - Expression

custom_data.contents
Required

Type: Array
Details of the contents in the transaction.

N/A - Expression


product_viewed

Output Key

Description

Expected Input

event_name Required

Type: String
Name of the event.

Enrichment - page_visit

custom_data.currency
Required

Type: String
Currency of the transaction.

properties.currency

custom_data.value
Required

Type: String
Total value of the transaction.

N/A - Expression

custom_data.content_ids
Required

Type: Array
List of content IDs involved in the transaction.

N/A - Expression

custom_data.contents
Required

Type: Array
Details of the contents in the transaction.

N/A - Expression

custom_data.num_items
Required

Type: Integer
Number of items in the transaction.

properties.quantity


product_added

Output Key

Description

Expected Input

event_name Required

Type: String
Name of the event.

Enrichment - add_to_cart

custom_data.currency
Required

Type: String
Currency of the transaction.

properties.currency

custom_data.value
Required

Type: String
Total value of the transaction.

N/A - Expression

custom_data.content_ids
Required

Type: Array
List of content IDs involved in the transaction.

N/A - Expression

custom_data.contents
Required

Type: Array
Details of the contents in the transaction.

N/A - Expression

custom_data.num_items
Required

Type: Integer
Number of items in the transaction.

properties.quantity


cart_viewed

Output Key

Description

Expected Input

event_name Required

Type: String
Name of the event.

Enrichment - page_visit

custom_data.currency
Required

Type: String
Currency of the transaction.

properties.currency

custom_data.value
Required

Type: String
Total value of the transaction.

N/A - Expression

custom_data.content_ids
Required

Type: Array
List of content IDs involved in the transaction.

N/A - Expression

custom_data.contents
Required

Type: Array
Details of the contents in the transaction.

N/A - Expression

custom_data.num_items
Required

Type: Integer
Number of items in the transaction.

properties.quantity

custom_data.order_id
Required

Type: String
Order ID of the transaction.

properties.order_id


order_completed

Output Key

Description

Expected Input

event_name Required

Type: String
Name of the event.

Enrichment - checkout

custom_data.currency
Required

Type: String
Currency of the transaction.

properties.currency

custom_data.value
Required

Type: String
Total value of the transaction.

N/A - Expression

custom_data.content_ids
Required

Type: Array
List of content IDs involved in the transaction.

N/A - Expression

custom_data.contents
Required

Type: Array
Details of the contents in the transaction.

N/A - Expression

custom_data.num_items
Required

Type: Integer
Number of items in the transaction.

properties.quantity

custom_data.order_id
Required

Type: String
Order ID of the transaction.

properties.order_id


Required & Recommended Identifiers

These identifiers must be mapped to Pinterest CAPI in order for successful user matching to occur. Without these IDs, any events sent to Pinterest CAPI may not be reflected within reporting. For your convenience, required and recommended IDs are mapped as Global parameters to ensure they are added to every event.


Attribute

Example

Sync Injector Required?

em Required if not using IP and user agent

d41d8cd98f00b204e9800998ecf8427e

No

client_ip_address
Required if not using em

192.168.1.1

No

client_user_agent
Required if not using em

Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/91.0.4472.124 Safari/537.36

No

external_id
Highly recommended

130161d0-8fee-4167-aa4d-d151eed27c6b

No

click_id
Highly recommended

abcdef1234567890

Yes

ct
Recommended

City: newyork
SHA-256 Hash: bb11df46c3c14b95b79b9e4c872c1e49f73eaa9570733e499cd4f36f9fbf2e6c

No

st
Recommended

State: ny
SHA-256 Hash: 995c9ffcc78411b9e53d206ec0a9a6f63b74b090e179dba1e4eafd922c1e95ff

No

zp
Recommended

Zipcode: 10001
SHA-256 Hash: 49557a7a840fcb6f8d11d1b276844acdd71c1c6b46c9c6e0cc5b2f43ad5c3d57

country
Recommended

Country: us
SHA-256 Hash: e6fb06210fafc02fd7479ddbed2d042cc3a5155e0d3af5ed9da5760b31e020d6

No


Additional Identifiers

These identifiers should be mapped to Pinterest CAPI whenever possible to ensure the highest user match rates possible. If using these identifiers, they must be added as Global or Event Specific mappings.

Attribute

Description

Example

hashed_maid

Sha256 hashes of user's "Google Advertising IDs" (GAIDs) or "Apple's Identifier for Advertisers" (IDFAs). Used for matching. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA.

GAID/IDFA: 123e4567-e89b-12d3-a456-426614174000

SHA-256 Hash: 03ac674216f3e15c761ee1a5e255f067e2e3a08ef0d751154643452c6b9ee7f8

ph

Sha256 hashes of user's phone numbers, only digits with country code, area code, and number. Remove any symbols, letters, spaces and leading zeros. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA.

Formatted: 12345678901

SHA-256 Hash: bf13be1992a112e35ac07fb2cdbf03a7c648ea7c593aa82ae388651adcb5efb6

ge

Sha256 hashes of user's gender, in lowercase. Either "f" or "m" or "n" for non-binary gender.

Gender: f

SHA-256 Hash: 2d711642b726b04401627ca9fbac32f5c5d5a1f59e80e04c3e8abf2d4d68b14e

db

Sha256 hashes of user's date of birthday, given as year, month, and day.

a69c6a58fe3821425dc1705a7a72c527504b52e7d5bb97854f4e48cf1a4055e7

ln

Sha256 hashes of user's last name, in lowercase. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA.

Last Name: smith

SHA-256 Hash: 872e4b0f8323b7fc6cb67e8a3e00094ed88d2f71c6a38ffb70f2e3107d8e7964

fn

Sha256 hashes of user's first name, in lowercase. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA.

First Name: john

SHA-256 Hash: 2fd4e1c67a2d28fced849ee1bb76e7391b93eb12


Additional Pinterest CAPI Documentation

Pinterest CAPI

Pinterest CAPI Conversion Events API Reference