Pinterest Marketing API: Ads

Pinterest Marketing API: Ads

Download OpenAPI specification:Download

You are viewing documentation specific to Ads and will only see endpoints and guides curated for this App type. See Introduction to learn more.


March 2022

Summary of changes for March

  • Ads API v3 shutdown
  • Update to top pins metric sort options

Ads API v3 Shutdown

Ads API v3 has come to an end of life starting today March 1st, 2022. From now on, all ads/v3 endpoints will return a 410 error response. Please make requests to Ads API v4. Check out the v3 to v4 migration guide for an overview of the new changes. Learn more about our new ads v4 bulk features.

Update to top pins metric sort options

GET /v3/partners/analytics/users/{user}/pins/top/

We are removing support for sorting by rates in the top pins endpoint. The updated list of supported metrics for the sort_by parameter is impressions, engagements, pin clicks, outbound clicks, and saves.

November 2021

Summary of changes for November

  • Enhancements to Engagement Audiences
  • Deprecation of Top Repins endpoint

Engagement Audiences

New engagement action options

We are simplifying the process of creating engagement audiences by introducing the option to create engagement audiences from Pinners who have performed “any engagement action” or “optimized engagement actions”.

  • With “any engagement action”, you can reach audiences who have performed any engagement action such as video viewed %, Pin clicks, outbound clicks, saves, and comments with the advertiser’s content. With “optimized engagement actions”, Pinners are automatically selected based on their high intent actions such as saves and outbound clicks to help you get the best results.
  • The ability to create engagement audiences by selecting action types and % video viewed options will be removed, as these options will be automatically included in the “any engagement action” and ‘optimized engagement actions” segments.
  • The filters (Pin category and destination URL) and inputs for the lookback window will be removed as well.
  • The Pin id filter will no longer support “not equals” operation.

Changes to “rule” API param:

  1. Added field engager_type with values 1 (all engagers) or 2 (optimized engagers). Example: “engager_type”: 2
  2. Removed fields prefill, retention_days, url, engagement_type, pin_category, pin_video_view
  3. Update pin_id fields to a list of pinIDs only, operations are removed. Example: "pin_id":{"=":["229754018470533878"]} changed to "pin_id":["229754018470533878"]. We will no longer support "pin_id":{"!=":["229754018470533878"]}

Claimed domain updates

We are removing the claimed domain requirement to make it easier for all advertisers to create engagement audiences.

  • Advertisers without a claimed domain will now be able to create engagement audiences off user activity on their promoted and organic content.
  • Advertisers can select multiple claimed domains

Changes to “rule” API param:

  1. “engagement_domain” field becomes an optional list. Example: “engagement_domain”: ["”, “”]

Advertisers with claimed domains can continue using claimed assets as data sources to increase the reach of their engagement audiences.

  • Advertisers who claim their domain can continue to grow their engagement audiences based on user activity on Pinterest.
  • This includes Pins that link out to claimed domains that exist on sites such as Etsy and YouTube.

Targeting based on specific ad, campaign, or objective types

We are introducing the ability to create engagement audiences based on interactions with specific Pins, ads, campaigns, or campaign objectives.

  • Advertisers can create engagement audiences based on their Pin IDs, ad IDs, campaign IDs, or campaign objectives. With this functionality, advertisers can sequence messaging and guide audiences from inspiration to action.
  • An engagement audience can only have at most one of these filters.

Changes to “rule” API param:

  1. Pin ID: "pin_id":["796222409119557197","796222409119557198"]
  2. Ad ID: "g_pin_promotion_id":["687224702315","687224702193"]
  3. Campaign ID: "g_campaign_id":["626744680725","626744680640"]
  4. Campaign objective: "objective":["AWARENESS","TRAFFIC","CATALOG_SALES","WEB_CONVERSION","VIDEO_VIEW"]

Deprecation of Top Repins endpoint

We will deprecate the top repins endpoint (/v3/domains//pins/top/repins/) on December 15th, 2021. If you currently use this endpoint, it will no longer be supported past that date. To fetch the top repins for a partner, please use the top pins endpoint, with the sort_by_metrics parameter set to "SAVE".

September 2021