Download OpenAPI specification:Download
You are viewing documentation specific to Pinner and will only see endpoints and guides curated for this App type. See Introduction to learn more.
Summary of changes for June
Due to low partner usage, we have decided to deprecate the GET /ads/v4/advertisers/{advertiser_id}/keywords/related endpoint. On June 30, 2022 we will enforce an end of life where any requests to this endpoint will receive a 410 error. The following endpoints can continue to be utilized to pull similar information:
To promote an Idea Pin,
Send a POST request to: https://api.pinterest.com/ads/ads/v4/advertisers/{advertiser_id}/ads
Reporting changes are the same as the reporting changes for Idea Pins with paid partnership with the exception of video metrics.
Our video metrics are calculated as follows:
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.
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.
Summary of changes for November
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”.
Changes to “rule” API param:
We are removing the claimed domain requirement to make it easier for all advertisers to create engagement audiences.
Changes to “rule” API param:
Advertisers with claimed domains can continue using claimed assets as data sources to increase the reach of their engagement audiences.
We are introducing the ability to create engagement audiences based on interactions with specific Pins, ads, campaigns, or campaign objectives.
Changes to “rule” API param:
We will deprecate the top repins endpoint (/v3/domains/
To promote an Idea Pin,
Send a POST request to: https://api.pinterest.com/ads/ads/v4/advertisers/{advertiser_id}/ads
Reporting changes are the same as the reporting changes for Idea Pins with paid partnership.
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:
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" }
The API requests for Slideshow Collections reporting are the same as for Standard Collections reporting. The same set of columns will be available.
To promote an Idea Pin with paid partnership,
Send a POST request to: https://api.pinterest.com/ads/ads/v4/advertisers/{advertiser_id}/ads
*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.
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.
The API requests for Idea ads reporting are the same as standard ad reporting, with the addition of these columns:
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
When an idea ad includes video assets, our video metrics are calculated as follows:
Go to your Pinterest API admin page to see the standalone endpoint docs for v4
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 create/update entities endpoint, new feature in v4)
Ex: POST /ads/v4/advertisers/
(bulk get entities endpoint)
Ex: GET /ads/v4/advertisers/
(get bulk request status endpoint)
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/
(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”
Endpoint paths that deal with the advertiser object or any child objects (campaigns, tags, campaigns, etc) are now prefixed with "/advertisers/
Ex: GET /ads/v4/advertisers/
(get a single campaign endpoint)
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.
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.
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.
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.
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.
You can now use the same URI with different http methods to do batch get, create, and update operations.
Examples:
GET /advertisers/
POST /advertisers/
PATCH /advertisers/
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"
}
]We have deprecated the following endpoints
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:
You may also reference ad_creative_type to determine type of Pin for Pin promotion purposes (ad formats). See Creative type enum
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.
When using the create endpoint , you can now include alternative text for improved accessibility.
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:
For detailed information about the changes please reference the document linked HERE.
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"
}
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}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}"
}]
}
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": ""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"
}
3rd party API partners should update their reporting to align with the Pinterest narrative of focusing on created vs curated content. To ease this migration for brands and creators, curated content will still be included by default. This option will be deprecated in late 2021 at which point only created content analytics will be returned. To update your reports and align with Pinterest, provide the include_curated parameter to the following endpoints with a value of 0:
| Param | Type | Description |
|---|---|---|
| include_curated | Integer | Enum: 0 1 2. 0 = get only created content analytics. 1 or 2 = get curated and created content analytics. Default is both. |
See User metrics API Reference
See Top video pins API Reference
Monthly viewers will change to Monthly views. This audience will only include views of created content. This is because the Monthly viewers metric will drop as a result of these changes, and we want to use this opportunity to move towards the ideal profile metric (lifetime views). This field is present in the user object response as profile_views. Please discontinue referencing profile_reach as it is now deprecated.