Pinterest

Developers

Pinterest Marketing API: Content

Pinterest Marketing API: Content

Download OpenAPI specification:Download

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

Changelog

November 2021

Summary of changes for November

  • Enhancements to Engagement Audiences

Engagement Audiences

###For changes to request & response parameters 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).
    1. 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.
    1. Example: "pin_id":{"=":["229754018470533878"]} changed to "pin_id":["229754018470533878"]. We will no longer support "pin_id":{"!=":["229754018470533878"]}

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.
    1. Example: “engagement_domain”: ["mydomain.com”, “mydomain2.com”]

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.

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"]

September 2021

Summary of changes for September

  • API support for Idea ads (beta)

Idea ads (beta)

Ad Creation (promoting Idea Pins)

To promote an Idea Pin,

Send a POST request to: https://api.pinterest.com/ads/ads/v4/advertisers/{advertiser_id}/ads

  1. Set "creative_type" to "STORY"
  2. Set "destination_url" as it is required for Idea ads
  3. Set "pin" to an Idea Pin id.

Reporting

Reporting changes are the same as the reporting changes for Idea Pins with paid partnership.

  • API support for Slideshow for Collections

Slideshow for Collections

Ad Creation

To create a slideshow promotion, use the same API call as you would to promote a regular product group or a standard collection. Just make these adjustments:

  1. Set "creative_type" to "SHOP_THE_PIN"
  2. Set "collections_hero_pin_id" to null
  3. Set "collections_hero_destination_url" to your desired hero landing page
  4. Set "slideshow_collections_title" to your desired slideshow title
  5. Set optional fields, e.g. status, tracking_url, and slideshow_collections_description

Send the data in the body of a POST request to: https://api.pinterest.com/ads/v4/advertisers/{advertiser_id}/promoted_product_groups/. See the example below for more information.

Request body: { "ad_group_id": "1234", "promoted_catalog_product_groups": [ { "status": "ACTIVE", "catalog_product_group_id": "1234", "creative_type": "SHOP_THE_PIN", "collections_hero_destination_url": "http://www.mylandingpage.com", "slideshow_collections_title": "My Slideshow Title" } ] }

You should receive a response as follows: { "status": "success", "code": 0, "data": [ { "data": { "collections_hero_destination_url": "http://www.mylandingpage.com", "slideshow_collections_title": "My Slideshow Title", "tracking_url": null, "id": "1234", "parent_id": null, "definition": "/", "bid_in_micro_currency": 0, "creative_type": "SHOP_THE_PIN", "collections_hero_pin_id": null, "relative_definition": "/", "catalog_product_group_id": "1234", "ad_group_id": "1234", "type": "productgroup", "catalog_product_group_name": "CPG Name", "slideshow_collections_description": null, "status": "ACTIVE", "included": null } } ], "message": "ok", "endpoint_name": "create_promoted_catalog_product_groups_handler" }

Reporting

The API requests for Slideshow Collections reporting are the same as for Standard Collections reporting. The same set of columns will be available.

August 2021

Summary of changes for August

  • API support for Idea ads with paid partnership

Idea ads with paid partnership

Ad Creation (promoting Idea Pins with paid partnership)

To promote an Idea Pin with paid partnership,

Send a POST request to: https://api.pinterest.com/ads/ads/v4/advertisers/{advertiser_id}/ads

  1. Set "creative_type" to "STORY"
  2. Set "destination_url" as it is required for Idea ads
  3. Set "pin" to an eligible* Pin id.

*The Pin must be an Idea Pin with paid partnership.

An Idea Pin with paid partnership is an Idea Pin created by a creator, not the current advertiser. The current advertiser is the partner paying the creator for the Pin. The sponsorship relationship between the Pin and the advertiser is established during Pin creation in the Idea Pin builder using the paid partnership tool. The advertiser must approve the paid partnership tag by going directly to the Pin on a desktop web browser.

Audiences

Setting the ad’s target audience is managed through the Advertiser’s account. You are unable to target the Creator’s audiences at this time.

Reporting

The API requests for Idea ads reporting are the same as standard ad reporting, with the addition of these columns:

  • IDEA_PIN_PAGE_FORWARD_1
  • IDEA_PIN_PAGE_FORWARD_2
  • IDEA_PIN_PAGE_BACKWARD_1
  • IDEA_PIN_PAGE_BACKWARD_2
  • TOTAL_IDEA_PIN_PAGE_FORWARD
  • TOTAL_IDEA_PIN_PAGE_BACKWARD

As with other columns, the 1 suffix indicates paid metrics, the _2 earned metrics, and TOTAL columns are the sum of the two. These metrics will be aggregated into the engagement metric as well.

Detailed definitions or tooltips for each metric are below

  • Earned Idea Pin page forward: The number of times someone advances to a new page within your Idea Pin on someone else's board
  • Paid Idea Pin page forward: The number of times someone advances to a new page to a new page within an Idea Pin you promoted
  • Earned Idea Pin page backward: The number of times someone goes back to a previous page within your Idea Pin on someone else's board
  • Paid Idea Pin page backward: The number of times someone goes back to a previous page within an Idea Pin you promoted
  • Total Idea Pin page forward: The total number of times someone advances to a new page within an Idea Pin, including paid and earned
  • Total Idea Pin page backward: The total number of times someone goes back to a previous page within an Idea Pin, including paid and earned

Video metrics

When an idea ad includes video assets, our video metrics are calculated as follows:

  • We treat all videos within an idea ad as one video and calculate standard video metrics across this video Eg: for Video 1 (1 min) | Video 2 (2 mins) | Video 3 (1 min), the total video length is 1+2+1 = 4 mins
  • This aggregation occurs even if multiple videos are separated by static assets Eg: for Video 1 (1 min) | Image 2 | Video 2 (2 mins) | Image 2 | Video 3 (1 min), the total video length is 1+2+1 = 4 mins
  • We only count actual watchtime if the user skips to the next video card Eg: If a user watched 10 seconds of Video 1, we count 10 secs of watchtime and not 1 min)
  • The total video length is counted as watch time if the user auto-advanced from one video card to the next

July 2021

Summary of changes for July

 

Ads API v4 release

To access API v4 documentation

Go to your Pinterest API admin page to see the standalone endpoint docs for v4

New Features / Global Changes

New Bulk API

Bulk APIs are introduced for batch creating, updating and downloading any of advertiser entities (including campaigns, ad groups, ads, keywords and product groups) in a single request. The bulk request is processed asynchronously, and request status fetched using the request id. Once a request completes successfully, a download url is provided in the request status.

Ex: POST /ads/v4/advertisers//bulk_upsert/
(bulk create/update entities endpoint, new feature in v4)

Ex: POST /ads/v4/advertisers//bulk_get/
(bulk get entities endpoint)

Ex: GET /ads/v4/advertisers//bulk/
(get bulk request status endpoint)

Pin promotions are now "ads"

As part of a larger consistency and clarity change throughout our products - everywhere we used the term "pin_promotion/pin_promotions" we now use "ad/ads".

Ex: GET /ads/v4/advertisers//ads//
(get a single ad endpoint)

NOTE: early in the v4 launch some places in our documentation may still refer to "promoted pins" or "pin promotions" - we're working on updating all these references to be “ad”/”ads”

Endpoints prefixed with "/advertisers//"

Endpoint paths that deal with the advertiser object or any child objects (campaigns, tags, campaigns, etc) are now prefixed with "/advertisers//" to clarify this relationship. By requiring the advertiser ID to be passed in the URI, we hope to minimize confusion when managing multiple advertiser accounts. This also allows us to assign rate limits differently (see "Ratelimit quotas assigned by advertiser ID…" below).

Ex: GET /ads/v4/advertisers//campaigns//
(get a single campaign endpoint)

All parameters and returned responses now use snake_case (previously some were camelCase)

All object type fields now will use snake case formatting.

Ex: For ad groups, You may get optimization_goal_metadata.conversionTagV3GoalMetadata in v3 but this will be optimization_goal_metadata.conversion_tag_v3_goal_metadata in v4.

Campaign objective type updates

APP_INSTALL objective has been deprecated.
TRAFFIC objective has been renamed to CONSIDERATION.
Please note these changes have not been fully updated in the documentation. We are working on publishing the fix soon.

Rate limit quotas assigned by advertiser ID

Rate limiting quotas for Ads API v4 are now measured against the relevant advertiser ID in each request, not the user ID associated with the access token used on the request. This should result in an overall increase in rate limiting quotas for your apps/end users.

In v3 - a user might have access to three different advertiser IDs, their quota of 400 write requests would need to be split across all three.
In v4 - the same user would now have three separate quotas of 400 write requests (one for each advertiser ID).

Rate limit header format changed, only returned if request is limited

We now only return rate limit headers when your request is limited. The format of the rate limit headers has also been updated to align with the IETF RateLimit headers draft spec.

In v3 - the following headers were returned on every request:
x-userendpoint-ratelimit-limit
x-userendpoint-ratelimit-remaining
x-userendpoint-ratelimit-reset-seconds

In v4 - the following headers will ONLY be returned when the request has been limited.

RateLimit-Limit - provides information about the limit that has been reached including the quota and time window that apply
RateLimit-Remaining - will be 0, indicating there is no more quota to expend
Retry-After - minimum time (in seconds) before you should attempt to make another request, but not a guarantee that your request will be successful after this time

Example #1 - per user limit
A per user or advertiser limit has been reached (but your app overall can continue to make requests).

RateLimit-Limit: 30, 30;w=60
RateLimit-Remaining: 0
Retry-After: 30

The limit quota here is defined as "30;w=60" or "30 requests per 60 seconds". The reset field indicates there are 30 seconds left in the window that this limit was triggered.

Example #2 - per app (aka "client") limit
A per app limit has been reached (but the specific user you are making requests for is not being limited).

RateLimit-Limit: 1000, 1000;w=60
RateLimit-Remaining: 0
Retry-After: 30

The limit quota here is defined as "1000;w=60" or "1000 requests per 60 seconds". The reset field indicates there are 30 seconds left in the window that this limit was triggered.

Example #3 - Pinterest backend service limit
In the case of downstream capacity/availability issues with our internal systems - we may apply a generic limit that isn't necessarily related to your app's or users' behavior.

RateLimit-Limit: 0, 0
RateLimit-Remaining: 0
Retry-After: 2

Reminder: the Retry-After value here is the minimum time your client should wait before making another request, but not a guarantee that your request will be successful.

Hidden "is_managed" campaigns fully visible

Previously, campaigns with the "is_managed" field set to "true" would be hidden and not included in certain endpoint results. The is_managed field was a remnant of a Pinterest Ads Manager functionality that allowed Advertiser and account teams to hide the campaign from being exposed to API partners. We found it was often not used correctly and created too much confusion. In v4 we have removed this field and we no longer hide or filter these campaigns.

Pagination supported on more endpoints

Standard pagination functionality (with a default page size of 25 records) is now supported on more endpoints, including: product groups, reporting, and tag management endpoints. You’ll be able to find details of each specific endpoint that now uses pagination below.

Batch operations for campaigns, ad groups, and ads

You can now use the same URI with different http methods to do batch get, create, and update operations.

Examples:
GET /advertisers//campaigns/ -> Batch get campaigns
POST /advertisers//campaigns/ -> Batch create campaigns
PATCH /advertisers//campaigns/ -> Batch update campaigns

For batch get operations - you will be able to optionally filter by a list of arbitrary entity IDs, or parent entity IDs (among other things).

For batch create and update operations - you must use the "content-type": "application/json" header and pass an array of objects.

Ex: POST /advertisers/{advertiser_id}/campaigns/

[
  {
    "advertiser_id": 549755885175,
    "name": "ACME Tools Campaign #1",
    "status": "ACTIVE",
    "lifetime_spend_cap": 1432744744,
    "daily_spend_cap": 1432744744,
    "order_line_id": 549755885175,
    "tracking_urls": {},
    "mobile_measurement_partner": "APPSFLYER",
    "measurement_partner_campaign_id": "549755885175",
    "objective_type": "AWARENESS"
  },
  {
    "advertiser_id": 549755885175,
    "name": "ACME Tools Campaign #2",
    "status": "ACTIVE",
    "lifetime_spend_cap": 1432744744,
    "daily_spend_cap": 1432744744,
    "order_line_id": 549755885175,
    "tracking_urls": {},
    "mobile_measurement_partner": "APPSFLYER",
    "measurement_partner_campaign_id": "549755885175",
    "objective_type": "AWARENESS"
  }
]

June 2021

Summary of changes for June

 

Deprecating two product feed endpoints

We have deprecated the following endpoints

GET /ads/v3/product_feeds/default/metadata/counts/
GET /ads/v3/product_feeds/default/metadata/{attribute_name}/

Pin formats

To facilitate identification of the type of Pin, please reference the native_format_type attribute on the Pin object.


{
    "status":"success",
    "message":"ok",
    "code":0,
    "data":{
      ...,
      "ad_creative_type":"REGULAR",
      "native_format_type":"SINGLE_IMAGE",
      ...,
    }
}

Pin format enum for native_format_type:

  • CAROUSEL
  • COLLAGE_PIN
  • LENS_IMAGE
  • PLACE
  • SINGLE_IMAGE
  • STORYBOARD
  • STORY_PIN
  • VIDEO
  • VIRTUAL_TRY_ON_IMAGE

You may also reference ad_creative_type to determine type of Pin for Pin promotion purposes (ad formats). See Creative type enum

 

[Ads] disregard campaign objective_type WEB_SESSIONS

For API endpoints that return campaign objective type, you may notice a new objective type WEB_SESSIONS. Please disregard this option as it is not yet available for advertisers to use.

Pin Create endpoint now has option to include alternative text

When using the create endpoint , you can now include alternative text for improved accessibility.

 

Updated click reporting metrics

We’re launching a number of updates to our metrics to help business account users better meet their objectives and optimize their content. If you work with advertisers or creators with business accounts, these updates will give you a more complete understanding of performance, both paid and organic, on Pinterest.


You can find a comprehensive list of updates for paid ads and organic content within this article. Technical details are as described below.


Click metrics across both paid and organic platforms will also be unified for consistency and additional clarity. This build is mandatory, and we ask that partners implement these updates by January 21, 2021 midnight UTC (or January 20, 2021, 5pm PT).


Note: For the organic endpoints, we will continue to support calls for the legacy metrics (CLOSEUP, CLICKTHROUGH, CLOSEUP_RATE, and CLICKTHROUGH_RATE) in parallel with the new metrics (PIN_CLICK, OUTBOUND_CLICK, PIN_CLICK_RATE, OUTBOUND_CLICK_RATE) for 1 month (until February 21, 2021) at which point we will deprecate the legacy metrics.


Summary of changes:

  • Updating metrics naming from ‘Link clicks’ to ‘Pin clicks’
  • Introducing new metrics: Outbound clicks

For detailed information about the changes please reference the document linked HERE.


For detailed information about the metrics that are changing please reference the document linked HERE.

Advertising changes

GET /ads/v3/resources/delivery_metrics/

See Delivery metrics definitions API Reference

Change: response
Deprecate: CLOSEUP_1, CLOSEUP_2 New: OUTBOUND_CLICK_1, OUTBOUND_CLICK_2
Change to existing metrics: CLICKTHROUGH_1, CLICKTHROUGH_2, CLICKTHROUGH_1_GROSS


Example Response:

{ "status": "success", "code": 0, "data": { "metrics": [{ "name": "CLICKTHROUGH_1", "definition": "Paid pinlink clicks" }, { "name": "CLICKTHROUGH_2", "definition": "Earned pinlink clicks" }, { "name": "CLICKTHROUGH_1_GROSS", "definition": "Gross pinlink clicks" }, { "name": "CLOSEUP_1", "definition": "Paid closeups" }, { "name": "CLOSEUP_2", "definition": "Earned closeups" }, { "name": "OUTBOUND_CLICK_1", "definition": "Paid outbound clicks" }, { "name": "OUTBOUND_CLICK_2", "definition": "Earned outbound clicks" }...] }, "message": "ok", "endpoint_name": "ads_v3_get_delivery_metrics_handler" }


POST /ads/v3/reports/async/{advertiser}/delivery_metrics/

See Request report API Reference

Change: metrics (Request body schema)
Deprecate: CLOSEUP_1, CLOSEUP_2 New: OUTBOUND_CLICK_1, OUTBOUND_CLICK_2


Example Request:

curl --request POST -s https://api.pinterest.com/ads/v3/reports/async/{advertiser_id}/delivery_metrics/?start_date={start_date}&end_date={end_date}&level={level}&metrics=OUTBOUND_CLICK_1,OUTBOUND_CLICK_2&access_token={access_token}

GET /ads/v3/advertisers/

See Delivery Get advertiser accounts API Reference

Change: downloaded metrics report
Deprecate: CLOSEUP_1, CLOSEUP_2 New: OUTBOUND_CLICK_1, OUTBOUND_CLICK_2


Example Report:

{ "{advertiser_id}": [{ "ADVERTISER_ID": {advertiser_id}, "CLOSEUP_2": 0, "DATE": "{date}", "CLOSEUP_1": 0, "CLICKTHROUGH_1": 1, "OUTBOUND_CLICK_1": 0, "OUTBOUND_CLICK_2": 0 }, { "CLICKTHROUGH_1": 1, "CLICKTHROUGH_2": 1, "CLOSEUP_2": 0, "CLOSEUP_1": 0, "OUTBOUND_CLICK_1": 0, "OUTBOUND_CLICK_2": 0, "ADVERTISER_ID": {advertiser_id}, "DATE": "{date}" }] }


Organic Changes

GET /v3/partners/analytics/users/{user}/metrics/

See User metrics API Reference

Changes: metric_types (Request body schema), response
Deprecate: CLOSEUP, CLOSEUP_RATE, CLICKTHROUGH, CLICKTHROUGH_RATE New: PIN_CLICK, PIN_CLICK_RATE, OUTBOUND_CLICK, OUTBOUND_CLICK_RATE
Note: CLOSEUP and CLICKTHROUGH will still be usable until February 21, 2021 midnight UTC. They will return the data for PIN_CLICK and OUTBOUND_CLICK, but they will have the response key for CLOSEUP and CLICKTHROUGH. This is simply to maintain backward compatibility as partners migrate to the new metrics.


Example Request:

curl -X GET https://api.pinterest.com/v3/partners/analytics/users/{user_id}/metrics/?start_date={start_date}&end_date={start_date}&metric_types=CLICKTHROUGH,CLICKTHROUGH_RATE,OUTBOUND_CLICK,OUTBOUND_CLICK_RATE,CLOSEUP,CLOSEUP_RATE,PIN_CLICK,PIN_CLICK_RATE&access_token={access_token}

Example Response:
{ "status": "success", "code": 0, "data": { "all": { "summary_metrics": { "CLICKTHROUGH": 1, "CLICKTHROUGH_RATE": 0.012195121951219513, "OUTBOUND_CLICK":1, "OUTBOUND_CLICK_RATE":0.012195121951219513, "CLOSEUP": 4, "CLOSEUP_RATE": 0.04878048780487805, "PIN_CLICK": 4, "PIN_CLICK_RATE": 0.04878048780487805 }, "daily_metrics": [{ "date": "", "data_status": "READY", "metrics": { "CLICKTHROUGH": 0, "CLICKTHROUGH_RATE": 0.0, "OUTBOUND_CLICK":0, "OUTBOUND_CLICK_RATE":0.0, "CLOSEUP": 0, "CLOSEUP_RATE": 0.0, "PIN_CLICK": 0, "PIN_CLICK_RATE": 0.0 } }] } }, "message": "ok", "endpoint_name": "v3_analytics_partner_metrics" }

 

Removal of curated content from Analytics