Pinterest Conversions Connector Setup Guide | Server-Side Connectors

API Information

This connector uses the following vendor API:

API Name: Pinterest Marketing API
API Version: v5
API Endpoint: https://api.pinterest.com/
Vendor documentation: Pinterest Conversions Guide

Batch Limits

This connector uses batched requests to support high-volume data transfers to the vendor. For more information, see Batched Actions. Requests are queued until one of the following thresholds is met or the profile is published:

Max number of requests: 1000
Max time since oldest request: 10 minutes
Max size of requests: 2 MB

How it Works

The Pinterest Conversions API allows advertisers to send conversion events to Pinterest without using the Pinterest tag. By mapping conversions to Pinterest campaigns, you can improve conversion visibility and receive a more accurate picture of the effectiveness of your campaigns and actions that are driving conversions. Additional benefits from Conversion API tracking include enhanced optimization and targeting, greater transparency, and enhancing reporting and analysis.

The Pinterest Conversions API can receive web, in-app, or offline conversions. Events received within an hour of the event occurring are reported as web or app events. Events received outside of that window are categorized as offline events.

We recommended using both the Pinterest Conversion connector and the Pinterest Tag together to maximize visibility and track conversions. You can use the Pinterest Conversion connector as a standalone solution, but using both tools together provides the best results.

Events that can be tracked include:

Add to Cart - Items are added to shopping carts.
Checkout - Completed transactions.
Custom - Track a custom event. Use this event name to track a special event that you want to include in your conversion reporting.
Lead - Interest in product or service.
Page Visit - Views of primary pages, such as product pages and article pages.
Search - Searches on your website.
Signup - Sign ups for your products or services.
View Category - Views of category pages.
Watch Video - Video views.
User-Defined Event - Add any additional events that you’ve defined for the purpose of audience targeting. Unique events are not available for conversion reporting.

Deduplication

When redundant implementations are put into place (for example, the Pinterest Conversion API and Pinterest Tag), deduplication is required to avoid double-counting of a single event when it is sent through both solutions. By using deduplication, advertisers can expect more conversions being attributed than if the connector or tag solution are used independently.

Deduplication for Pinterest Tag and Pinterest Conversions API

The Pinterest Tag and Pinterest Conversion API use the Event ID for deduplication. Ensure this value is included when multiple sources are used to track conversion data. To find your Event IDs, complete the following steps:

Log into your Pinterest business account.
Navigate to Ads > Reporting.
Click the menu icon in the top-right above the table and select Performance.

Depending on what event codes you’ve added to your site, they will be listed throughout the table along with the number of times they’ve happened during the selected timeframe.

Look for event attributes using the following naming convention:

pinterest_event_id_<Pinterest Event>_<Tag UID>

For example: pinterest_event_id_Checkout_32

Use a separate action for each type of event ID. Map the event-specific event ID attribute to Event ID with the matching event name mapped to Event Name. For example:

Tealium Attribute/Value	Pinterest Parameter
`pinterest_event_id_Checkout_32`	Event ID
Checkout (dropdown selection)	Event Name

For more information, see the Pinterest Tag Setup Guide.

Connector Actions

Action Name	AudienceStream	EventStream
Send Conversion Event	✓	✓

Configure Settings

Navigate to the Connector Marketplace and add a new connector. For general instructions on how to add a connector, see the About Connectors article.

When you add this connector you are prompted to accept the vendor’s data platform policy.

After adding the connector, configure the following settings:

Access Token
Required. Access Token generated through the Pinterest Ads Manager.
For more information, see the Pinterest Conversions Guide.
Ad Account ID
Required. Unique identifier of an ad account. To locate your Ad Account ID in Pinterest, log into the Pinterest account that owns your advertiser account and navigate to Ads > Overview. The Ad Account ID is visible in the URL path. For example, ads.pinterest.com/advertiser/{ad_account_id}/... .

Click Done when you are finished configuring the connector.

Action Settings — Parameters and Options

Click Continue to configure the connector actions. Enter in a name for the action and then select the action type from the drop-down menu.

The following section describes how to set up parameters and options for each action.

Action — Send Conversion Event

Parameters

Parameter	Description
Event Name	The type of the user event to record. Note: Events with custom event types will not be available to use in reporting. Add to Cart - Items are added to shopping carts. Checkout - Completed transactions. Custom - Use this event name to track a special event that you want to include in your conversion reporting. Lead - Interest in product or service. Page Visit - Views of primary pages, such as product pages and article pages. Search - Searches on your website. Signup - Sign ups for your products or services. View Category - Views of category pages. Watch Video - Video views.
Event Action Source	Source indicating where the conversion event occurred. App Android - Via mobile in-app events from an Android device. App iOS - Via mobile in-app events from an iOS device. Offline - Event is from offline. Web - Via desktop web browsers as well as mobile web browsers.
Event ID	(Required) A unique ID string that identifies this event and can be used for deduplicating between events ingested via both the Pinterest API for Conversions and the Pinterest Tag.
Ad Account ID Override	This setting overrides Pinterest Ad Account ID used in the connector configuration section. Either Ad Account ID Override or Ad Account ID in the connector configuration section must be provided.
Event Time	Unix timestamp (in UTC) in seconds indicating when the user conversion event occurred. The event time cannot be in the future of when Pinterest receives the request. If this field is not mapped, it will be initialized with the current timestamp.
Event Source URL	URL of the web conversion event.
Opt Out	When Event Action Source is Web or Offline, it defines whether the user has opted out of tracking for web conversion events. While when Event Action Source is App Android or App iOS, it defines whether the user has enabled Limit Ad Tracking on their iOS device, or opted out of Ads Personalization on their Android device.
Email (already SHA256 hashed)	Provide an email address which has already been whitespace trimmed, lowercased, and SHA256 hashed.
Email (apply SHA256 hash)	Provide a plain text email address and the connector will whitespace trim, lowercase, and hash this value using SHA256 hash.
Apple’s Identifier for Advertisers (already SHA256 hashed)	Provide an Apple’s Identifier for Advertisers which has already been whitespace trimmed and SHA256 hashed.
Apple’s Identifier for Advertisers (apply SHA256 hash)	Provide a plain text Apple’s Identifier for Advertisers and the connector will whitespace trim and hash this value using SHA256 hash.
Google Advertising ID (already SHA256 hashed)	Provide a Google Advertising ID which has already been whitespace trimmed and SHA256 hashed.
Google Advertising ID (apply SHA256 hash)	Provide a plain text Google Advertising ID and the connector will whitespace trim and hash this value using SHA256 hash.
Client IP Address	The user’s IP address, which can be either in IPv4 or IPv6 format.
Client User Agent	The user agent string of the user’s web browser.
Phone Number (already SHA256 hashed)	Provide a phone number which contains only numeric characters, has already been whitespace trimmed and SHA256 hashed. Remove leading zeros before hashing.
Phone Number (apply SHA256 hash)	Provide a plain text phone number and the connector will remove all non-numeric characters and leading zeroes, whitespace trim, and hash this value using SHA256 hash.
Gender (already SHA256 hashed)	Provide a gender which has already been whitespace trimmed, lowercased, and SHA256 hashed.
Gender (apply SHA256 hash)	Provide a plain text gender and the connector will whitespace trim, lowercase, and hash this value using SHA256 hash.
Birthdate (already SHA256 hashed)	Provide a birthdate which has already been whitespace trimmed, lowercased, and SHA256 hashed.
Birthdate (apply SHA256 hash)	Provide a plain text birthdate and the connector will whitespace trim, lowercase, and hash this value using SHA256 hash.
First Name (already SHA256 hashed)	Provide a first name which has already been whitespace trimmed, lowercased, and SHA256 hashed.
First Name (apply SHA256 hash)	Provide a plain text first name and the connector will whitespace trim, lowercase, and hash this value using SHA256 hash.
Last Name (already SHA256 hashed)	Provide a last name which has already been whitespace trimmed, lowercased, and SHA256 hashed.
Last Name (apply SHA256 hash)	Provide a plain text last name and the connector will whitespace trim, lowercase, and hash this value using SHA256 hash.
City (already SHA256 hashed)	Provide a city which has already been whitespace trimmed, lowercased, and SHA256 hashed. Remove spaces and punctuation before hashing.
City (apply SHA256 hash)	Provide a plain text city and the connector will remove spaces and punctuation, whitespace trim, lowercase, and hash this value using SHA256 hash.
State (already SHA256 hashed)	Provide a state which has already been whitespace trimmed, lowercased, and SHA256 hashed.
State (apply SHA256 hash)	Provide a plain text state and the connector will whitespace trim, lowercase, and hash this value using SHA256 hash.
Zip Code (already SHA256 hashed)	Provide a zip code which contains only numeric characters, has already been whitespace trimmed and SHA256 hashed.
Zip Code (apply SHA256 hash)	Provide a plain text zip code and the connector will remove all non-numeric characters, whitespace trim and hash this value using SHA256 hash.
Country Code (already SHA256 hashed)	Provide a country code which has already been whitespace trimmed, lowercased, and SHA256 hashed.
Country Code (apply SHA256 hash)	Provide a plain text country code and the connector will whitespace trim, lowercase, and hash this value using SHA256 hash.
External ID (already SHA256 hashed)	Provide one or more external IDs, already whitespace trimmed and SHA256 hashed, and formatted as an array if there are multiple External IDs. For more information, see Pinterest: What is an External ID?.
External ID (apply SHA256 hash)	Provide one or more plain text external IDs and the connector will whitespace trim and hash these values using SHA256 hash. If you provide multiple External IDs, format them as an array.
Click ID	The unique identifier stored in `_epik` cookie on your domain or `&epik= query` parameter in the URL. It may improve reporting performance such as ROAS/CPA.
Currency	The ISO-4217 currency code. If not provided, Pinterest will default to the advertiser’s currency set during account creation.
Value	Total value of the event. Accepted as a string in the request, it will be parsed into a double. For example, if there are two items in a checkout event, the value should be the total price.
Content IDs	List of products IDs.
Number of Items	Total number of products of the event. For example, the total number of items purchased in a checkout event.
Order ID	The order ID.
Search String	The search string related to the user conversion event.
Opt Out Type	Flags for different privacy rights laws to opt out users of sharing personal information. Values should be comma separated. Array type attributes can be mapped and will be converted to a comma separated string.
Item Price	The price of a product. Accepted as a string in the request, it will be parsed into a double. For example, if there are two products in a checkout event, the value should be the total price.
Quantity	The amount of a product.
App ID	The app store app ID.
App Name	Name of the app.
App Version	Version of the app.
Device Brand	Brand of the user device.
Device Carrier	User device’s mobile carrier.
Device Model	Model of the user device.
Device Type	Type of the user device.
OS Version	Version of the device operating system.
WiFi	Whether the event occurred when the user device was connected to WiFi.
Language	Two-character ISO-639-1 language code indicating the user’s language.
Tealium iQ Tag ID	When the Tealium iQ Tag ID is provided, the event ID value sent from Tealium iQ is automatically identified and sent to Pinterest. The UDO value used to identify the the event ID is `pinterest_event_id_EVENTNAME_TAGID`.
Testing Mode	Select to mark the request as a test request. The events will not be recorded but the API will still return the same response messages. Use this mode to verify your requests are working and your events are constructed correctly.