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:

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

Pixel ID:

Continuing in Pinterest Business Manager, click on the upper-left drop down menu.
Click on “Conversions” under the “Business” column.
On the left-hand navigation, click on “Tag Manager”.
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 Parameter	Description
`AD_ACCOUNT_ID`	Your Pinterest ad account ID.
`ACCESS_TOKEN`	Your conversion access token.

Adding a Pinterest CAPI Sync

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

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.”
In the Identity Syncs section, select the Pinterest CAPI sync.
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"
]
```
Scroll down and click the Save and Build File button.
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