Version: 5.23.0
Pinterest's REST API
Connect Pinterest users to external platform accounts.
| Operation | Description |
|---|
View analytical information about advertising.
Note: If the current operation_user_account (defined by the access token) has access to another user's Ad Accounts via Pinterest Business Access, you can modify your request to use the current operation_user_account's permissions to those Ad Accounts by including the ad_account_id in the path parameters for the request (e.g. .../?ad_account_id=12345&...).
Create, update, or download ads-related entities in bulk.
| Operation | Description |
|---|---|
| POST /ad_accounts/{ad_account_id}/bulk/download | Get advertiser entities in bulk |
| POST /ad_accounts/{ad_account_id}/bulk/upsert | Create/update ad entities in bulk |
| GET /ad_accounts/{ad_account_id}/bulk/{bulk_request_id} | Download advertiser entities in bulk |
View, create or update campaigns.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/campaigns | List campaigns |
| POST /ad_accounts/{ad_account_id}/campaigns | Create campaigns |
| PATCH /ad_accounts/{ad_account_id}/campaigns | Update campaigns |
| GET /ad_accounts/{ad_account_id}/campaigns/analytics | Get campaign analytics |
| GET /ad_accounts/{ad_account_id}/campaigns/targeting_analytics | Get targeting analytics for campaigns |
| GET /ad_accounts/{ad_account_id}/campaigns/{campaign_id} | Get campaign |
| GET /ad_accounts/{ad_account_id}/pins/analytics | Get pins analytics |
View and manage catalog feeds.
| Operation | Description |
|---|---|
| GET /catalogs/feeds | List feeds |
| POST /catalogs/feeds | Create feed |
| GET /catalogs/feeds/{feed_id} | Get feed |
| PATCH /catalogs/feeds/{feed_id} | Update feed |
| DELETE /catalogs/feeds/{feed_id} | Delete feed |
| POST /catalogs/feeds/{feed_id}/ingest | Ingest feed items |
| GET /catalogs/feeds/{feed_id}/processing_results | List feed processing results |
| GET /catalogs/processing_results/{processing_result_id}/item_issues | List item issues |
View and manage catalog items directly without a feed.
| Operation | Description |
|---|---|
| POST /catalogs/items | Get catalogs items (POST) |
| POST /catalogs/items/batch | Operate on item batch |
| GET /catalogs/items/batch/{batch_id} | Get item batch status |
View and manage catalog product groups using filters.
| Operation | Description |
|---|---|
| DELETE /catalogs/product_groups/multiple | Delete product groups |
| POST /catalogs/product_groups/multiple | Create product groups |
| GET /catalogs/product_groups | List product groups |
| POST /catalogs/product_groups | Create product group |
| GET /catalogs/product_groups/{product_group_id} | Get product group |
| DELETE /catalogs/product_groups/{product_group_id} | Delete product group |
| PATCH /catalogs/product_groups/{product_group_id} | Update single product group |
| GET /catalogs/product_groups/{product_group_id}/product_counts | Get product counts |
| GET /catalogs/product_groups/{product_group_id}/products | List products by product group |
| POST /catalogs/products/get_by_product_group_filters | List products by filter |
View and manage catalog regions defined by sets of postal codes.
| Operation | Description |
|---|
View and manage reports about catalogs.
| Operation | Description |
|---|---|
| POST /catalogs/reports | Build catalogs report |
| GET /catalogs/reports | Get catalogs report |
| GET /catalogs/reports/stats | List report stats |
View and manage catalog supplemental items.
| Operation | Description |
|---|
Manage information about shopping product catalogs and items.
| Operation | Description |
|---|---|
| GET /catalogs | List catalogs |
| POST /catalogs | Create catalog |
| GET /catalogs/available_filter_values | List available filter values |
Get the Event Quality Score (EQS) of your conversion signals.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/conversion_eqs | Get event quality score (EQS) |
View, create or update ad groups.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/ad_groups | List ad groups |
| POST /ad_accounts/{ad_account_id}/ad_groups | Create ad groups |
| PATCH /ad_accounts/{ad_account_id}/ad_groups | Update ad groups |
| GET /ad_accounts/{ad_account_id}/ad_groups/analytics | Get ad group analytics |
| GET /ad_accounts/{ad_account_id}/ad_groups/targeting_analytics | Get targeting analytics for ad groups |
| POST /ad_accounts/{ad_account_id}/ad_groups/audience_sizing | Get audience sizing |
| GET /ad_accounts/{ad_account_id}/ad_groups/{ad_group_id} | Get ad group |
| POST /ad_accounts/{ad_account_id}/bid_floor | Get bid floors |
Submit conversion events via the Pinterest API.
| Operation | Description |
|---|---|
| POST /ad_accounts/{ad_account_id}/events | Send conversions |
View, create, or update conversion tags.
| Operation | Description |
|---|---|
| POST /ad_accounts/{ad_account_id}/conversion_tags | Create conversion tag |
| GET /ad_accounts/{ad_account_id}/conversion_tags | List conversion tags |
| GET /ad_accounts/{ad_account_id}/conversion_tags/ocpm_eligible | Get Ocpm eligible conversion tags |
| GET /ad_accounts/{ad_account_id}/conversion_tags/page_visit | Get page visit conversion tags |
| GET /ad_accounts/{ad_account_id}/conversion_tags/{conversion_tag_id} | Get conversion tag |
View, create, or update customer lists.
| Operation | Description |
|---|---|
| POST /ad_accounts/{ad_account_id}/customer_lists | Create customer lists |
| GET /ad_accounts/{ad_account_id}/customer_lists | Get customer lists |
| GET /ad_accounts/{ad_account_id}/customer_lists/{customer_list_id} | Get customer list |
| PATCH /ad_accounts/{ad_account_id}/customer_lists/{customer_list_id} | Update customer list |
View, create, or update commerce integrations.
| Operation | Description |
|---|---|
| POST /integrations/commerce | Create commerce integration |
| GET /integrations/commerce/{external_business_id} | Get commerce integration |
| PATCH /integrations/commerce/{external_business_id} | Update commerce integration |
| DELETE /integrations/commerce/{external_business_id} | Delete commerce integration |
| POST /integrations/logs | Receives batched logs from integration applications. |
| GET /integrations | Get integration metadata list |
| GET /integrations/{id} | Get integration metadata |
View, create or update keywords.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/keywords | Get keywords |
| POST /ad_accounts/{ad_account_id}/keywords | Create keywords |
| PATCH /ad_accounts/{ad_account_id}/keywords | Update keywords |
| GET /ad_accounts/{ad_account_id}/keywords/metrics | Get country's keyword metrics |
| GET /trends/keywords/{region}/top/{trend_type} | List trending keywords |
View, create, or update lead ads.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/leads/subscriptions | Get lead ads subscriptions |
| POST /ad_accounts/{ad_account_id}/leads/subscriptions | Create lead ads subscription |
| GET /ad_accounts/{ad_account_id}/leads/subscriptions/{subscription_id} | Get lead ads subscription by ID |
| DELETE /ad_accounts/{ad_account_id}/leads/subscriptions/{subscription_id} | Delete lead ads subscription |
View lead forms.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/lead_forms | List lead forms |
| POST /ad_accounts/{ad_account_id}/lead_forms | Create lead forms |
| PATCH /ad_accounts/{ad_account_id}/lead_forms | Update lead forms |
| GET /ad_accounts/{ad_account_id}/lead_forms/{lead_form_id} | Get lead form by id |
| POST /ad_accounts/{ad_account_id}/lead_forms/{lead_form_id}/test | Create lead form test data |
Create and export leads information from lead ads.
| Operation | Description |
|---|---|
| POST /ad_accounts/{ad_account_id}/leads_export | Create a request to export leads collected from a lead ad |
| GET /ad_accounts/{ad_account_id}/leads_export/{leads_export_id} | Get the lead export from the lead export create call |
Register and manage media uploads.
| Operation | Description |
|---|---|
| GET /media | List media uploads |
| POST /media | Register media upload |
| GET /media/{media_id} | Get media upload details |
Submit Measurement Source of Truth attributed conversion events via the Pinterest API.
| Operation | Description |
|---|---|
| POST /ad_accounts/{ad_account_id}/msot/events | Send Measurement Source Of Truth (MSOT) attributed conversion events |
View, create or update ads.
| Operation | Description |
|---|---|
| POST /ad_accounts/{ad_account_id}/ad_previews | Create ad preview with pin or image |
| GET /ad_accounts/{ad_account_id}/ads | List ads |
| POST /ad_accounts/{ad_account_id}/ads | Create ads |
| PATCH /ad_accounts/{ad_account_id}/ads | Update ads |
| GET /ad_accounts/{ad_account_id}/ads/analytics | Get ad analytics |
| GET /ad_accounts/{ad_account_id}/ads/targeting_analytics | Get targeting analytics for ads |
| GET /ad_accounts/{ad_account_id}/ads/{ad_id} | Get ad |
Generate and refresh OAuth access tokens.
| Operation | Description |
|---|---|
| POST /oauth/conversion_token | Generate OAuth access token for conversion API |
| POST /oauth/token | Generate OAuth access token |
| POST /oauth/token/revoke | Revoke a token |
View order lines.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/order_lines | Get order lines |
| GET /ad_accounts/{ad_account_id}/order_lines/{order_line_id} | Get order line |
View, create, update, or delete information about Pins.
| Operation | Description |
|---|---|
| POST /pins | Create Pin |
| GET /pins | List Pins |
| GET /pins/{pin_id} | Get Pin |
| PATCH /pins/{pin_id} | Update Pin |
| DELETE /pins/{pin_id} | Delete Pin |
| GET /pins/{pin_id}/analytics | Get Pin analytics |
| GET /pins/analytics | Get multiple Pin analytics |
| POST /pins/{pin_id}/save | Save Pin |
View, create, update, or delete information about promoted product groups.
| Operation | Description |
|---|---|
| POST /ad_accounts/{ad_account_id}/product_group_promotions | Create product group promotions |
| PATCH /ad_accounts/{ad_account_id}/product_group_promotions | Update product group promotions |
| GET /ad_accounts/{ad_account_id}/product_group_promotions | Get product group promotions |
| GET /ad_accounts/{ad_account_id}/product_group_promotions/{product_group_promotion_id} | Get a product group promotion by id |
| GET /ad_accounts/{ad_account_id}/product_groups/analytics | Get product group analytics |
View, create, update, or delete promotions.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/promotions | Get promotions |
| POST /ad_accounts/{ad_account_id}/promotions | Create promotions |
| PATCH /ad_accounts/{ad_account_id}/promotions | Update promotions |
| GET /ad_accounts/{ad_account_id}/promotions/{promotion_id} | Get promotion by id |
| DELETE /ad_accounts/{ad_account_id}/promotions/{promotion_id} | Delete promotion by id |
View metadata about available metrics and targeting options in the Pinterest API.
| Operation | Description |
|---|---|
| GET /resources/ad_account_countries | Get ad accounts countries |
| GET /resources/delivery_metrics | Get available metrics' definitions |
| GET /resources/lead_form_questions | Get lead form questions |
| GET /resources/metrics_ready_state | Get metrics ready state |
| GET /resources/targeting/interests/{interest_id} | Get interest details |
| GET /resources/targeting/{targeting_type} | Get targeting options |
Search for Pins and boards owned by the current user.
| Operation | Description |
|---|---|
| GET /search/boards | Search user's boards |
| GET /search/pins | Search user's Pins |
| GET /search/partner/pins | Search pins by a given search term |
View, create or update targeting templates.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/targeting_templates | List targeting templates |
| POST /ad_accounts/{ad_account_id}/targeting_templates | Create targeting templates |
| PATCH /ad_accounts/{ad_account_id}/targeting_templates | Update targeting templates |
View related and suggested terms for ads targeting.
| Operation | Description |
|---|---|
| GET /terms/related | List related terms |
| GET /terms/suggested | List suggested terms |
View Advertising Terms Of Service.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/terms_of_service | Get terms of service |
View, create, or update advanced auction item bid options.
| Operation | Description |
|---|---|
| POST /advanced_auction/items/get | Get item bid options (POST) |
| POST /advanced_auction/items/submit | Operate on item level bid options |
View user accounts associated with a given access token.
| Operation | Description |
|---|---|
| GET /user_account | Get user account |
| GET /user_account/analytics | Get user account analytics |
| GET /user_account/analytics/top_pins | Get user account top pins analytics |
| GET /user_account/analytics/top_video_pins | Get user account top video pins analytics |
| GET /user_account/businesses | List linked businesses |
| GET /user_account/followers | List followers |
| GET /user_account/following | List following |
| GET /user_account/following/boards | List following boards |
| POST /user_account/following/{username} | Follow user |
| POST /user_account/websites | Verify website |
| GET /user_account/websites | Get user websites |
| DELETE /user_account/websites | Unverify website |
| GET /user_account/websites/verification | Get user verification code for website claiming |
| GET /users/{username}/interests/follow | List following interests |
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/advertiser_defined_events | Get advertiser defined events |
| Operation | Description |
|---|---|
| POST /ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}/uploads | Create customer list upload |
| GET /ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}/uploads/{customer_list_upload_id} | Get customer list upload |
| POST /ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}/uploads/{customer_list_upload_id}/run | Run customer list upload |
| Operation | Description |
|---|---|
| POST /ad_accounts/{ad_account_id}/labels | Create labels |
| GET /ad_accounts/{ad_account_id}/labels | List labels |
| PATCH /ad_accounts/{ad_account_id}/labels | Update labels |
| Operation | Description |
|---|---|
| GET /businesses/employers | List business employers for user |
| PATCH /businesses/{business_id}/system_users/{system_user_id} | Update a system user information. |
| GET /businesses/{business_id}/members | Get business members |
| PATCH /businesses/{business_id}/members | Update member's business role |
| DELETE /businesses/{business_id}/members | Terminate business memberships |
| GET /businesses/{business_id}/partners | Get business partners |
| DELETE /businesses/{business_id}/partners | Terminate business partnerships |
| POST /business_access/business_hierarchy/{business_hierarchy_id}/brand_accounts | Create a Brand Account |
| PATCH /business_access/business_hierarchy/{business_hierarchy_id}/brand_accounts/{brand_account_id} | Update a Brand Account |
| Operation | Description |
|---|---|
| PATCH /businesses/invites | Accept or decline an invite/request |
| POST /businesses/{business_id}/invites/assets/access | Update invite/request with an asset permission |
| POST /businesses/{business_id}/requests/assets/access | Create a request to access an existing partner's assets. |
| GET /businesses/{business_id}/invites | Get invites/requests |
| POST /businesses/{business_id}/invites | Create invites or requests |
| DELETE /businesses/{business_id}/invites | Cancel invites/requests |
| Operation | Description |
|---|---|
| POST /notifications | Receive notifications from external partners. |
| Operation | Description |
|---|---|
| GET /trends/topics/featured | Get featured topics |
| GET /trends/product_categories/details | Get product category details |
| GET /trends/product_categories/trending | Get a list of growing Shopping Product Categories |
View audience insights.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/audience_insights | Get audience insights |
| GET /ad_accounts/{ad_account_id}/insights/audiences | Get audience insights scope and type |
View, share, or revoke shared audiences.
Audience Sharing endpoints are not available to all apps,
if you are interested in using them, reach out to us on our help center page.
Learn more.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/audiences/shared/accounts | List accounts with access to an audience owned by an ad account |
| PATCH /ad_accounts/{ad_account_id}/audiences/ad_accounts/shared | Update audience sharing between ad accounts |
| PATCH /ad_accounts/{ad_account_id}/audiences/businesses/shared | Update audience sharing from an ad account to businesses |
| GET /businesses/{business_id}/audiences | List received audiences for a business |
| GET /businesses/{business_id}/audiences/shared/accounts | List accounts with access to an audience owned by a business |
| PATCH /businesses/{business_id}/audiences/ad_accounts/shared | Update audience sharing from a business to ad accounts |
| PATCH /businesses/{business_id}/audiences/businesses/shared | Update audience sharing between businesses |
View, create, or update audiences.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/audiences | List audiences |
| POST /ad_accounts/{ad_account_id}/audiences | Create audience |
| GET /ad_accounts/{ad_account_id}/audiences/{audience_id} | Get audience |
| PATCH /ad_accounts/{ad_account_id}/audiences/{audience_id} | Update audience |
View, create, or update information related to billing.
View, create, update, or delete information about boards.
| Operation | Description |
|---|---|
| POST /boards | Create board |
| GET /boards | List boards |
| GET /boards/{board_id} | Get board |
| DELETE /boards/{board_id} | Delete board |
| PATCH /boards/{board_id} | Update board |
| GET /boards/{board_id}/pins | List Pins on board |
| GET /boards/{board_id}/sections | List board sections |
| POST /boards/{board_id}/sections | Create board section |
| PATCH /boards/{board_id}/sections/{section_id} | Update board section |
| DELETE /boards/{board_id}/sections/{section_id} | Delete board section |
| GET /boards/{board_id}/sections/{section_id}/pins | List Pins on board section |
Get a list of the ad_accounts that the "operation user_account" has access to. - This includes ad_accounts they own and ad_accounts that are owned by others who have granted them Business Access.
| include_shared_accounts | Include shared ad accounts |
query | object | |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/Pinterest.Lib.BookmarkParams.bookmark |
| page_size | Maximum number of items to include in a single page. See documentation on Pagination for more information. |
query | object | #/components/parameters/Pinterest.Lib.BookmarkParams.page_size |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Create a new ad account. Different ad accounts can support different currencies, payment methods, etc. An ad account is needed to create campaigns, ad groups, and ads; other accounts (your employees or partners) can be assigned business access and appropriate roles to access an ad account.
You can set up up to 50 ad accounts per user. (The user must have a business account to create an ad account.) For more, see Create an advertiser account.
The request has succeeded.
Resource create operation completed successfully.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | ads:write |
Get an ad account
| ad_account_id | path | object | #/components/parameters/AdAccountKey |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
List ad groups based on provided campaign IDs or ad group IDs.(campaign_ids or ad_group_ids).
Note: Provide only campaign_id or ad_group_id. Do not provide both.| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| campaign_ids | List of Campaign Ids to use to filter the results. |
query | object | #/components/parameters/query_campaign_ids |
| ad_group_ids | List of Ad group Ids to use to filter the results. |
query | object | #/components/parameters/query_ad_group_ids |
| entity_statuses | Entity status |
query | object | #/components/parameters/query_entity_statuses |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| order | The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items. |
query | object | #/components/parameters/query_order |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| translate_interests_to_names | Return interests as text names (if value is true) rather than topic IDs. |
query | object | #/components/parameters/query_translate_interests_to_names |
Success
Invalid ad account group parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Update multiple existing ad groups.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
Create multiple new ad groups. All ads in a given ad group will have the same budget, bid, run dates, targeting, and placement (search, browse, other). For more information, click here. Notes:
bid_in_micro_currency and budget_in_micro_currency should be expressed in microcurrency amounts based on the currency field set in the advertiser's profile.Microcurrency is used to track very small transactions, based on the currency set in the advertiser’s profile.
A microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser’s profile.
Equivalency equations, using dollars as an example currency:
To convert between currency and microcurrency, using dollars as an example currency:
start_time and end_time at the ad group level for campaigns with Campaign Budget Optimization (CBO) objectives: TRAFFIC, AWARENESS, WEB_CONVERSIONS, and CATALOG_SALES. All other organizations can set these scheduling parameters for non-CBO campaigns only.| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
Get analytics for the specified ad groups in the specified ad_account_id, filtered by the specified options.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| start_date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today. |
query | object | #/components/parameters/query_start_date |
| end_date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. |
query | object | #/components/parameters/query_end_date |
| ad_group_ids | List of Ad group Ids to use to filter the results. |
query | object | #/components/parameters/query_ad_group_ids_required |
| columns | Columns to retrieve, encoded as a comma-separated string. NOTE: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. |
query | object | #/components/parameters/query_granularity |
| click_window_days | Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_click_window_days |
| engagement_window_days | Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_engagement_window_days |
| view_window_days | Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_view_window_days |
| conversion_report_time | The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event. |
query | object | #/components/parameters/query_conversion_attribution_conversion_report_time |
| aggregate_report_rows | Determines if report rows should be aggregated across all requested entities. This feature is currently in BETA and is not available to all users. |
query | object | #/components/parameters/aggregate_report_rows |
| reporting_timezone | Specify the timezone to be applied for the reporting. This feature is currently in BETA and is not available to all users. |
query | object | #/components/parameters/query_reporting_timezone |
Success
Invalid ad account group analytics parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get potential audience size for an ad group with given targeting criteria. Potential audience size estimates the number of people you may be able to reach per month with your campaign. It is based on historical advertising data and the targeting criteria you select. It does not guarantee results or take into account factors such as bid, budget, schedule, seasonality or product experiments.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Invalid ad group audience sizing parameters.
No access to requested audience list or product group.
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get targeting analytics for one or more ad groups. For the requested ad group(s) and metrics, the response will include the requested metric information (e.g. SPEND_IN_DOLLAR) for the requested target type (e.g. "age_bucket") for applicable values (e.g. "45-49").
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| ad_group_ids | List of Ad group Ids to use to filter the results. |
query | object | #/components/parameters/query_ad_group_ids_required |
| start_date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today. |
query | object | #/components/parameters/query_start_date |
| end_date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. |
query | object | #/components/parameters/query_end_date |
| targeting_types | Targeting type breakdowns for the report. The reporting per targeting type |
query | object | #/components/parameters/query_ad_group_targeting_types |
| columns | Columns to retrieve, encoded as a comma-separated string. NOTE: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. |
query | object | #/components/parameters/query_granularity |
| click_window_days | Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_click_window_days |
| engagement_window_days | Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_engagement_window_days |
| view_window_days | Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_view_window_days |
| conversion_report_time | The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event. |
query | object | #/components/parameters/query_conversion_attribution_conversion_report_time |
| attribution_types | List of types of attribution for the conversion report |
query | object | #/components/parameters/query_attribution_types |
| reporting_timezone | Specify the timezone to be applied for the reporting. This feature is currently in BETA and is not available to all users. |
query | object | #/components/parameters/query_reporting_timezone |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get a specific ad group given the ad group ID.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| ad_group_id | Unique identifier of an ad group. |
path | object | #/components/parameters/path_ad_group_id |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Create an ad preview given an ad account ID and either an existing organic pin ID or the URL for an image to be used to create the Pin and the ad.
If you are creating a preview from an existing Pin, that Pin must be promotable: that is, it must have a clickthrough link and meet other requirements. (See Ads Overview.) You can view the returned preview URL on a webpage or iframe for 7 days, after which the URL expires. Collection ads are not currently supported ad preview.Creating ad preview from catalog product group is currently in BETA and is not available to all users.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Successful ad preview creation.
Invalid Pin parameters response
Unexpected error
| pinterest_oauth2 | ads:write |
List ads that meet the filters provided:
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| campaign_ids | List of Campaign Ids to use to filter the results. |
query | object | #/components/parameters/query_campaign_ids |
| ad_group_ids | List of Ad group Ids to use to filter the results. |
query | object | #/components/parameters/query_ad_group_ids |
| ad_ids | List of Ad Ids to use to filter the results. |
query | object | #/components/parameters/query_ad_ids |
| entity_statuses | Entity status |
query | object | #/components/parameters/query_entity_statuses |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| order | The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items. |
query | object | #/components/parameters/query_order |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
Success
Invalid ad account ads parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Update multiple existing ads
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
Create multiple new ads. Request must contain ad_group_id, creative_type, and the source Pin pin_id.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
Get analytics for the specified ads in the specified ad_account_id, filtered by the specified options.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| start_date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today. |
query | object | #/components/parameters/query_start_date |
| end_date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. |
query | object | #/components/parameters/query_end_date |
| ad_ids | List of Ad Ids to use to filter the results. |
query | object | #/components/parameters/query_ad_ids |
| columns | Columns to retrieve, encoded as a comma-separated string. NOTE: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. |
query | object | #/components/parameters/query_granularity |
| click_window_days | Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_click_window_days |
| engagement_window_days | Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_engagement_window_days |
| view_window_days | Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_view_window_days |
| conversion_report_time | The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event. |
query | object | #/components/parameters/query_conversion_attribution_conversion_report_time |
| pin_ids | List of Pin IDs. |
query | object | |
| campaign_ids | List of Campaign Ids to use to filter the results. |
query | object | #/components/parameters/query_campaign_ids |
| reporting_timezone | Specify the timezone to be applied for the reporting. This feature is currently in BETA and is not available to all users. |
query | object | #/components/parameters/query_reporting_timezone |
Success
Invalid ad account ads analytics parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get targeting analytics for one or more ads. For the requested ad(s) and metrics, the response will include the requested metric information (e.g. SPEND_IN_DOLLAR) for the requested target type (e.g. "age_bucket") for applicable values (e.g. "45-49").
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| ad_ids | List of Ad Ids to use to filter the results. |
query | object | #/components/parameters/query_ad_ids_required |
| start_date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today. |
query | object | #/components/parameters/query_start_date |
| end_date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. |
query | object | #/components/parameters/query_end_date |
| targeting_types | Targeting type breakdowns for the report. The reporting per targeting type |
query | object | #/components/parameters/query_ad_targeting_types |
| columns | Columns to retrieve, encoded as a comma-separated string. NOTE: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. |
query | object | #/components/parameters/query_granularity |
| click_window_days | Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_click_window_days |
| engagement_window_days | Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_engagement_window_days |
| view_window_days | Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_view_window_days |
| conversion_report_time | The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event. |
query | object | #/components/parameters/query_conversion_attribution_conversion_report_time |
| attribution_types | List of types of attribution for the conversion report |
query | object | #/components/parameters/query_attribution_types |
| reporting_timezone | Specify the timezone to be applied for the reporting. This feature is currently in BETA and is not available to all users. |
query | object | #/components/parameters/query_reporting_timezone |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get a specific ad given the ad ID. If your pin is rejected, rejected_reasons will contain additional information from the Ad Review process. For more information about our policies and rejection reasons see the Pinterest advertising standards.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| ad_id | Unique identifier of an ad. |
path | object | #/components/parameters/path_ad_id |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Returns the list of discounts applied to the account.
This endpoint might not be available to all apps. Learn more.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
Success
Unexpected error.
| pinterest_oauth2 | ads:read , billing:read |
Redeem ads credit on behalf of the ad account id and apply it towards billing.
This endpoint might not be available to all apps. Learn more.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Successfully redeemed ad credits.
Error thrown when unable to redeem offer code.
Unexpected error
| pinterest_oauth2 | ads:write , billing:write |
Get advertiser defined events for the given ad account.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get analytics for the specified ad_account_id, filtered by the specified options.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| start_date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today. |
query | object | #/components/parameters/query_start_date |
| end_date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. |
query | object | #/components/parameters/query_end_date |
| columns | Columns to retrieve, encoded as a comma-separated string. NOTE: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. |
query | object | #/components/parameters/query_granularity |
| click_window_days | Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_click_window_days |
| engagement_window_days | Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_engagement_window_days |
| view_window_days | Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_view_window_days |
| conversion_report_time | The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event. |
query | object | #/components/parameters/query_conversion_attribution_conversion_report_time |
| reporting_timezone | Specify the timezone to be applied for the reporting. This feature is currently in BETA and is not available to all users. |
query | object | #/components/parameters/query_reporting_timezone |
Success
Invalid ad account analytics parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get Audience Insights for an ad account. The response will return insights for 3 types of audiences: the ad account's engaged audience on Pinterest, the ad account's total audience on Pinterest and Pinterest's total audience.
Learn more about Audience Insights.| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| audience_insight_type | Type of audience insights. |
query | object | #/components/parameters/query_audience_insight_type |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get list of audiences for the ad account.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| order | The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. For received audiences, it is sorted by sharing event time. Note that higher-value IDs are associated with more-recently added items. |
query | object | |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| ownership_type | Filter audiences by ownership type. |
query | object |
Success
Invalid ad account audience parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Create an audience you can use in targeting for specific ad groups. Targeting combines customer information with
the ways users interact with Pinterest to help you reach specific groups of users; you can include or exclude
specific audience_ids when you create an ad group.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
Get a specific audience given the audience ID.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| audience_id | Unique identifier of an audience |
path | object | #/components/parameters/path_audience_id |
Success
Audience not found.
Unexpected error.
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Update (edit or remove) an existing targeting audience.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| audience_id | Unique identifier of an audience |
path | object | #/components/parameters/path_audience_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
List bid floors for your campaign configuration. Bid floors are given in microcurrency values based on the currency in the bid floor specification.
Microcurrency is used to track very small transactions, based on the currency set in the advertiser’s profile.
A microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser’s profile.
Equivalency equations, using dollars as an example currency:
To convert between currency and microcurrency, using dollars as an example currency:
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get download url for a billing invoice.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| billing_invoice_id | Unique identifier of a billing invoice. |
path | object | #/components/parameters/path_billing_invoice_id |
Successfully fetched Billing invoice information for a given ad account
Invalid request parameter.
Unexpected error
| pinterest_oauth2 | ads:read , billing:read |
Get billing invoices in the advertiser account.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| sort | Field of which to sort billing invoices |
query | object | #/components/parameters/query_sort_billing_invoice |
| order | The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items. |
query | object | #/components/parameters/query_order |
| status | Status of billing invoices to filter by |
query | object | #/components/parameters/query_billing_invoice_status |
| document_type | Document type of billing invoices to filter by |
query | object | #/components/parameters/query_billing_document_type |
| start_due_date | Starting point for due dates when searching for invoices. Format: YYYY-MM-DD |
query | object | #/components/parameters/query_billing_start_due_date |
| end_due_date | Ending point for due dates when searching for invoices. Format: YYYY-MM-DD |
query | object | #/components/parameters/query_billing_end_due_date |
Success
Invalid request parameter.
Unexpected error
| pinterest_oauth2 | ads:read , billing:read |
Get billing profiles in the advertiser account.
This endpoint might not be available to all apps. Learn more.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| is_active | Return active billing profiles, if false return all billing profiles. |
query | object | |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
Success
Unexpected error.
| pinterest_oauth2 | ads:read , billing:read |
Create an asynchronous report that may include information on campaigns, ad groups, product groups, ads, keywords, and/or labels; can filter by campaigns. Though the entities may be active, archived, or paused, only active entities will return data.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
Either create or update any combination of campaigns, ad groups, product groups, ads, keywords, or labels.
Note that this request will be processed asynchronously; the response will include a request_id
that can be used to obtain the status of the request.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
Get the status of a bulk request by request_id, along with a download URL that will allow you to download the
new or updated entity data (campaigns, ad groups, product groups, ads, or keywords).
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| bulk_request_id | Unique identifier of a bulk upsert request. |
path | object | #/components/parameters/path_bulk_request_id |
| include_details | if set to True then attach the errors/details to all the requests |
query | object | #/components/parameters/include_details |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get a list of the campaigns in the specified ad_account_id, filtered by the specified options.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| campaign_ids | List of Campaign Ids to use to filter the results. |
query | object | #/components/parameters/query_campaign_ids |
| entity_statuses | Entity status |
query | object | #/components/parameters/query_entity_statuses |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| order | The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items. |
query | object | #/components/parameters/query_order |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
Success
Invalid ad account campaign parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Update multiple ad campaigns based on campaign_ids.
Note:
-The values for `lifetime_spend_cap` and `daily_spend_cap` are microcurrency amounts based on the currency field set in the advertiser's profile. (e.g. USD)
Microcurrency is used to track very small transactions, based on the currency set in the advertiser's profile.
A microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser's profile.
Equivalency equations, using dollars as an example currency:
To convert between currency and microcurrency, using dollars as an example currency:
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
response
Unexpected error
| pinterest_oauth2 | ads:write |
Create multiple new campaigns. Every campaign has its own campaign_id and houses one or more ad groups, which contain one or more ads. For more, see Set up your campaign.
Note:Microcurrency is used to track very small transactions, based on the currency set in the advertiser’s profile.
A microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser’s profile.
Equivalency equations, using dollars as an example currency:
To convert between currency and microcurrency, using dollars as an example currency:
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
response
Unexpected error
| pinterest_oauth2 | ads:write |
Get analytics for the specified campaigns in the specified ad_account_id, filtered by the specified options.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| start_date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today. |
query | object | #/components/parameters/query_start_date |
| end_date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. |
query | object | #/components/parameters/query_end_date |
| campaign_ids | List of Campaign Ids to use to filter the results. |
query | object | #/components/parameters/query_campaign_ids_required |
| columns | Columns to retrieve, encoded as a comma-separated string. NOTE: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. |
query | object | #/components/parameters/query_granularity |
| click_window_days | Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_click_window_days |
| engagement_window_days | Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_engagement_window_days |
| view_window_days | Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_view_window_days |
| conversion_report_time | The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event. |
query | object | #/components/parameters/query_conversion_attribution_conversion_report_time |
| aggregate_report_rows | Determines if report rows should be aggregated across all requested entities. This feature is currently in BETA and is not available to all users. |
query | object | #/components/parameters/aggregate_report_rows |
| reporting_timezone | Specify the timezone to be applied for the reporting. This feature is currently in BETA and is not available to all users. |
query | object | #/components/parameters/query_reporting_timezone |
Success
Invalid ad account campaign analytics parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get targeting analytics for one or more campaigns. For the requested account and metrics, the response will include the requested metric information (e.g. SPEND_IN_DOLLAR) for the requested target type (e.g. "age_bucket") for applicable values (e.g. "45-49").
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| campaign_ids | List of Campaign Ids to use to filter the results. |
query | object | #/components/parameters/query_campaign_ids_required |
| start_date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today. |
query | object | #/components/parameters/query_start_date |
| end_date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. |
query | object | #/components/parameters/query_end_date |
| targeting_types | Targeting type breakdowns for the report. The reporting per targeting type |
query | object | #/components/parameters/query_campaign_targeting_types |
| columns | Columns to retrieve, encoded as a comma-separated string. NOTE: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. |
query | object | #/components/parameters/query_granularity |
| click_window_days | Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_click_window_days |
| engagement_window_days | Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_engagement_window_days |
| view_window_days | Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_view_window_days |
| conversion_report_time | The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event. |
query | object | #/components/parameters/query_conversion_attribution_conversion_report_time |
| attribution_types | List of types of attribution for the conversion report |
query | object | #/components/parameters/query_attribution_types |
| reporting_timezone | Specify the timezone to be applied for the reporting. This feature is currently in BETA and is not available to all users. |
query | object | #/components/parameters/query_reporting_timezone |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get a specific campaign given the campaign ID.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| campaign_id | Campaign ID, must be associated with the ad account ID provided in the path. |
path | object | #/components/parameters/path_campaign_id |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get the Event Quality Score (EQS) of your conversion signals.
Event Quality Score indicates how effective the customer information and event insights (metadata) passed with your web, app and offline conversion events may be at matching to a Pinterest user.
| lookback_period | Lookback window (number of days). |
query | object | #/components/parameters/EventQualityScoreListParams.lookback_period |
| source_platform | Source platform of event. |
query | object | #/components/parameters/EventQualityScoreListParams.source_platform |
| ingestion_source | Ingestion source of event. |
query | object | #/components/parameters/EventQualityScoreListParams.ingestion_source |
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get a set of customer lists including id and name based on the filters provided.
(Customer lists are a type of audience.) For more information, see Audience targeting or the Audiences section of the ads management guide.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| order | The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items. |
query | object | #/components/parameters/query_order |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
Create a customer list from your records(hashed or plain-text email addresses, or hashed MAIDs or IDFAs).
A customer list is one of the four types of Pinterest audiences: for more information, see Audience targeting or the Audiences section of the ads management guide.
Please review our requirements for what type of information is allowed when uploading a customer list.
When you create a customer list, the system scans the list for existing Pinterest accounts; the list must include at least 100 Pinterest accounts. Your original list will be deleted when the matching process is complete. The filtered list – containing only the Pinterest accounts that were included in your starting list – is what will be used to create the audience.
To use your customer list after creating it, convert it into a customer list audience by passing the `CUSTOMER_LIST` audience type at the create audience endpoint.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
Gets a specific customer list given the customer list ID.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| customer_list_id | Unique identifier of a customer list |
path | object | #/components/parameters/path_customer_list_id |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Append or remove records to/from an existing customer list. (A customer list is one of the four types of Pinterest audiences.)
When you add records to an existing customer list, the system scans the additions for existing Pinterest accounts; those are the records that will be added to your “CUSTOMER_LIST” audience. Your original list of records to add will be deleted when the matching process is complete.
For more information, see Audience targeting or the Audiences section of the ads management guide.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| customer_list_id | Unique identifier of a customer list |
path | object | #/components/parameters/path_customer_list_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
Create a customer list upload request for multipart S3 upload.
Note: Each part must be at least 5mb; however the last part can be any size greater than 0. Clients with smaller files can request a single part count. This minimal part size restriction is defined by the AWS S3 API.
Please review the update customer list endpoint documentation for additional information.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| customer_list_id | Unique identifier of a customer list |
path | object | #/components/parameters/path_customer_list_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
Get the metadata for a given upload by its ID.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| customer_list_id | Unique identifier of a customer list |
path | object | #/components/parameters/path_customer_list_id |
| customer_list_upload_id | Unique identifier of a customer list upload |
path | object | #/components/parameters/path_customer_list_upload_id |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
Begin processing a customer list upload.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| customer_list_id | Unique identifier of a customer list |
path | object | #/components/parameters/path_customer_list_id |
| customer_list_upload_id | Unique identifier of a customer list upload |
path | object | #/components/parameters/path_customer_list_upload_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
The Pinterest API offers advertisers a way to send Pinterest their conversion information (including web conversions, in-app conversions, or even offline conversions) based on their ad_account_id. The request body should be a JSON object.
access_token be generated through Ads Manager. Review the Conversions Guide for more details. (Note that the authorization header required is Authorization: Bearer <access_token>).user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Audience, Campaign. (Note that the token can be used across multiple ad accounts under an user ID.)| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| test | Include query param ?test=true to mark the request as a test request. The events will not be recorded but the API will still return the same response messages. Use this mode to verify your requests are working and your events are constructed correctly. Warning: If you use this query parameter, be certain that it is off (set to false or deleted) before sending a legitimate (non-testing) request. |
query | object |
Success
The request was invalid.
Not authorized to send conversion events
Unauthorized access.
Not all events were successfully processed.
This request exceeded a rate limit. This can happen if the client exceeds one of the published rate limits within a short time window.
The endpoint has been ramped down and is currently not accepting any traffic.
Unexpected errors
| pinterest_oauth2 | ads:write |
| conversion_token |
Get the scope and type of available audiences, which along with a date, is an audience that has recently had an interaction (referred to here as a type) on pins. Interacted pins can belong to at least the most common partner or Pinterest scopes. This means that user interactions made on advertiser or partner pins will have the partner scope. You can also have user interactions performed in general on Pinterest with the Pinterest scope. In that case, you can then use the returned type and scope values together on requests to other endpoints to retrieve insight metrics for a desired audience.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get a list of keywords based on the filters provided. If no filter is provided, it will default to the ad_account_id filter, which means it will only return keywords that specifically have parent_id set to the ad_account_id. Note: Keywords can have ad_account_ids, campaign_ids, and ad_group_ids set as their parent_ids. Keywords created through Ads Manager will have their parent_id set to an ad_group_id, not ad_account_id.
For more information, see Keyword targeting.
Notes:
For more information on match types, see match type enums.
Returns:
A successful call returns an object containing an array of new keyword objects and an empty "errors" object array.
An unsuccessful call returns an empty keywords array, and, instead, inserts the entire object with nulled/negated properties into the "errors" object array:
{ "keywords": [], "errors": [ { "data": { "archived": null, "match_type": "EXACT", "parent_type": null, "value": "foobar", "parent_id": null, "type": "keyword", "id": null }, "error_messages": [ "Advertisers and Campaigns only accept excluded targeting attributes." ] } } | ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| campaign_id | Campaign Id to use to filter the results. |
query | object | #/components/parameters/query_campaign_id |
| ad_group_id | Ad group Id. |
query | object | #/components/parameters/query_ad_group_id |
| ad_group_ids | List of Ad group Ids to retrieve keywords from. This feature is currently in BETA and is not available to all users. |
query | object | #/components/parameters/keywords_query_ad_group_ids |
| match_types | Keyword match type |
query | object | #/components/parameters/query_match_types |
| page_size | Maximum number of items to include in a single page of the response. Default maximum of 250. See documentation on Pagination for more information. |
query | object | |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Update one or more keywords' bid and archived fields.
Archiving a keyword effectively deletes it - keywords no longer receive metrics and no longer visible within the parent entity's keywords list.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
Create keywords for following entity types(advertiser, campaign, ad group or ad).
For more information, see Keyword targeting.
Notes:
For more information on match types, see match type enums.
Returns:
A successful call returns an object containing an array of new keyword objects and an empty "errors" object array.
An unsuccessful call returns an empty keywords array, and, instead, inserts the entire object with nulled/negated properties into the "errors" object array:
{ "keywords": [], "errors": [ { "data": { "archived": null, "match_type": "EXACT", "parent_type": null, "value": "foobar", "parent_id": null, "type": "keyword", "id": null }, "error_messages": [ "Advertisers and Campaigns only accept excluded targeting attributes." ] } } Rate limit: WRITE.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
See keyword metrics for a specified country, aggregated across all of Pinterest. (Definitions are available from the "Get delivery metrics definitions" API endpoint).
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| country_code | Two letter country code (ISO 3166-1 alpha-2) |
query | object | #/components/parameters/query_country_code |
| keywords | Comma-separated keywords |
query | object | #/components/parameters/query_keywords |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Closed beta This endpoint is not available to all users.
See a list of labels for assets that your account owns, and filter the list by different criteria.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| campaign_ids | List of Campaign Ids to use to filter the results. |
query | object | #/components/parameters/query_campaign_ids |
| label_ids | List of Label Ids to use to filter the results. |
query | object | #/components/parameters/query_label_ids |
| entity_statuses | Label entity status |
query | object | #/components/parameters/query_label_entity_statuses |
| label_types | Label type. |
query | object | #/components/parameters/query_label_types |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
Success
Invalid ad account ads parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
Closed beta This endpoint is not available to all users.
Change the properties of one or more labels.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
Closed beta This endpoint is not available to all users.
Apply one or more labels to a campaign. Currently, you can apply brand and custom labels. Future releases will provide more options.
Note: You can only apply one brand label to a campaign. You can apply 30 custom labels to a campaign.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.
List lead forms associated with an ad account ID.
For more, see Lead ads.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| order | The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items. |
query | object | #/components/parameters/query_order |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
Success
Invalid ad account lead forms parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.
Update lead forms. Lead ads help you reach people who are actively looking for, and interested in, your goods and services. The lead form can be associated with an ad to allow people to fill out the form.
For more, see Lead ads.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Invalid ad account lead forms parameters.
Unexpected error
| pinterest_oauth2 | ads:write |
This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.
Create lead forms. Lead forms are used in lead ads and allow you to control what text appears on the lead form’s description, questions and confirmation sections.
For more, see Lead ads.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Invalid ad account lead forms parameters.
Unexpected error
| pinterest_oauth2 | ads:write |
This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.
Gets a lead form given it's ID. It must also be associated with the provided ad account ID.
For more, see Lead ads.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| lead_form_id | Unique identifier of a lead form. |
path | object | #/components/parameters/path_lead_form_id |
Success
Invalid ad account lead forms parameters.
The lead form ID for the given ad account ID does not exist.
Unexpected error
| pinterest_oauth2 | ads:read |
Create lead form test data based on the list of answers provided as part of the body.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| lead_form_id | Unique identifier of a lead form. |
path | object | #/components/parameters/path_lead_form_id |
Success
Invalid parameters.
Lead not found.
Unexpected error
| pinterest_oauth2 | ads:write |
Get the advertiser's list of lead ads subscriptions. Only requests for the OWNER or ADMIN of the ad_account will be allowed.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/Pinterest.Lib.BookmarkParams.bookmark |
| page_size | Maximum number of items to include in a single page. See documentation on Pagination for more information. |
query | object | #/components/parameters/Pinterest.Lib.BookmarkParams.page_size |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | ads:read |
Create a lead ads webhook subscription. Subscriptions allow Pinterest to deliver lead data from Ads Manager directly to the subscriber. Subscriptions can exist for a specific lead form or at ad account level.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
An unexpected error response.
| pinterest_oauth2 | ads:write |
Delete an existing lead ads webhook subscription by ID.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| subscription_id | Unique identifier of a subscription. |
path | object | #/components/parameters/SubscriptionIdPathParam |
Resource deleted successfully.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | ads:write |
Get an existing lead ads webhook subscription by ID.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| subscription_id | Unique identifier of a subscription. |
path | object | #/components/parameters/SubscriptionIdPathParam |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.
Create an export of leads collected from a lead ad. This returns a lead_export_id token that you can use to download the export when it is ready.
Note: Lead ad data will be available up to 30 days after the lead has been submitted.
For more, see Lead ads.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Invalid ad account parameter.
Unexpected error
| pinterest_oauth2 | ads:write |
This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.
Get the export of leads collected from a lead ad. This returns a URL to a list of lead export given a lead_export_id token returned from the create a lead export call. You can use the URL to download the report.
Note: Lead ad data will be available up to 30 days after the lead has been submitted.
For more, see Lead ads.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| leads_export_id | lead_export_id token returned from the create a lead export endpoint |
path | object |
Success
Invalid ad account parameter.
Invalid leads export id parameter.
Unexpected error
| pinterest_oauth2 | ads:read |
Get an mmm report for an ad account. This returns a URL to an mmm metrics report given a token returned from the create mmm report endpoint.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| token | Token returned from the post request creation call |
query | object | #/components/parameters/query_token_required |
Success
Invalid ad account ads analytics parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
This creates an asynchronous mmm report based on the given request. It returns a token that you can use to download the report when it is ready. NOTE: An additional limit of 5 queries per minute per advertiser applies to this endpoint while it's in beta release.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Invalid ad account ads analytics mmm parameters
Unexpected error
| pinterest_oauth2 | ads:read |
This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.
Advertisers or their measurement partners can send attributed MSOT conversion events to Pinterest based on their ad_account_id. The request body should be a JSON object.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
The request was invalid
Not authorized to send MSOT conversion events
Unauthorized access
This request exceeded a rate limit. This can happen if the client exceeds one of the published rate limits within a short time window.
Unexpected errors
| pinterest_oauth2 | msot:write |
List existing order lines associated with an ad account.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| order | The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items. |
query | object | #/components/parameters/query_order |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
Get a specific existing order line associated with an ad account.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| order_line_id | Unique identifier of an order line. |
path | object | #/components/parameters/path_order_line_id |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
Get analytics for the pins given a campaign and pins in the specified ad_account_id, filtered by the specified options.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| campaign_id | Campaign Id to use to filter the results. |
query | object | #/components/parameters/query_campaign_id_required |
| pin_ids | List of Pin IDs. |
query | object | #/components/parameters/query_required_pin_ids |
| start_date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today. |
query | object | #/components/parameters/query_start_date |
| end_date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. |
query | object | #/components/parameters/query_end_date |
| columns | Columns to retrieve, encoded as a comma-separated string. NOTE: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. |
query | object | #/components/parameters/query_granularity |
| click_window_days | Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_click_window_days |
| engagement_window_days | Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_engagement_window_days |
| view_window_days | Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_view_window_days |
| conversion_report_time | The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event. |
query | object | #/components/parameters/query_conversion_attribution_conversion_report_time |
Success
Invalid ad account pins analytics parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
List existing product group promotions associated with an ad account.
Include either ad_group_id or product_group_promotion_ids in your request.
Note: ad_group_ids and product_group_promotion_ids are mutually exclusive parameters. Only provide one. If multiple options are provided, product_group_promotion_ids takes precedence over ad_group_ids. If none are provided, the endpoint returns an error.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| product_group_promotion_ids | List of Product group promotion Ids. |
query | object | #/components/parameters/query_product_group_promotion_ids |
| entity_statuses | Entity status |
query | object | #/components/parameters/query_entity_statuses |
| ad_group_id | Ad group Id. |
query | object | #/components/parameters/query_ad_group_id |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| order | The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items. |
query | object | #/components/parameters/query_order |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
Update multiple existing Product Group Promotions (by product_group_id)
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
Add one or more product groups from your catalog to an existing ad group. (Product groups added to an ad group are a 'product group promotion.')
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:write |
Get a product group promotion by id
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| product_group_promotion_id | Unique identifier of a product group promotion |
path | object | #/components/parameters/path_product_group_promotion_id |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
Get analytics for the specified product groups in the specified ad_account_id, filtered by the specified options.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| start_date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today. |
query | object | #/components/parameters/query_start_date |
| end_date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. |
query | object | #/components/parameters/query_end_date |
| product_group_ids | List of Product group Ids to use to filter the results. |
query | object | #/components/parameters/query_product_group_ids_required |
| columns | Columns to retrieve, encoded as a comma-separated string. NOTE: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. |
query | object | #/components/parameters/query_granularity |
| click_window_days | Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_click_window_days |
| engagement_window_days | Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_engagement_window_days |
| view_window_days | Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_view_window_days |
| conversion_report_time | The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event. |
query | object | #/components/parameters/query_conversion_attribution_conversion_report_time |
| reporting_timezone | Specify the timezone to be applied for the reporting. This feature is currently in BETA and is not available to all users. |
query | object | #/components/parameters/query_reporting_timezone |
Success
Invalid ad account ads analytics parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Gets all promotions associated with an ad account ID that can be applied to an ad group. Can be either internally-saved promotions or external promotions imported from a commerce integration.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| order | The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items. |
query | object | #/components/parameters/query_order |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
Success
Invalid ad account promotions parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
Update multiple promotions.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Invalid create promotions request parameters.
Unexpected error
| pinterest_oauth2 | ads:write |
Create multiple new promotions.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Invalid create promotions request parameters.
Unexpected error
| pinterest_oauth2 | ads:write |
Delete a promotion within Pinterest.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| promotion_id | Unique identifier of a promotion |
path | object | #/components/parameters/path_promotion_id |
Promotion deleted successfully
Unexpected error
| pinterest_oauth2 | ads:write |
Get a promotion by its Pinterest-specific id. It must be associated with the provided ad account id.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| promotion_id | Unique identifier of a promotion |
path | object | #/components/parameters/path_promotion_id |
Success
The promotion ID for the given ad account ID was not found.
Unexpected error
| pinterest_oauth2 | ads:read |
This returns a URL to an analytics report given a token returned from the post request report creation call. You can use the URL to download the report. The link is valid for five minutes and the report is valid for one hour.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| token | Token returned from the post request creation call |
query | object | #/components/parameters/query_token_required |
Success
Invalid ad account ads analytics parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
This returns a token that you can use to download the report when it is ready. Note that this endpoint requires the parameters to be passed as JSON-formatted in the request body. This endpoint does not support URL query parameters.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Invalid ad account ads analytics parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
Restricted Get a brand, category, SKU report for an ad account. This call returns the URL for the report that matches the token returned in the request to the Create brand, category, SKU report endpoint.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| token | Token returned from the post request creation call |
query | object | #/components/parameters/query_token_required |
Success
Invalid ad account ads analytics parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
Restricted This creates an asynchronous brand, category, SKU report based on the given request. This request returns a token that you can use to download the report when it is ready.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Invalid ad account ads analytics brand, category, SKU parameters
Unexpected error
| pinterest_oauth2 | ads:read |
Delete an ad account and all the ads data associated with that account. A string message is returned indicating the status of the delete operation.
Note: This endpoint is only allowed in the Pinterest API Sandbox (https://api-sandbox.pinterest.com/v5). Go to /docs/developer-tools/sandbox/ for more information.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
OK
Invalid ad account id.
Unexpected error
| pinterest_oauth2 | ads:write |
Get Salesforce account details including bill-to information to be used in insertion orders process for ad_account_id.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Invalid request parameter.
Unexpected error
| pinterest_oauth2 | ads:read |
Edit insertion order through SSIO for ad_account_id.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Invalid request.
Unexpected error
| pinterest_oauth2 | ads:write |
Create insertion order through SSIO for ad_account_id.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Invalid request.
Unexpected error
| pinterest_oauth2 | ads:write |
Get insertion order status for account id ad_account_id.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
Success
Invalid request parameter.
Unexpected error
| pinterest_oauth2 | ads:read |
Get insertion order status for pin order id pin_order_id.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| pin_order_id | The pin order id associated with the ssio insertion order |
path | object | #/components/parameters/path_pin_order_id |
Success
Invalid request parameter.
Unexpected error
| pinterest_oauth2 | ads:read |
Get Salesforce order lines for account id ad_account_id.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| pin_order_id | The pin order id associated with the ssio insertino order |
query | object | #/components/parameters/query_pin_order_id |
Success
Invalid request parameter.
Unexpected error
| pinterest_oauth2 | ads:read |
Get targeting analytics for an ad account. For the requested account and metrics, the response will include the requested metric information (e.g. SPEND_IN_DOLLAR) for the requested target type (e.g. "age_bucket") for applicable values (e.g. "45-49").
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| start_date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today. |
query | object | #/components/parameters/query_start_date |
| end_date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. |
query | object | #/components/parameters/query_end_date |
| targeting_types | Targeting type breakdowns for the report. The reporting per targeting type |
query | object | #/components/parameters/query_targeting_types |
| columns | Columns to retrieve, encoded as a comma-separated string. NOTE: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. |
query | object | #/components/parameters/query_granularity |
| click_window_days | Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_click_window_days |
| engagement_window_days | Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_engagement_window_days |
| view_window_days | Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to |
query | object | #/components/parameters/query_conversion_attribution_view_window_days |
| conversion_report_time | The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event. |
query | object | #/components/parameters/query_conversion_attribution_conversion_report_time |
| attribution_types | List of types of attribution for the conversion report |
query | object | #/components/parameters/query_attribution_types |
| reporting_timezone | Specify the timezone to be applied for the reporting. This feature is currently in BETA and is not available to all users. |
query | object | #/components/parameters/query_reporting_timezone |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get a list of the targeting templates in the specified ad_account_id
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| order | The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items. |
query | object | #/components/parameters/query_order |
| include_sizing | Include audience sizing in result or not |
query | object | |
| search_query | Search keyword for targeting templates |
query | object | |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
Success
Invalid ad account id.
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Update the targeting template given advertiser ID and targeting template ID
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Invalid ad account id.
Unexpected error
| pinterest_oauth2 | ads:write |
Targeting templates allow advertisers to save a set of targeting details including audience lists, keywords & interest, demographics, and placements to use more than once during the campaign creation process.
Templates can be used to build out basic targeting criteria that you plan to use across campaigns and to reuse performance targeting from prior campaigns for new campaigns.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
Success
Invalid ad account id.
Unexpected error
| pinterest_oauth2 | ads:write |
Gets all Templates associated with an ad account ID.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| order | The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items. |
query | object | #/components/parameters/query_order |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
Success
Invalid ad account template parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
This takes a template ID and an optional custom timeframe and constructs an asynchronous report based on the template. It returns a token that you can use to download the report when it is ready.
| ad_account_id | path | object | #/components/parameters/TemplateBasedReportKey.id | |
| template_id | Unique identifier of a template. |
path | object | #/components/parameters/TemplateBasedReportKey.template_id |
| start_date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 2.5 years back from today. |
query | object | #/components/parameters/query_start_date_async |
| end_date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 2.5 years past start date. |
query | object | #/components/parameters/query_end_date_async |
| granularity | TOTAL - metrics are aggregated over the specified date range. DAY - metrics are broken down daily. HOUR - metrics are broken down hourly. WEEKLY - metrics are broken down weekly. MONTHLY - metrics are broken down monthly |
query | object | #/components/parameters/query_granularity_async |
The request has succeeded.
Resource create operation completed successfully.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | ads:read |
Get the text of the terms of service and see whether the advertiser has accepted the terms of service.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/path_ad_account_id |
| include_html | Return HTML in TOS text. |
query | object | #/components/parameters/query_include_html |
| tos_type | Request type. |
query | object | #/components/parameters/query_tos_type |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
Get the bid options for a batch of retail catalog items.
The catalog must be owned by the "operation user_account". See detailed documentation here. By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin.
This endpoint is not available to all users.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Response containing the bid option values for the requested retail catalog items. Items that don't exist or do not have bid options set won't be present in the response.
Invalid request parameters.
Not authenticated to get item bid options
Not authorized to get item bid options
Internal error
Unexpected error
| pinterest_oauth2 | ads:read , catalogs:read |
This endpoint supports multiple operations on a set of one or more bid options (bid price and bid adjustments for targeting categories) for retail catalog items. These advanced auction settings are applied in campaigns using objective_type CATALOG_SALES and ad groups using bid_strategy_type MAX_BID.
The catalog must be owned by the "operation user_account". See detailed documentation here. By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin.
This endpoint is not available to all users.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Response containing the results of the item bid options operations
Response containing the results of the item bid options operations (where some/all operation results have errors)
Invalid request parameters.
Not authenticated to post item bid options
Not authorized to post item bid options
Internal error
Unexpected error
| pinterest_oauth2 | ads:write , catalogs:read |
Get a list of the boards owned by the "operation user_account" + group boards where this account is a collaborator Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". Optional: Specify a privacy type (public, protected, or secret) to indicate which boards to return.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
| privacy | The privacy level of the board |
query | object | #/components/parameters/query_board_privacy |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/Pinterest.Lib.BookmarkParams.bookmark |
| page_size | Maximum number of items to include in a single page. See documentation on Pagination for more information. |
query | object | #/components/parameters/Pinterest.Lib.BookmarkParams.page_size |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | boards:read |
| client_credentials | boards:read |
Create a board owned by the "operation user_account". Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
The request has succeeded.
Resource create operation completed successfully.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | boards:read , boards:write |
| client_credentials | boards:read , boards:write |
Delete a board owned by the "operation user_account".
| board_id | path | object | #/components/parameters/BoardKey | |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Resource deleted successfully.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | boards:read , boards:write |
Get a board owned by the operation user_account - or a group board that has been shared with this account.
| board_id | path | object | #/components/parameters/BoardKey | |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | boards:read |
| client_credentials | boards:read |
Update a board owned by the "operating user_account".
| board_id | path | object | #/components/parameters/BoardWithUpdatePrivacyKey | |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | boards:read , boards:write |
| client_credentials | boards:read , boards:write |
Get a list of the Pins on a board owned by the "operation user_account" - or on a group board that has been shared with this account.
| board_id | Unique identifier of a board. |
path | object | #/components/parameters/path_board_id |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| creative_types | Pin creative types filter. Note: SHOP_THE_PIN has been deprecated. Please use COLLECTION instead. |
query | object | #/components/parameters/query_creative_types |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
| pin_metrics | Specify whether to return 90d and lifetime Pin metrics. Total comments
and total reactions are only available with lifetime Pin metrics. If Pin was
created before |
query | object | #/components/parameters/query_pin_metrics |
response
Board not found.
Unexpected error
| pinterest_oauth2 | boards:read , pins:read |
| client_credentials | boards:read , pins:read |
Get a list of all board sections from a board owned by the "operation user_account" - or a group board that has been shared with this account. Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
| board_id | Unique identifier of a board. |
path | object | #/components/parameters/path_board_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
response
Unexpected error
| pinterest_oauth2 | boards:read |
| client_credentials | boards:read |
Create a board section on a board owned by the "operation user_account" - or on a group board that has been shared with this account. Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
| board_id | Unique identifier of a board. |
path | object | #/components/parameters/path_board_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
response
Invalid board section parameters.
Not authorized to create board sections.
Could not get exclusive access to the board to create a new section.
Could not create a new board section.
Unexpected error
| pinterest_oauth2 | boards:read , boards:write |
Delete a board section on a board owned by the "operation user_account" - or on a group board that has been shared with this account. Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
| board_id | Unique identifier of a board. |
path | object | #/components/parameters/path_board_id |
| section_id | Unique identifier of a board section. |
path | object | #/components/parameters/path_board_section_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Board section deleted successfully
Not authorized to delete board section.
Board section not found.
Board section conflict.
Unexpected error
| pinterest_oauth2 | boards:read , boards:write |
Update a board section on a board owned by the "operation user_account" - or on a group board that has been shared with this account. Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
| board_id | Unique identifier of a board. |
path | object | #/components/parameters/path_board_id |
| section_id | Unique identifier of a board section. |
path | object | #/components/parameters/path_board_section_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
response
Invalid board section parameters.
Not authorized to update board section.
Board section conflict.
Unexpected error
| pinterest_oauth2 | boards:read , boards:write |
Get a list of the Pins on a board section of a board owned by the "operation user_account" - or on a group board that has been shared with this account. Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
| board_id | Unique identifier of a board. |
path | object | #/components/parameters/path_board_id |
| section_id | Unique identifier of a board section. |
path | object | #/components/parameters/path_board_section_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
response
Not authorized to access Pins on board section.
Board or section not found.
Board section conflict.
Unexpected error
| pinterest_oauth2 | boards:read , pins:read |
| client_credentials | boards:read , pins:read |
Create a Brand Account that will be a child business of a business hierarchy. Request must contain name, username, and country.
| business_hierarchy_id | business hierarchy node id |
path | object | #/components/parameters/path_business_hierarchy_id |
Success
Invalid parameters.
Unexpected error
| pinterest_oauth2 | biz_access:read , biz_access:write |
Update an existing Brand Account
| business_hierarchy_id | business hierarchy node id |
path | object | #/components/parameters/path_business_hierarchy_id |
| brand_account_id | Unique identifier of a brand account. |
path | object |
Success
Invalid parameters.
Not authenticated to update Brand Account
Not authorized to update Brand Account
Brand account not found
This account is not a brand account.
This request exceeded a rate limit. This can happen if the client exceeds one of the published rate limits within a short time window.
Unexpected error
| pinterest_oauth2 | biz_access:read , biz_access:write |
Get all of the viewing user's business employers.
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
Success
Unexpected error
| pinterest_oauth2 | biz_access:read |
Accept or decline invites or requests.
Success
Unexpected error
| pinterest_oauth2 | biz_access:read , biz_access:write |
Delete a batch of asset groups.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
Success
Invalid parameters.
Unexpected error
| pinterest_oauth2 | biz_access:read , biz_access:write |
Update a batch of asset groups with the specified parameters.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
Success
Invalid parameters.
Unexpected error
| pinterest_oauth2 | biz_access:read , biz_access:write |
Create a new asset group with the specified parameters.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
Success
Invalid parameters.
Unexpected error
| pinterest_oauth2 | biz_access:read , biz_access:write |
Get all the assets the requesting business has access to. This includes assets the business owns and assets the business has access to through partnerships.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
| permissions | A list of asset permissions used to filter the assets. Only assets where the requesting business has at least one of the specified permissions will be returned. |
query | object | |
| child_asset_id | A child asset unique identifier. Used to fetch asset groups that contain the asset id as a child. |
query | object | |
| asset_group_id | An asset group unique identifier. Used to fetch assets contained within the specified asset group. |
query | object | |
| asset_type | A resource type to filter the assets by. Only assets of the specified type will be returned. |
query | object | #/components/parameters/query_resource_type |
| start_index | An index to start fetching the results from. Only the results starting from this index will be returned. |
query | object | #/components/parameters/query_business_access_start_index |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
Success
Unexpected error
| pinterest_oauth2 | biz_access:read |
Get all the members the requesting business has granted access to on the given asset.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
| asset_id | Unique identifier of a business asset. |
path | object | #/components/parameters/path_asset_id |
| fetch_system_users | Fetches system users if True. Fetches regular user employees if False. |
query | object | #/components/parameters/fetch_system_users |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| start_index | An index to start fetching the results from. Only the results starting from this index will be returned. |
query | object | #/components/parameters/query_business_access_start_index |
Sucess
Unexpected error
| pinterest_oauth2 | biz_access:read |
Get all the partners the requesting business has granted access to on the given asset. Note: If the asset has been shared with you, an empty array will be returned. This is because an asset shared with you cannot be shared with a different partner.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
| asset_id | Unique identifier of a business asset. |
path | object | #/components/parameters/path_asset_id |
| start_index | An index to start fetching the results from. Only the results starting from this index will be returned. |
query | object | #/components/parameters/query_business_access_start_index |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
Sucess
Unexpected error
| pinterest_oauth2 | biz_access:read |
Get a list of received audiences for the given business.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| order | The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items. |
query | object | #/components/parameters/query_order |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
Success
Invalid parameters.
Unexpected error
| pinterest_oauth2 | biz_access:read |
Cancel membership/partnership invites and/or requests.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_non_system_business_user |
Success
Unexpected error
| pinterest_oauth2 | biz_access:write |
Get the membership/partnership invites and/or requests for the authorized user.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_non_system_business_user |
| is_member | A boolean field to indicate whether the invite is to create a partnership or a membership. |
query | object | #/components/parameters/query_is_member |
| invite_status | A list of invite statuses to filter invites by. Only invites whose status is in the provided statuses will be returned. |
query | object | #/components/parameters/query_invite_status |
| invite_type | Invite type to filter invites by. Only invites of the specified type will be returned. |
query | object | #/components/parameters/query_invite_type |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
Success
Unexpected error
| pinterest_oauth2 | biz_access:read |
Create batch invites or requests. Can create batch invites or requests as described below.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_non_system_business_user |
Success
Unexpected error
| pinterest_oauth2 | biz_access:write |
Assign asset permissions information to an existing invite/request. Can be used to:
To learn more about permission levels, visit https://help.pinterest.com/en/business/article/business-manager-overview.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
Success
Unexpected error
| pinterest_oauth2 | biz_access:read , biz_access:write |
Terminate memberships between the specified members and your business.
| business_id | Business id |
path | object | #/components/parameters/path_business_id |
Success
Unexpected error
| pinterest_oauth2 | biz_access:read , biz_access:write |
Get all members of the specified business. The return response will include the member's business_role and assets they have access to if assets_summary=TRUE
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
| fetch_system_users | Fetches system users if True. Fetches regular user employees if False. |
query | object | #/components/parameters/fetch_system_users |
| assets_summary | Include assets summary in the response if this is true. The assets summary returns a dictionary representing a summary of the assets for the business user ID, with information like the ad accounts and profiles the user has permissions for and what those permissions are |
query | object | #/components/parameters/query_assets_summary |
| business_roles | A list of business roles to filter the members by. Only members whose roles are in the specified roles will be returned. |
query | object | |
| member_ids | A list of business members ids separated by comma. |
query | object | |
| start_index | An index to start fetching the results from. Only the results starting from this index will be returned. |
query | object | #/components/parameters/query_business_access_start_index |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
Success
Unexpected error
| pinterest_oauth2 | biz_access:read |
Update a member's business role within the business.
| business_id | Business id |
path | object | #/components/parameters/path_business_id |
response
Unexpected error
| pinterest_oauth2 | biz_access:write |
Terminate multiple members' access to an asset.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
response
Unexpected error
| pinterest_oauth2 | biz_access:write |
Grant multiple members access to assets and/or update multiple member's exisiting permissions to an asset. Note: Not all listed permissions are applicable to each asset type. For example, PROFILE_PUBLISHER would not be applicable to an asset of type AD_ACCOUNT. The permission level PROFILE_PUBLISHER is only available to an asset of the type PROFILE.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
response
Unexpected error
| pinterest_oauth2 | biz_access:write |
Get assets on which you assigned asset permissions to the given member. Can be used to:
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
| member_id | The member id to fetch assets for. |
path | object | #/components/parameters/path_business_member_user |
| asset_type | A resource type to filter the assets by. Only assets of the specified type will be returned. |
query | object | #/components/parameters/query_resource_type |
| start_index | An index to start fetching the results from. Only the results starting from this index will be returned. |
query | object | #/components/parameters/query_business_access_start_index |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
Success
Unexpected error
| pinterest_oauth2 | biz_access:read |
Terminate partnerships between the specified partners and your business. Note: You may only batch terminate partners of the same partner type.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
Success
A supplied partner id doesn't exist
Unexpected error
| pinterest_oauth2 | biz_access:write |
Get all partners of the specified business.
If the assets_summary=TRUE and:
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
| assets_summary | Include assets summary in the response if this is true. The assets summary returns a dictionary representing a summary of the assets for the business user ID, with information like the ad accounts and profiles the user has permissions for and what those permissions are |
query | object | #/components/parameters/query_assets_summary |
| partner_type | Specifies whether to fetch internal or external (shared) partners.
If partner_type=INTERNAL, the asset being queried is for accesses the partner has to your business assets. |
query | object | #/components/parameters/query_business_partner_type |
| partner_ids | A list of business partner ids separated by commas used to filter the results. Only partners with the specified ids will be returned. |
query | object | |
| start_index | An index to start fetching the results from. Only the results starting from this index will be returned. |
query | object | #/components/parameters/query_business_access_start_index |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
Success
Unexpected error
| pinterest_oauth2 | biz_access:read |
Terminate multiple partners' access to an asset. If
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
Success
Unexpected error
| pinterest_oauth2 | biz_access:write |
Grant multiple partners access to assets and/or update multiple partner's exisiting permissions to an asset. If your partner already had permissions on the asset, they will be overriden with the new permissions you assign to them. To learn more about permission levels, visit https://help.pinterest.com/en/business/article/business-manager-overview
Note: Not all listed permissions are applicable to each asset type. For example, PROFILE_PUBLISHER would not be applicable to an asset of type AD_ACCOUNT. The permission level PROFILE_PUBLISHER is only available to an asset of the type PROFILE.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
Success
Unexpected error
| pinterest_oauth2 | biz_access:write |
Can be used to get the business assets your partner has granted you access to or the business assets you have granted your partner access to. If you specify:
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
| partner_id | The partner id to be bound to the Business |
path | object | #/components/parameters/path_business_partner_user |
| partner_type | Specifies whether to fetch internal or external (shared) partners.
If partner_type=INTERNAL, the asset being queried is for accesses the partner has to your business assets. |
query | object | |
| asset_type | A resource type to filter the assets by. Only assets of the specified type will be returned. |
query | object | #/components/parameters/query_resource_type |
| start_index | An index to start fetching the results from. Only the results starting from this index will be returned. |
query | object | #/components/parameters/query_business_access_start_index |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
Success
Unexpected error
| pinterest_oauth2 | biz_access:read |
Create a request to access an existing partner's assets with the specified permissions. The request will be sent to the partner for approval. The assets that can be requested are ad accounts and profiles.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
Success
Unexpected error
| pinterest_oauth2 | biz_access:read , biz_access:write |
Update a system user information such as name.
| business_id | Unique identifier of the requesting business. |
path | object | #/components/parameters/path_business_user |
| system_user_id | Unique identifier of a system user. |
path | object |
System user updated successfully.
Invalid parameters.
Unexpected error
| pinterest_oauth2 | biz_access:read , biz_access:write |
Fetch catalogs owned by the "operation user_account".
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Invalid parameters.
Unauthorized access.
Unexpected error.
| pinterest_oauth2 | catalogs:read |
Create a new catalog owned by the "operation user_account".
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Note: Access to the Product and Creative Assets catalog type is restricted to a specific group of users. If you require access, please reach out to your partner manager.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Invalid parameters.
Unauthorized access.
Unexpected error.
| pinterest_oauth2 | catalogs:write |
Get the available filter attributes and values associated with a given feed or catalog owned by the "operation user_account".
country, language, and feed_id are only used in retail catalogs.Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
| catalog_id | Filter entities for a given catalog_id. |
query | object | |
| feed_id | Filter entities for a given feed_id. If not given, all feeds are considered. |
query | object | #/components/parameters/query_catalogs_feed_id |
| country | Country for the Catalogs Items |
query | object | |
| language | Language for the Catalogs Items |
query | object | |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Invalid parameters.
Unauthorized access.
Forbidden. Account not authorized to access available filter values.
Data feed not found.
Can't access this feature without an existing catalog.
Unexpected error.
| pinterest_oauth2 | catalogs:read |
Fetch feeds owned by the "operation user_account".
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
For Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| catalog_id | Filter entities for a given catalog_id. If not given, all catalogs are considered. |
query | object | #/components/parameters/query_catalogs_catalog_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Invalid parameters.
Unauthorized access.
Unexpected error.
| pinterest_oauth2 | catalogs:read |
| client_credentials | catalogs:read |
Create a new feed owned by the "operation user_account".
Please, be aware that "default_country" and "default_locale" are not required in the spec for forward compatibility but for now the API will not accept requests without those fields.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
For Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.
Note: Access to the Creative Assets catalog type is restricted to a specific group of users. If you require access, please reach out to your partner manager.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Invalid feed parameters.
Unauthorized access.
Business account required.
User website required.
Unique feed name is required.
Not implemented (absent "default_country" or "default_locale").
Unexpected error
| pinterest_oauth2 | catalogs:read , catalogs:write |
| client_credentials | catalogs:read , catalogs:write |
Delete a feed owned by the "operating user_account".
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
For Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.
| feed_id | Unique identifier of a feed |
path | object | #/components/parameters/path_catalogs_feed_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Feed deleted successfully.
Invalid feed parameters.
Forbidden. Account not approved for feed mutations yet.
Data feed not found.
Conflict. Can't delete a feed with active promotions.
Unexpected error
| pinterest_oauth2 | catalogs:read , catalogs:write |
| client_credentials | catalogs:read , catalogs:write |
Get a single feed owned by the "operation user_account".
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
For Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.
| feed_id | Unique identifier of a feed |
path | object | #/components/parameters/path_catalogs_feed_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Invalid feed parameters.
Unauthorized access.
Data feed not found.
Unexpected error.
| pinterest_oauth2 | catalogs:read |
| client_credentials | catalogs:read |
Update a feed owned by the "operation user_account".
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
For Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.
Note: Access to the Creative Assets catalog type is restricted to a specific group of users. If you require access, please reach out to your partner manager.
| feed_id | Unique identifier of a feed |
path | object | #/components/parameters/path_catalogs_feed_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Invalid feed parameters.
Forbidden. Account not approved for feed mutations yet.
Data feed not found.
Unexpected error
| pinterest_oauth2 | catalogs:read , catalogs:write |
| client_credentials | catalogs:read , catalogs:write |
Ingest items for a given feed owned by the "operation user_account".
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Note: This endpoint is restricted to a specific group of users. If you require access, please reach out to your partner manager.
| feed_id | Unique identifier of a feed |
path | object | #/components/parameters/path_catalogs_feed_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
The ingestion process was successfully started.
Invalid feed parameters.
Forbidden. Account not approved for feed mutations yet.
Data feed not found.
Unexpected error
| pinterest_oauth2 | catalogs:write |
Fetch a feed processing results owned by the "operation user_account". Please note that for now the bookmark parameter is not functional and only the first page will be available until it is implemented in some release in the near future.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
| feed_id | Unique identifier of a feed |
path | object | #/components/parameters/path_catalogs_feed_id |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Invalid parameters.
Unauthorized access.
Feed not found.
Unexpected error.
| pinterest_oauth2 | catalogs:read |
Get the items of the catalog owned by the "operation user_account". See detailed documentation here.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Note: Access to the Creative Assets catalog type is restricted to a specific group of users. If you require access, please reach out to your partner manager.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Response containing the requested catalogs items
Invalid request
Not authorized to access catalogs items
Not authorized to access catalogs items
Unexpected error
| pinterest_oauth2 | catalogs:read |
This endpoint supports multiple operations on a set of one or more catalog items owned by the "operation user_account". See detailed documentation here.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Note:
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Response containing the requested catalogs items batch
Invalid request parameters.
Not authenticated to post catalogs items
Not authorized to post catalogs items
Unexpected error
| pinterest_oauth2 | catalogs:read , catalogs:write |
| client_credentials | catalogs:read , catalogs:write |
Get a single catalogs items batch owned by the "operating user_account". See detailed documentation here.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
| batch_id | Id of a catalogs items batch to fetch |
path | object | #/components/parameters/path_catalogs_items_batch_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Response containing the requested catalogs items batch
Not authenticated to access catalogs items batch
Not authorized to access catalogs items batch
Catalogs items batch not found
Method Not Allowed.
Unexpected error
| pinterest_oauth2 | catalogs:read |
| client_credentials | catalogs:read |
List item validation issues for a given feed processing result owned by the "operation user_account". Up to 20 random samples of affected items are returned for each error and warning code. Please note that for now query parameters 'item_numbers' and 'item_validation_issue' cannot be used simultaneously until it is implemented in some release in the future.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Note: To get a list of all affected items instead of sampled issues, please refer to Build catalogs report and Get catalogs report endpoints. Moreover, they support multiple types of catalogs.
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| processing_result_id | Unique identifier of a feed processing result. It can be acquired from the "id" field of the "items" array within the response of the List processing results for a given feed. |
path | object | #/components/parameters/path_catalogs_processing_result_id |
| item_numbers | Item number based on order of appearance in the Catalogs Feed. For example, '0' refers to first item found in a feed that was downloaded from a 'location' specified during feed creation. |
query | object | #/components/parameters/query_catalogs_item_numbers |
| item_validation_issue | Filter item validation issues that have a given type of item validation issue. |
query | object | #/components/parameters/query_catalogs_item_validation_issue |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Unauthorized access.
Processing Result not found.
Not implemented.
Unexpected error.
| pinterest_oauth2 | catalogs:read |
Get a list of product groups for a given Catalogs Feed Id owned by the "operation user_account".
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
| id | Comma-separated list of product group ids |
query | object | #/components/parameters/query_catalogs_product_group_ids |
| feed_id | Filter entities for a given feed_id. If not given, all feeds are considered. |
query | object | #/components/parameters/query_catalogs_feed_id |
| catalog_id | Filter entities for a given catalog_id. If not given, all catalogs are considered. |
query | object | #/components/parameters/query_catalogs_catalog_id |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Invalid feed parameters.
Unauthorized access.
Forbidden. Account not approved for catalog product group mutations yet.
Data feed not found.
Conflict. Can't create this catalogs product group with this value.
Unexpected error.
| pinterest_oauth2 | catalogs:read |
Create product group to use in Catalogs owned by the "operation user_account".
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
"Catalog-based product groups" can include items from all data sources (feeds and API) and are available to both non-retail catalogs with any data sources and retail catalogs with API-created items. If your catalog only contains retail items created via feeds, you should use the "retail feed-based" option.
Learn more
Note: Access to the Creative Assets catalog type is restricted to a specific group of users. If you require access, please reach out to your partner manager.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Invalid body.
Unauthorized access.
Forbidden. Account not approved for catalog product group mutations yet.
Conflict. Can't create this catalogs product group with this value.
Unexpected error.
| pinterest_oauth2 | catalogs:write |
Delete product groups owned by the "operation user_account".
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
| id | Comma-separated list of product group ids |
query | object | #/components/parameters/query_catalogs_product_group_ids_required |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Catalogs Product Groups deleted successfully.
Unauthorized access.
Forbidden. Account not approved for catalog product group mutations yet.
Catalogs product group not found.
Conflict. Can't delete this catalogs product group.
Unexpected error.
| pinterest_oauth2 | catalogs:write |
Create product group to use in Catalogs owned by the "operation user_account".
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Note: Access to the Creative Assets catalog type is restricted to a specific group of users. If you require access, please reach out to your partner manager.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Invalid body.
Unauthorized access.
Forbidden. Account not approved for catalog product group mutations yet.
Conflict. Can't create this catalogs product group with this value.
Unexpected error.
| pinterest_oauth2 | catalogs:write |
Delete a product group owned by the "operation user_account" from being in use in Catalogs.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
| product_group_id | Unique identifier of a product group |
path | object | #/components/parameters/path_catalogs_product_group_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Catalogs Product Group deleted successfully.
Invalid catalogs product group id parameters.
Unauthorized access.
Forbidden. Account not approved for catalog product group mutations yet.
Catalogs product group not found.
Conflict. Can't delete this catalogs product group.
Unexpected error.
| pinterest_oauth2 | catalogs:write |
Get a singe product group for a given Catalogs Product Group Id owned by the "operation user_account".
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
| product_group_id | Unique identifier of a product group |
path | object | #/components/parameters/path_catalogs_product_group_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Invalid catalogs product group id parameters.
Unauthorized access.
Forbidden. Account not approved for catalog product group mutations yet.
Catalogs product group not found.
Conflict. Can't get a catalogs product group without an existing catalog.
Unexpected error.
| pinterest_oauth2 | catalogs:read |
Update product group owned by the "operation user_account" to use in Catalogs.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
"Catalog-based product groups" can include items from all data sources (feeds and API) and are available to both non-retail catalogs with any data sources and retail catalogs with API-created items. If your catalog only contains retail items created via feeds, you should use the "retail feed-based" option.
Learn more
Note: Access to the Creative Assets catalog type is restricted to a specific group of users. If you require access, please reach out to your partner manager.
| product_group_id | Unique identifier of a product group |
path | object | #/components/parameters/path_catalogs_product_group_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Invalid parameters.
Unauthorized access.
Forbidden. Account not approved for catalog product group mutations yet.
Catalogs product group not found.
Conflict. Can't update this catalogs product group to this value.
Unexpected error.
| pinterest_oauth2 | catalogs:write |
Get a product counts for a given Catalogs Product Group owned by the "operation user_account".
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
| product_group_id | Unique identifier of a product group |
path | object | #/components/parameters/path_catalogs_product_group_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Product Group Not Found.
Can't access this feature without an existing catalog.
Unexpected error.
| pinterest_oauth2 | catalogs:read |
Get a list of product pins for a given Catalogs Product Group Id owned by the "operation user_account".
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| product_group_id | Unique identifier of a product group |
path | object | #/components/parameters/path_catalogs_product_group_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
| pin_metrics | Specify whether to return 90d and lifetime Pin metrics. Total comments
and total reactions are only available with lifetime Pin metrics. If Pin was
created before |
query | object | #/components/parameters/query_pin_metrics |
Success
Invalid parameters.
Unauthorized access.
Catalogs product group not found.
Unexpected error.
| pinterest_oauth2 | boards:read , catalogs:read , pins:read |
List products Pins owned by the "operation user_account" that meet the criteria specified in the Catalogs Product Group Filter given in the request.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Note: This endpoint only supports RETAIL catalog at the moment.
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
| pin_metrics | Specify whether to return 90d and lifetime Pin metrics. Total comments
and total reactions are only available with lifetime Pin metrics. If Pin was
created before |
query | object | #/components/parameters/query_pin_metrics |
Success
Unauthorized access.
Conflict. Can't get products.
Unexpected error.
| pinterest_oauth2 | boards:read , catalogs:read , pins:read |
This returns a URL to a report given a token returned from Build catalogs report. You can use the URL to download the report.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
| token | Token returned from async build report call |
query | object | #/components/parameters/query_catalogs_report_token |
Response that contains a link to download the report
The token you provided is not valid or has expired.
Can't access this feature without an existing catalog.
Unexpected error
| pinterest_oauth2 | catalogs:read |
Async request to create a report of the catalog owned by the "operation user_account". This endpoint generates a report upon receiving the first approved request of the day. Any following requests with identical parameters will yield the same report even if data has changed.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
Note: Access to the All Items report type is restricted to a specific group of users. If you require access, please reach out to your partner manager.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Response containing the report token
Entity (e.g., catalog, feed or processing_result) not found
Can't access this feature without an existing catalog.
Unexpected error
| pinterest_oauth2 | catalogs:read |
List aggregated numbers of issues for a catalog owned by the "operation user_account".
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| parameters | Contains the parameters for report identification. |
query | object | #/components/parameters/query_catalogs_report_stats_parameters |
Response containing the diagnostics aggregated counters
Not authorized to access catalogs
Unexpected error
| pinterest_oauth2 | catalogs:read |
Get integration metadata list. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager.
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
Success
Unexpected error.
| pinterest_oauth2 | ads:read |
Create commerce integration metadata to link an external business ID with a Pinterest merchant & ad account. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager.
Success
Integration not found.
Can't access this integration metadata.
Unexpected error.
| pinterest_oauth2 | ads:write |
Delete commerce integration metadata for the given external business ID. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager.
| external_business_id | External business ID for the integration. |
path | object | #/components/parameters/path_external_business_id |
Commerce Integration deleted successfully
Unexpected error.
| pinterest_oauth2 | ads:write |
Get commerce integration metadata associated with the given external business ID. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager.
| external_business_id | External business ID for the integration. |
path | object | #/components/parameters/path_external_business_id |
Success
Integration not found.
Can't access this integration metadata.
Unexpected error.
| pinterest_oauth2 | ads:read |
Update commerce integration metadata for the given external business ID. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager.
| external_business_id | External business ID for the integration. |
path | object | #/components/parameters/path_external_business_id |
Success
Integration not found.
Can't access this integration metadata.
Unexpected error.
| pinterest_oauth2 | ads:write |
This endpoint receives batched logs from integration applications on partner platforms. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager.
Success.
Bad request.
Unexpected error
| pinterest_oauth2 | ads:write |
Get integration metadata by ID. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager.
| id | Integration ID. |
path | object |
Success
Integration not found.
Unexpected error.
| pinterest_oauth2 | ads:read |
List media uploads filtered by given parameters.
Learn more about video Pin creation.
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/Pinterest.Lib.BookmarkParams.bookmark |
| page_size | Maximum number of items to include in a single page. See documentation on Pagination for more information. |
query | object | #/components/parameters/Pinterest.Lib.BookmarkParams.page_size |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | pins:read |
Register your intent to upload media.
The response includes all of the information needed to upload the media to Pinterest.
To upload the media, make an HTTP POST request (using curl, for example) to upload_url using the Content-Type header value. Send the media file's contents as the request's file parameter and also include all of the parameters from upload_parameters.
Learn more about video Pin creation.
The request has succeeded.
Resource create operation completed successfully.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | pins:read , pins:write |
Get details for a registered media upload, including its current status.
Learn more about video Pin creation.
| media_id | Unique identifier for this media upload. Used to track status and for attaching during Pin creation. |
path | object | #/components/parameters/MediaKey |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | pins:read |
Used by third-party partners to send notifications to Pinterest. These notifications could be specific for your use-case or generic notification that are accepted by Pinterests' systems. This API is gated and you need to request access to this feature.
Successfully received notification
Invalid request parameter.
Unexpected error
| pinterest_oauth2 | user_accounts:read |
| client_credentials | user_accounts:read |
Generate a new and long-lived OAuth access token dedicated for sending conversions using a valid access token.
response
Unexpected error
| pinterest_oauth2 | ads:write |
Generate a new OAuth access token using an authorization code; or refresh an existing one using a continuous refresh token.
Follow the complete steps for requesting and refreshing tokens.
Note: If your app was created before September 25, 2025, make sure to set the continuous_refresh parameter to true to use the continuous refresh token (60-day expiration, refreshable indefinitely). Pinterest no longer supports the legacy refresh token (365-day expiration, hard limit).
Disregard this note if your app was activated on or after September 25, 2025. You are automatically using the continuous refresh token.
Use Token Debugger to validate and inspect your access token.
response
Unexpected error
| basic |
Revokes an access or refresh token. Only tokens issued for system users are currently supported. Revoked tokens become immediately invalid and unusable.
Successful token revocation. No content is returned.
Client authentication error.
Client is not allowed to revoke token.
Unexpected error
| basic |
Get a list of the Pins owned by the "operation user_account".
- By default, the "operation user_account" is the token user_account.
- All Pins owned by the "operation user_account" are included, regardless of who owns the board they are on.
Optional: Business Access: Specify an `ad_account_id` to use the owner of that ad_account as the "operation user_account".
Disclaimer: There are known performance issues when filtering by field `creative_type` and including protected pins.
If your request is timing out in this scenario, we encourage you to use [GET List Pins on Board](/docs/api/v5/#operation/boards/list_pins).| pin_filter | The filter to apply to the pins |
query | object | #/components/parameters/query_pin_filter |
| pin_metrics | Specify whether to return 90d and lifetime Pin metrics. Total comments
and total reactions are only available with lifetime Pin metrics. If Pin was
created before |
query | object | #/components/parameters/query_pin_metrics |
| include_protected_pins | Whether to include protected pins in the results |
query | object | #/components/parameters/query_include_protected_pins |
| pin_type | The type of pins to return, currently only enabled for private pins |
query | object | #/components/parameters/query_pin_type |
| creative_types | Pin creative types filter. Note: SHOP_THE_PIN has been deprecated. Please use COLLECTION instead. |
query | object | #/components/parameters/query_creative_types |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/Pinterest.Lib.BookmarkParams.bookmark |
| page_size | Maximum number of items to include in a single page. See documentation on Pagination for more information. |
query | object | #/components/parameters/Pinterest.Lib.BookmarkParams.page_size |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | boards:read , pins:read |
| client_credentials | boards:read , pins:read |
Create a Pin on a board or board section owned by the "operation user_account".
Note: If the current "operation user_account" (defined by the access token) has access to another user's Ad Accounts via Pinterest Business Access, you can modify your request to make use of the current operation_user_account's permissions to those Ad Accounts by including the ad_account_id in the path parameters for the request (e.g. .../?ad_account_id=12345&...).
Learn more about video Pin creation.
Learn more about image Pin creation.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
The request has succeeded.
Resource create operation completed successfully.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | boards:read , boards:write , pins:read , pins:write |
| client_credentials | boards:read , boards:write , pins:read , pins:write |
This endpoint is currently in beta and not available to all apps. Learn more.
Get analytics for multiple pins owned by the "operation user_account" - or on a group board that has been shared with this account.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account:
If Pin was created before 2023-03-20 lifetime metrics will only be available for Video and Idea Pin formats. Lifetime metrics are available for all Pin formats since then.
| pin_ids | List of Pin IDs. |
query | object | #/components/parameters/query_required_pin_ids |
| start_date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today. |
query | object | #/components/parameters/query_start_date |
| end_date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. |
query | object | #/components/parameters/query_end_date |
| app_types | Apps or devices to get data for, default is all. |
query | object | #/components/parameters/query_app_types |
| metric_types | Pin metric types to get data for. |
query | object | |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
response
Invalid pins analytics parameters.
Not authorized to access board or Pin.
Pin not found.
This request exceeded a rate limit. This can happen if the client exceeds one of the published rate limits or if multiple write operations are applied to an object within a short time window.
Unexpected error
| pinterest_oauth2 | boards:read , pins:read |
| client_credentials | boards:read , pins:read |
Delete a Pins owned by the "operation user_account" - or on a group board that has been shared with this account.
By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account:
For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager.
For Pins on secret boards: Owner, Admin.
| pin_id | path | object | #/components/parameters/PinKey | |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Resource deleted successfully.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | boards:read , boards:write , pins:read , pins:write |
| client_credentials | boards:read , boards:write , pins:read , pins:write |
Get a Pin owned by the "operation user_account" - or on a group board that has been shared with this account.
By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account:
For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager.
For Pins on secret boards: Owner, Admin.
| pin_id | path | object | #/components/parameters/PinKey | |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
| pin_metrics | Specify whether to return 90d and lifetime Pin metrics. Total comments
and total reactions are only available with lifetime Pin metrics. If Pin was
created before |
query | object | #/components/parameters/query_pin_metrics |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | boards:read , pins:read |
| client_credentials | boards:read , pins:read |
Update a pin owned by the "operating user_account".
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account:
This endpoint is currently in beta and not available to all apps. Learn more.
| pin_id | path | object | #/components/parameters/PinKey | |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | boards:read , boards:write , pins:read , pins:write |
| client_credentials | boards:read , boards:write , pins:read , pins:write |
Get analytics for a Pin owned by the "operation user_account" - or on a group board that has been shared with this account.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account:
If Pin was created before 2023-03-20 lifetime metrics will only be available for Video and Idea Pin formats. Lifetime metrics are available for all Pin formats since then.
| pin_id | Unique identifier of a Pin. |
path | object | #/components/parameters/path_pin_id |
| start_date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today. |
query | object | #/components/parameters/query_start_date |
| end_date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. |
query | object | #/components/parameters/query_end_date |
| app_types | Apps or devices to get data for, default is all. |
query | object | #/components/parameters/query_app_types |
| metric_types | Pin metric types to get data for. VIDEO_MRC_VIEW are Video views, VIDEO_V50_WATCH_TIME is Total play time. If Pin was created before |
query | object | #/components/parameters/query_pin_analytics_metric_types |
| split_field | How to split the data into groups. Not including this param means data won't be split. |
query | object | #/components/parameters/query_split_field_pins |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
response
Invalid pins analytics parameters.
Not authorized to access board or Pin.
Pin not found.
Unexpected error
| pinterest_oauth2 | boards:read , pins:read |
| client_credentials | boards:read , pins:read |
Save a Pin on a board or board section owned by the "operation user_account".
By default, the "operation user_account" is the token user_account.
Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account:
For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager.
For Pins on secret boards: Owner, Admin.
Any Pin type can be saved: image Pin, video Pin, Idea Pin, product Pin, etc.
Any public Pin can be saved given a pin ID.
| pin_id | Unique identifier of a Pin. |
path | object | #/components/parameters/path_pin_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Successfully saved pin.
Not authorized to access Board or Pin.
Board or Pin not found.
Unexpected error
| pinterest_oauth2 | boards:read , boards:write , pins:read , pins:write |
Get Ad Accounts countries
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Get the definitions for ads and organic metrics available across both synchronous and asynchronous report endpoints.
The display_name attribute will match how the metric is named in our native tools like Ads Manager.
See Organic Analytics and Ads Analytics for more information.
| report_type | Report type. |
query | object | #/components/parameters/query_report_type |
Success
Unexpected error
| pinterest_oauth2 | ads:read , pins:read , user_accounts:read |
| client_credentials | ads:read , pins:read , user_accounts:read |
Get a list of all lead form question type names. Some questions might not be used.
This endpoint is currently in beta and not available to all apps. Learn more.
Success
Unexpected error
| pinterest_oauth2 | ads:read |
Learn whether conversion or non-conversion metrics are finalized and ready to query.
| date | Analytics reports request date (UTC). Format: YYYY-MM-DD |
query | object |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
Get details of a specific interest given interest ID.
Click here for a spreadsheet listing interests and their IDs.
| interest_id | Unique identifier of an interest. |
path | object | #/components/parameters/path_interest_id |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
You can use targeting values in ads placement to define your intended audience.
Targeting metrics are organized around targeting specifications.
For more information on ads targeting, see Audience targeting.
Sample return:
[{"36313": "Australia: Moreton Bay - North", "124735": "Canada: North Battleford", "36109": "Australia: Murray", "36108": "Australia: Mid North Coast", "36101": "Australia: Capital Region", "811": "U.S.: Reno", "36103": "Australia: Central West", "36102": "Australia: Central Coast", "36105": "Australia: Far West and Orana", "36104": "Australia: Coffs Harbour - Grafton", "36107": "Australia: Illawarra", "36106": "Australia: Hunter Valley Exc Newcastle", "554017": "New Zealand: Wanganui", "554016": "New Zealand: Marlborough", "554015": "New Zealand: Gisborne", "554014": "New Zealand: Tararua", "554013": "New Zealand: Invercargill", "GR": "Greece", "554011": "New Zealand: Whangarei", "554010": "New Zealand: Far North", "717": "U.S.: Quincy-Hannibal-Keokuk", "716": "U.S.: Baton Rouge",...}]
| targeting_type | Public targeting type. |
path | object | #/components/parameters/path_targeting_type |
| client_id | Client ID. |
query | object | #/components/parameters/query_client_id |
| oauth_signature | Oauth signature |
query | object | #/components/parameters/query_oauth_signature |
| timestamp | Timestamp |
query | object | #/components/parameters/query_timestamp |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | ads:read |
| client_credentials | ads:read |
Search for boards for the "operation user_account". This includes boards of all board types.
If using Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". See Understanding Business Access for more information.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| query | Search query. Can contain pin description keywords or comma-separated pin IDs. |
query | object | #/components/parameters/query_query |
response
Unexpected error
| pinterest_oauth2 | boards:read , boards:read_secret |
| client_credentials | boards:read , boards:read_secret |
This endpoint is currently in beta and not available to all apps. Learn more.
Get the top 10 Pins by a given search term.
| term | Search term to look up pins. |
query | object | |
| country_code | Two letter country code (ISO 3166-1 alpha-2) |
query | object | #/components/parameters/query_country_code |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| locale | Search locale. |
query | object | |
| limit | Max search result size |
query | object | #/components/parameters/result_limit |
Success
Invalid pins
Unexpected error
| pinterest_oauth2 | boards:read , pins:read |
Search for pins for the "operation user_account".
If using Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". See Understanding Business Access for more information.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
| query | Search query. Can contain pin description keywords or comma-separated pin IDs. |
query | object | #/components/parameters/query_required_search_query |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
Success
User not found
Unexpected error
| pinterest_oauth2 | boards:read , boards:read_secret , pins:read , pins:read_secret |
Get popular search terms that begin with your input term.
Example: 'sport' would return popular terms like 'sports bar' and 'sportswear', but not 'motor sports' since the phrase does not begin with the given term.| term | Input term. |
query | object | #/components/parameters/query_input_term |
| limit | Max suggested terms to return. |
query | object | #/components/parameters/query_term_limit |
Success
Invalid terms suggested parameters.
Unexpected error
| pinterest_oauth2 | ads:read |
Get the top trending search keywords among the Pinterest user audience.
Trending keywords can be used to inform ad targeting, budget strategy, and creative decisions about which products and Pins will resonate with your audience.
Geographic, demographic and interest-based filters are available to narrow down to the top trends among a specific audience. Multiple trend types are supported that can be used to identify newly-popular, evergreen or seasonal keywords.
For an interactive way to explore this data, please visit trends.pinterest.com.
| region | The geographic region of interest. Only top trends within the specified region will be returned.
|
path | object | #/components/parameters/path_trend_region |
| trend_type | The methodology used to rank how trendy a keyword is.
|
path | object | #/components/parameters/path_trend_type |
| interests | If set, filters the results to trends associated with the specified interests.
|
query | object | #/components/parameters/query_interest_list |
| genders | If set, filters the results to trends among users who identify with the specified gender(s). |
query | object | #/components/parameters/query_gender_list |
| ages | If set, filters the results to trends among users in the specified age range(s). |
query | object | #/components/parameters/query_age_bucket_list |
| include_keywords | If set, filters the results to top trends which include at least one of the specified keywords. |
query | object | |
| normalize_against_group | Governs how the resulting time series data will be normalized to a [0-100] scale. |
query | object | #/components/parameters/query_normalize_against_group |
| limit | The maximum number of trending keywords that will be returned. Keywords are returned in trend-ranked order, so a |
query | object | #/components/parameters/query_trending_keyword_limit |
| include_prediction | Closed beta
Including predicted weekly search volume data for the next 90 days.
By default ( |
query | object | |
| include_demographics | Closed beta
Including the age and gender distribution for each keyword.
By default ( |
query | object |
Success
Invalid trending keywords request parameters
Unexpected error
| pinterest_oauth2 | user_accounts:read |
Enables advertisers to retrieve demographic information, related pins, and trend lines for specified product categories
| product_categories | List of product categories |
query | object | #/components/parameters/ProductCategoryIds |
| region | |
query | object | #/components/parameters/query_product_category_detail_region |
| lookback_window | Time period for historical data analysis in days. The lookback window defines how far back in time the API will analyze data to compute trend metrics.
|
query | object | #/components/parameters/query_product_category_lookback_window |
| engagement_type |
|
query | object | #/components/parameters/query_product_category_engagement_type |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | user_accounts:read |
| client_credentials | user_accounts:read |
Get a list of growing Shopping Product Categories in ranked order allowing filtering by engagement type, vertical, age, and gender.
| region | |
query | object | #/components/parameters/query_product_category_detail_region |
| verticals | List of verticals to filter by |
query | object | #/components/parameters/query_vertical_product_category |
| ages | Age to filter by. If not provided, the results will be filtered by all ages. |
query | object | #/components/parameters/query_age_trends_buckets |
| genders | Gender to filter by, If not provided, the results will be filtered by all genders. |
query | object | #/components/parameters/query_gender_buckets |
| engagement_type |
|
query | object | #/components/parameters/query_product_category_engagement_type |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | user_accounts:read |
| client_credentials | user_accounts:read |
Enables advertisers to pull top five trending topics by interest and market, at full parity with the Pinterest Trends UI.
| interest | Interest to filter by |
query | object | #/components/parameters/query_interest |
| region | |
query | object | #/components/parameters/query_product_category_detail_region |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
Authentication is required and has either failed or not been provided.
The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
The requested resource could not be found on this server.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | user_accounts:read |
| client_credentials | user_accounts:read |
Get account information for the "operation user_account"
If using Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". See Understanding Business Access for more information.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
response
Not authorized to access the user account.
Unexpected error
| pinterest_oauth2 | user_accounts:read |
| client_credentials | user_accounts:read |
Get analytics for the "operation user_account"
Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
| start_date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today. |
query | object | #/components/parameters/query_start_date |
| end_date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. |
query | object | #/components/parameters/query_end_date |
| from_claimed_content | Filter on Pins that match your claimed domain. |
query | object | #/components/parameters/query_from_claimed_content |
| pin_format | Pin formats to get data for, default is all. |
query | object | #/components/parameters/query_pin_format |
| app_types | Apps or devices to get data for, default is all. |
query | object | #/components/parameters/query_app_types |
| content_type | Filter to paid or organic data. Default is all. |
query | object | #/components/parameters/query_content_type |
| source | Filter to activity from Pins created and saved by your, or activity created and saved by others from your claimed accounts |
query | object | #/components/parameters/query_source |
| metric_types | Metric types to get data for, default is all. |
query | object | #/components/parameters/query_metric_types |
| split_field | How to split the data into groups. Not including this param means data won't be split. |
query | object | #/components/parameters/query_split_field_user_account |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Invalid user accounts analytics parameters.
Not authorized to access the user account analytics.
Unexpected error
| pinterest_oauth2 | user_accounts:read |
Gets analytics data about a user's top pins (limited to the top 50).
Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
| start_date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today. |
query | object | #/components/parameters/query_start_date |
| end_date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. |
query | object | #/components/parameters/query_end_date |
| sort_by | Specify sorting order for metrics |
query | object | #/components/parameters/query_sort_by |
| from_claimed_content | Filter on Pins that match your claimed domain. |
query | object | #/components/parameters/query_from_claimed_content |
| pin_format | Pin formats to get data for, default is all. |
query | object | #/components/parameters/query_pin_format |
| app_types | Apps or devices to get data for, default is all. |
query | object | #/components/parameters/query_app_types |
| content_type | Filter to paid or organic data. Default is all. |
query | object | #/components/parameters/query_content_type |
| source | Filter to activity from Pins created and saved by your, or activity created and saved by others from your claimed accounts |
query | object | #/components/parameters/query_source |
| metric_types | Metric types to get data for, default is all. |
query | object | #/components/parameters/query_metric_types |
| num_of_pins | Number of pins to include, default is 10. Max is 50. |
query | object | #/components/parameters/query_num_of_pins |
| created_in_last_n_days | Get metrics for pins created in the last "n" days. |
query | object | #/components/parameters/query_created_in_last_n_days |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Not authorized to access the user account analytics.
Unexpected error
| pinterest_oauth2 | pins:read , user_accounts:read |
| client_credentials | pins:read , user_accounts:read |
Gets analytics data about a user's top video pins (limited to the top 50).
Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
| start_date | Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today. |
query | object | #/components/parameters/query_start_date |
| end_date | Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date. |
query | object | #/components/parameters/query_end_date |
| sort_by | Specify sorting order for video metrics |
query | object | #/components/parameters/query_video_pin_sort_by |
| from_claimed_content | Filter on Pins that match your claimed domain. |
query | object | #/components/parameters/query_from_claimed_content |
| pin_format | Pin formats to get data for, default is all. |
query | object | #/components/parameters/query_pin_format |
| app_types | Apps or devices to get data for, default is all. |
query | object | #/components/parameters/query_app_types |
| content_type | Filter to paid or organic data. Default is all. |
query | object | #/components/parameters/query_content_type |
| source | Filter to activity from Pins created and saved by your, or activity created and saved by others from your claimed accounts |
query | object | #/components/parameters/query_source |
| metric_types | Metric types to get video data for, default is all. |
query | object | #/components/parameters/query_video_pin_metric_types |
| num_of_pins | Number of pins to include, default is 10. Max is 50. |
query | object | #/components/parameters/query_num_of_pins |
| created_in_last_n_days | Get metrics for pins created in the last "n" days. |
query | object | #/components/parameters/query_created_in_last_n_days |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Not authorized to access the user account analytics.
Unexpected error
| pinterest_oauth2 | pins:read , user_accounts:read |
| client_credentials | pins:read , user_accounts:read |
Get a list of your linked business accounts.
Success
Unexpected error
| pinterest_oauth2 | user_accounts:read |
| client_credentials | user_accounts:read |
Get a list of your followers.
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
Success
Invalid user id
Unexpected error
| pinterest_oauth2 | user_accounts:read |
| client_credentials | user_accounts:read |
Get a list of who a certain user follows.
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| feed_type | Thrift param specifying what type of followees will be kept. Default to include all followees. |
query | object | #/components/parameters/query_user_following_feed_type |
| explicit_following | Whether or not to include implicit user follows, which means followees with board follows. When explicit_following is True, it means we only want explicit user follows. |
query | object | #/components/parameters/query_explicit_following |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
response
Unexpected error
| pinterest_oauth2 | user_accounts:read |
| client_credentials | user_accounts:read |
Get a list of the boards a user follows. The request returns a board summary object array.
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
| explicit_following | Whether or not to include implicit user follows, which means followees with board follows. When explicit_following is True, it means we only want explicit user follows. |
query | object | #/components/parameters/query_explicit_following |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Invalid user id
Unexpected error
| pinterest_oauth2 | user_accounts:read |
| client_credentials | user_accounts:read |
This endpoint is currently in beta and not available to all apps. Learn more.
Use this request, as a signed-in user, to follow another user.
| username | A valid username |
path | object | #/components/parameters/path_username |
Success
User not found
Unexpected error
| pinterest_oauth2 | user_accounts:write |
Unverifu a website verified by the signed-in user.
| website | Website with path or domain only |
query | object | #/components/parameters/query_website |
Successfully unverified website
Website not in user list.
Unexpected error
| pinterest_oauth2 | user_accounts:write |
Get user websites, claimed or not
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
Success
Not authorized to access the user website list.
Unexpected error
| pinterest_oauth2 | user_accounts:read |
Verify a website as a signed-in user.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Unexpected error
| pinterest_oauth2 | user_accounts:write |
Get verification code for user to install on the website to claim it.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
Success
Not authorized to access the user verification code for website claiming.
Unexpected error
| pinterest_oauth2 | user_accounts:read |
| client_credentials | user_accounts:read |
Get a list of a user's following interests in one place.
| username | A valid username |
path | object | #/components/parameters/path_username |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_bookmark |
| page_size | Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_page_size |
Success
Invalid parameters
Authorization failed
User not found
Unexpected error
| pinterest_oauth2 | user_accounts:read |
| client_credentials | user_accounts:read |