Pinterest Conversions API
The Pinterest Conversions API destination is a server-to-server integration with The Pinterest API for Conversions that allows advertisers to send conversions directly to Pinterest without requiring a Pinterest Tag. These conversions map to Pinterest campaigns for conversion reporting to improve conversion visibility. When you pass events to Pinterest, advertisers can use Pinterest’s insights to evaluate an ad’s effectiveness to improve content, targeting, and placement of future ads.
Advertisers can send web, in-app, or offline conversions to Pinterest’s server to server endpoint in real-time. Events received in real time or within an hour of the event occurring are reported as web or app events. Events received outside of this window, as well as delayed batch events are considered as offline events.
The API for Conversions helps Pinterest provide a more comprehensive view of your campaign performance. All advertisers who currently use the Pinterest Tag will benefit from using it in tandem with the API for Conversions.
Benefits of Pinterest Conversions API (Actions)
The Pinterest Conversions API destination provides the following benefits:
- Fewer settings. Data mapping for actions-based destinations happens during configuration, which eliminates the need for most settings.
- Clearer mapping of data. Actions-based destinations enable you to define the mapping between the data Segment receives from your source, and the data Segment sends to the Pinterest Conversions API.
- Prebuilt mappings. Mappings for standard Pinterest Conversions API events, like
Add to Cart
, are prebuilt with the prescribed parameters and available for customization. - Support Deduplication. Deduplication removes duplicates events which improves the accuracy of your conversions
- Support for page calls. Page calls can be sent to Pinterest as a standard Page View.
- Support for multi-user arrays. User data nested within arrays, like the
User Data
array in the Order Completed event, can be sent to Pinterest. - Data normalization. Data is normalized before it’s hashed to send to Pinterest Conversions.
Getting started
Before connecting to the Pinterest Conversions destination, you must have a Pinterest account and an Ad Account ID.
To connect the Pinterest Conversions API Destination:
- From the Segment web app, navigate to Connections > Catalog.
- Search for Pinterest Conversions API in the Destinations Catalog, and select the destination.
- Click Configure Pinterest Conversions API.
- Select the source that will send data to Pinterest Conversions API and follow the steps to name your destination.
- On the Basic Settings page, configure the following fields:
- Destination Name
- Ad Account ID
- Conversions Token
- Navigate to the Mappings tab, there are already Prebuilt mapping like
Checkout,Search,Add to Cart
defined with prescribed parameter . All required ,recommended and optional fields are listed here - If you want to create New Mapping, and select Report Conversions Event ,configure and enable it.
- Follow the steps in the Destinations Actions documentation on Customizing mappings.
- Enable the destination using the Enable Destination toggle switch and click Save Changes.
Destination Settings
Setting | Description |
---|---|
Ad Account ID | Required. Unique identifier of an ad account. This can be found in the Pinterest UI by following the steps mentioned here. |
Conversion Token | Required. The conversion token for your Pinterest account. This can be found in the Pinterest UI by following the steps mentioned here. |
Available Presets
Pinterest Conversions API has the following presets:
Preset Name | Trigger | Default Action |
---|---|---|
View Category | Event type = "track" AND event = "Product Category Viewed" |
Report Conversion Event |
Add to Cart | Event type = "track" AND event = "Product Added" |
Report Conversion Event |
Page Visit | Event type = "page" |
Report Conversion Event |
Checkout | Event type = "track" AND event = "Checkout" |
Report Conversion Event |
Lead | Event type = "track" AND event = "Generate Lead" |
Report Conversion Event |
Watch Video | Event type = "track" AND event = "Product Video Watched" |
Report Conversion Event |
Sign Up | Event type = "track" AND event = "Signed Up" |
Report Conversion Event |
Search | Event type = "track" AND event = "Products Searched" |
Report Conversion Event |
Available Actions
Build your own Mappings. Combine supported triggers with the following Pinterest Conversions API-supported actions:
Mapping limits per destination
Individual destination instances have support a maximum of 50 mappings.
Report Conversion Event
Report events directly to Pinterest. Data shared can power Pinterest solutions that will help evaluate ads effectiveness and improve content, targeting, and placement of future ads.
Report Conversion Event is a Cloud action.
Field | Description |
---|---|
Event Name* | Type: STRING The conversion event type. For custom events, you must use the predefined event name “custom”. Please refer to the possible event types in Pinterest API docs. |
Action Source* | Type: STRING The source indicating where the conversion event occurred. This must be app_android, app_ios , web or offline. |
Event Timestamp* | Type: STRING Device IDs can be used to add and remove only anonymous users to/from a cohort. However, users with an assigned User ID cannot use Device ID to sync to a cohort. |
Event ID* | Type: STRING A unique id string that identifies this event and can be used for deduping between events ingested via both the conversion API and Pinterest tracking. |
Event Source URL | Type: STRING URL of the web conversion event. |
Opt Out | Type: BOOLEAN When action_source is web or offline, it defines whether the user has opted out of tracking for web conversion events. While when 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. |
User Data | Type: OBJECT Object containing customer information data. Note, It is required at least one of 1) em, 2) hashed_maids or 3) pair client_ip_address + client_user_agent.. |
Custom Data | Type: OBJECT Object containing customer information data. |
App ID | Type: STRING The app store app ID. |
App Name* | Type: STRING Name of the app. |
App Version | Type: STRING Version of the app. |
Device Brand | Type: STRING Brand of the user device. |
Device Carrier | Type: STRING User device’s mobile carrier. |
Device Model | Type: STRING Model of the user device. |
Device Type | Type: STRING Type of the user device. |
OS Version | Type: STRING Version of the device operating system. |
Wifi | Type: BOOLEAN Whether the event occurred when the user device was connected to wifi. |
Language | Type: STRING Two-character ISO-639-1 language code indicating the user’s language. |
By default, all mappings send as web
conversions. If you want to send events as mobile or offline conversions, update the Action Source in each mapping to be app_android
, app_ios
, offline
.
FAQ & Troubleshooting
Deduplication with Pinterest Tag
Pinterest cannot know if a conversion reported by the Tag and another reported by the API for Conversions are the same.
Because Pinterest recommends using both the API for Conversions and the Pinterest Tag, deduplication is an essential part of the implementation process. It helps to avoid double-counting of a single event when it’s sent through multiple sources, such as the Pinterest Tag and the Pinterest API for Conversions.
For example, if a user triggers an add to cart event and the tag reports the data using 123
as the event ID. Later, their web server reports the conversion to the API and uses 123
as the event ID. When Pinterest receives the events, Segment looks at the event IDs to confirm they correspond to the same event.
By using deduplication advertisers can report conversions using both the tag and the API without having to worry about over-counting conversions. This will result in more conversions being attributed than either alone, because if the tag doesn’t match an event, but the API does (or vice versa), the event can still be linked.
Advertisers should use deduplication for any events they expect to be reported by multiple sources across the API and the Pinterest Tag.
Conversion Events must meet the following requirements to be considered for deduplication:
- The event has non-empty and non-null values for
event_id
andevent_name
- The
action_source
of the event is notoffline
(for example, events that occurred in the physical world, like in a local store) Theaction_source
parameter is an enum that gives the source of the event –app_android
,app_ios
,web
, oroffline
. - The duplicate events arrived within 24 hours of the time of receipt of the first unique event.
Segment offers a client-side destination specifically designed for the Pinterest Tag. You can find detailed documentation and further information on how to implement this integration by following this link.
Events fail to send due to no App Name set
App Name is a mandatory field for many of the Pinterest Conversion API destination’s mappings. Segment’s mobile libraries automatically collect and map the App Name to the correct field. However, Segment’s web or server-based libraries do not automatically collect this field, which can cause mappings to fail. Segment recommends adding the App Name to the Segment event, or hardcoding a static string in the mapping as the App Name.
Limited Data Processing
Starting from Jan 1, 2023, Pinterest introduced the Limited Data Processing flag as per California Consumer Privacy Act (CCPA). With this flag set Pinterest will allow advertisers to comply with CCPA.
Advertisers are responsible for complying with user opt-outs, as well as identifying the user’s state of residency when implementing the Limited Data Processing flag.
Keep in mind that the Limited Data Processing flag could impact campaign performance and targeting use cases. Pinterest recommends using the Limited Data Processing flag on a per-user basis for best results.
LDP relies on 3 fields and is enabled only when all 3 combinations are met, if one of them is not met then LDP is disabled / ignored.
Field Name | Field Description | Required Value for LDP |
---|---|---|
opt_out_type |
Opt Out Type based on User’s privacy preference | “LDP” |
st |
State of Residence | “CA” |
country |
Country of Residence | “US” |
PII Hashing
Segment creates a SHA-256 hash of the following fields before sending to Pinterest:
- External ID
- Mobile Ad Identifier
- Phone
- Gender
- Date of Birth
- Last Name
- First Name
- City
- State
- Zip Code
- Country
User Data Parameters
Segment automatically maps User Data fields to their corresponding parameters as expected by the Conversions API before sending to Pinterest Conversions:
User Data Field | Conversions API User Data Parameter |
---|---|
External ID | external_id |
Mobile Ad Id | hashed_maids |
Client IP Address | client_ip_address |
Client User Agent | client_user_agent |
em |
|
Phone | ph |
Gender | ge |
Date of Birth | db |
Last Name | ln |
First Name | fn |
City | ct |
State | st |
Zip Code | zp |
Country | country |
Custom Data Parameters
Segment automatically maps Custom Data fields (excluding content_ids
, contents
, num_items
, opt_out_type
) to their corresponding parameters as expected by the Conversions API before sending to Pinterest Conversions:
User Data Field | Conversions API Custom Data Parameter |
---|---|
Currency | currency |
Value | value |
Content IDs | content_ids |
Contents | contents |
Number of Items | num_items |
Order ID | order_id |
Search String | search_string |
Opt Out Type | opt_out_type |
Server Event Parameter Requirements
Pinterest requires the action_source
server event parameter for all events sent to the Pinterest Conversions API. This parameter specifies where the conversions occur.
Verify Events in Pinterest Conversions Dashboard
After you start sending events, you should start seeing them in dashboard. You can confirm that Pinterest received them:
- Go to the Events Overview.
- Click on the Event History to see all the events sent to Pinterest conversions.
Settings
Segment lets you change these destination settings from the Segment app without having to touch any code.
Setting | Description |
---|---|
Ad Account ID (required) |
string . Unique identifier of an ad account. This can be found in the Pinterest UI by following the steps mentioned here. |
Conversion Token (required) |
password . The conversion token for your Pinterest account. This can be found in the Pinterest UI by following the steps mentioned here. |
This page was last modified: 03 Jun 2024
Need support?
Questions? Problems? Need more info? Contact Segment Support for assistance!