Overview

The Pinterest API for Conversions enables advertisers to send conversions directly to Pinterest via a server-to-server connection. Conversions captured with the Pinterest API can then be used for retargeting in campaigns and can be reviewed in conversion reporting for improved conversion visibility.

Through the Pinterest API for Conversions, advertisers can send:

  • Web conversions
  • In-App Conversions
  • Offline Conversions
  • Events can be received in real-time or within an hour of the event occurring and being captured. Events received outside this window or as part of a delayed batch event will be counted as offline conversions. 

    Using the Pinterest API for Conversions along with the Pinterest Tag can help maximize visibility into captured conversions. Our best practice is to use both conversion capturing solutions to ensure you’re receiving a comprehensive view of your conversion campaign performance.

    The Pinterest API

    The Pinterest API for Conversions is one of several products that live within our Pinterest API ecosystem. Anyone with a Pinterest Business account will be able to use the Pinterest API for Conversions, but this does not automatically grant access to the wider Pinterest API. 

    The Pinterest Developer Platform has information on all of Pinterest’s API products. 

    Getting Started

    Anyone with a Pinterest Business account has access to the Pinterest API for Conversions.

    To get started, you’ll first need to generate an access token. An access token is a string of characters that verifies the requests are being made and sent back to the correct user’s account. 

    To generate an access token: 

  • Login to your Pinterest business account
  • Click Ads in the top menu and choose Conversions
  • Select Conversion access token page from the left hand navigation
  • Click the Generate new token button
  • Copy the new access token and return to the setup process.
  • If you’re trying to access an account you don’t own, you’ll need to set up Business Access first. 

    Implementation

    Conversion Events: all event types available for capture on the Pinterest Tag are also available via the Pinterest API for Conversions. You can find a full list of the events and further information around their importance in our Pinterest API Developer Documentation.

    Setting up a server to server API integration requires developer and engineering resources from the website owner. The amount of technical developer effort will vary depending on:

  • Your developer’s familiarity with API integrations. If they have never done an API integration before, they might require additional work.  If you have implemented other conversion API’s, your developer should only need to make a few incremental changes.
  • The number of events being tracked and at what stage of the conversion process data will be sent to us.
  • If an advertiser wants or needs to use a 3rd party to integrate (ie. Shopify, GTM, Tealium).
  • If you’re already using the Pinterest Tag

    We strongly recommend using the Pinterest API for Conversions alongside the Pinterest Tag to ensure you’re maximizing your conversions. 

    If you’ve already set up the Pinterest Tag previously, you’ll need to ensure conversions aren’t being counted twice - once through the Pinterest Tag, and once through the API. 

    To achieve this, you’ll need to make sure the parameter, event_id is being passed back with conversions captured by both the Pinterest Tag and the Pinterest API for Conversions. 

    Our system will then recognize the event_ids as duplicates and only retain the first conversion captured. To ensure this deduplication is success, event_ids will need to be:

  • event_ids need to be identical between the same conversions - A person navigates to a webpage and a Page visit conversion is fired by both the Pinterest Tag and the Pinterest API. The two conversions will need to have matching event_ids sent back so our system recognizes they’re the same conversion. 
  • event_ids need to be unique for different conversions - A person navigates to a webpage and a Page visit conversion is fired by both the Pinterest Tag and the Pinterest API. The person then adds a t-shirt to their cart, which triggers the AddToCart event to fire on both the Pinterest Tag and the Pinterest API. While the event_ids fired for the same events need to match, the event_ids being sent for the Page visit event and the AddToCart event need to be unique. This way our system recognizes them as separate events.
  • Based on that event identifier and the event_name, Pinterest will remove any duplicate events from the record, provided that (a) the event did not take place offline (the action_source is not offline), and (b) Pinterest receives the duplicate events within 48 hours of one another.

    Verifying your setup

    Once you’ve finished setting up the API, you can verify conversion events are being received by checking:

  • Response Codes: the developer setting up your API integration can review the response codes returned with each request sent back after a conversion fires. 
  • Deduplication Page on Ads Manager: post-deduplicated conversions will appear on the Deduplication Page on Ads Manager. To access the deduplication page:
    • Login to your Pinterest business account
    • Click Ads in the top menu and choose Conversions
    • Select Deduplication from the left hand navigation.
  • Quality and resilience

    A resilient event setup includes additional conversion data that Pinterest can use to ensure that events will be matched and attributed correctly.  This additional data will help us provide more accurate reporting as ad industry policies change and evolve.

    Resilience levels

    There are three levels to rank an advertiser’s resilience: Poor, Good/Fair, and Great. Your resilience status is visible in the Conversion Health section of Ads Manager.

    Poor

    A poor status rating means that either:

  • an advertiser has IP/UA coverage < 100% of all events
  • an email or Mobile App ID is not shared in checkout events
  • an advertiser has the Pinterest tag implemented, but they are not sending all of the lower funnel tag events (add to cart, checkout, lead or signup) to the API.
  • Good / Fair

    A good or fair status rating is achieved when: 

  • an advertiser has 100% IP/UA coverage of all events 
  • An email or MAID is shared in checkout events 
  • if the advertiser has the Pinterest tag implemented, they have 100% of lower funnel tag events (either add to cart, checkout, lead or signup) received through the API.
  • Great

    A great status rating means that an advertiser meets all of the Good/Fair requirements and also sends all of the medium and low priority ids.

    Resilience ID’s and Signals

    To reach resilient advertiser status, Pinterest recommends sending the following signals.

     

    API ID's/Signals Weights/Rank
    hashed_maid High
    em High
    client_ip_address + client_user_agent High
    external_id Medium
    fn+In Medium
    click_id Low
    ph Low
    ge, bd, ct, st, zp, country Low
    Third Party Implementation

    Pinterest has several Third Party Integrations to help support your API adoption process. 

    Google Tag Manager - Server Side

    Connect your Google Tag Manager account with the Pinterest API for Conversions to find out how much Pinterest influences traffic to your store and sales of your products.

    This integration requires you to deploy a server container using your preferred cloud provider and knowledge of server side tagging. For more info on prerequisites visit the developer site

    Shopify

    This API for Conversions integration compliments the Pinterest Tag to ensure high data coverage and quality. As long as the Shopify app is installed, no action is required to take advantage of this enhancement. The changes will automatically be applied to the merchant’s store.

    Tealium

    Advertisers who are interested in Tealium, can set up the API for Conversions directly with the third party. Tealium builds the template and will help facilitate the integration with the advertiser. 

    The implementation process is outlined in Tealium’s Learning Center. Any questions on implementation support can be sent to support [at] tealium.com (support[at]tealium[dot]com)

    If you’re interested in any additional third party integrations, please reach out to your sales rep for more information. 

    Understanding Limited Data Processing

    Starting January 1, 2023, advertisers can use a Limited Data Processing flag to help them comply with the California Consumer Privacy Act, as amended by the California Privacy Rights Act (together, CCPA). With this flag in place, Pinterest will limit how we use certain data to help advertisers comply with user privacy settings. For example, an advertiser might implement the Limited Data Processing flag for California users who have opted out of the sale or sharing of their data under CCPA. When the Limited Data Processing flag is used, Pinterest will act as a service provider under CCPA with respect to flagged data from users in California.

    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.

    End of Other articles Links
    Still need help? Contact us
    User feedback
    Was this article helpful?

    collection_fields

    How can we make this article better?