Pinterest Conversions Connector Setup Guide

[#1]

This article describes how to set up the Pinterest Conversions connector.

In this article:

• API Information
• Batch Limits
• Connector Actions
• Configure Settings
• Action Settings — Parameters and Options
• Action — Send Conversion Event

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. Requests are queued until one of the following thresholds is met:

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

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 deduping 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 been already 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 been already 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 been already 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 been already 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 been already 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 been already 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 been already 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 been already 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 been already 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 been already 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 been already 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 been already 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 an external ID which has been already whitespace trimmed and SHA256 hashed.
External ID (apply SHA256 hash)	Provide a plain text external ID and the connector will whitespace trim and hash this value using SHA256 hash.
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.
Testing Mode	Check if you want 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.