Version: 5.28.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 |
| POST /ad_accounts/{ad_account_id}/campaigns/delivery_estimates | Get campaign delivery estimates |
| 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 |
|---|---|
| GET /catalogs/product_groups | List product groups |
| POST /catalogs/product_groups | Create product group |
| DELETE /catalogs/product_groups/multiple | Delete product groups |
| POST /catalogs/product_groups/multiple | Create product groups |
| GET /catalogs/product_groups/{product_group_id} | Get product group |
| PATCH /catalogs/product_groups/{product_group_id} | Update single product group |
| DELETE /catalogs/product_groups/{product_group_id} | Delete 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 |
|---|---|
| GET /catalogs/reports | Get catalogs report |
| POST /catalogs/reports | Build catalogs report |
| GET /catalogs/reports/stats | List report stats |
View and manage catalog supplemental items.
| Operation | Description |
|---|---|
| POST /catalogs/{catalog_id}/local_inventory_items/batch | Operate on local inventory item batch |
| POST /catalogs/{catalog_id}/local_inventory_items/query | Get local inventory items (POST) |
| GET /catalogs/{catalog_id}/local_stores | List local stores |
| POST /catalogs/{catalog_id}/local_stores | Create local stores |
| PATCH /catalogs/{catalog_id}/local_stores | Update local stores |
| DELETE /catalogs/{catalog_id}/local_stores | Delete local stores |
| GET /catalogs/{catalog_id}/supplemental_items/batch/{batch_id} | Get supplemental items batch status |
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 |
View, create, or delete conversion data deletion requests.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/conversion_deletion_requests | List conversion deletion requests |
| POST /ad_accounts/{ad_account_id}/conversion_deletion_requests | Create a conversion deletion request |
| GET /ad_accounts/{ad_account_id}/conversion_deletion_requests/{request_id} | Get a single conversion deletion request |
| DELETE /ad_accounts/{ad_account_id}/conversion_deletion_requests/{request_id} | Delete a conversion deletion request |
View, create or update ad groups.
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) |
Submit conversion events via the Pinterest API.
| Operation | Description |
|---|---|
| POST /ad_accounts/{ad_account_id}/events | Send conversions |
| Operation | Description |
|---|
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 manage customer list uploads.
| 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 |
View, create, or update customer lists.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/customer_lists | Get customer lists |
| POST /ad_accounts/{ad_account_id}/customer_lists | Create 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 customer segments.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/customer_segments | List customer segments |
| POST /ad_accounts/{ad_account_id}/customer_segments | Create customer segments |
| PATCH /ad_accounts/{ad_account_id}/customer_segments | Update customer segments |
View, create, or update commerce integrations.
| Operation | Description |
|---|---|
| GET /integrations | Get integration metadata list |
| 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/{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 ad account labels.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/labels | List labels |
| POST /ad_accounts/{ad_account_id}/labels | Create labels |
| PATCH /ad_accounts/{ad_account_id}/labels | Update labels |
| POST /ad_accounts/{ad_account_id}/labels/{label_id}/apply | Apply label to entity |
| POST /ad_accounts/{ad_account_id}/labels/{label_id}/remove | Remove label from entities |
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 |
| POST /ad_accounts/{ad_account_id}/campaign_ad_preview | Create ad preview records for one or more ad groups |
| GET /ad_accounts/{ad_account_id}/campaign_ad_preview | Fetch ad preview records for one or more ad groups |
| DELETE /ad_accounts/{ad_account_id}/campaign_ad_preview | Delete ad preview records for one or more ad groups |
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 |
Send notifications.
| Operation | Description |
|---|---|
| POST /notifications | Receive notifications from external partners. |
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 |
| Operation | Description |
|---|
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 |
| Operation | Description |
|---|
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 |
| Operation | Description |
|---|
View, create, update, or delete information about Pins.
| Operation | Description |
|---|---|
| POST /pins | Create Pin |
| GET /pins | List Pins |
| GET /pins/analytics | Get multiple Pin analytics |
| 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 |
| 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 |
Tag products to hero pins.
| Operation | Description |
|---|---|
| POST /pins/{pin_id}/product_tags | Add product tags to pin |
| GET /pins/{pin_id}/product_tags | Get product tags for pin |
| POST /pins/{pin_id}/product_tags/bulk-delete | Delete product tags from pin |
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 |
| Operation | Description |
|---|
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/partner/pins | Search pins by a given search term |
| GET /search/pins | Search user's Pins |
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 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 Advertising Terms Of Service.
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/terms_of_service | Get terms of service |
View trending terms, topics, and product categories.
| Operation | Description |
|---|---|
| GET /trends/editorial_articles | Returns editorial articles for a given region |
| GET /trends/product_categories/details | Get product category details |
| GET /trends/product_categories/trending | Get a list of growing Shopping Product Categories |
| GET /trends/topics/featured | Get featured topics |
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 |
| GET /user_account/websites | Get user websites |
| POST /user_account/websites | Verify website |
| 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 |
| POST /ad_accounts/{ad_account_id}/advertiser_defined_events | Create advertiser defined events |
| PATCH /ad_accounts/{ad_account_id}/advertiser_defined_events | Update advertiser defined events |
| DELETE /ad_accounts/{ad_account_id}/advertiser_defined_events | Delete advertiser defined events |
| Operation | Description |
|---|---|
| GET /ad_accounts/{ad_account_id}/schedules | Get Schedules |
| POST /ad_accounts/{ad_account_id}/schedules | Create schedules |
| PATCH /ad_accounts/{ad_account_id}/schedules | Update schedules |
| Operation | Description |
|---|---|
| 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 |
| GET /businesses/employers | List business employers for user |
| GET /businesses/{business_id}/members | Get business members |
| DELETE /businesses/{business_id}/members | Terminate business memberships |
| PATCH /businesses/{business_id}/members | Update member's business role |
| GET /businesses/{business_id}/partners | Get business partners |
| DELETE /businesses/{business_id}/partners | Terminate business partnerships |
| PATCH /businesses/{business_id}/system_users/{system_user_id} | Update a system user information. |
| Operation | Description |
|---|---|
| PATCH /businesses/invites | Accept or decline an invite/request |
| 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 |
| 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. |
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 |
|---|---|
| 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 /ad_accounts/{ad_account_id}/audiences/shared/accounts | List accounts with access to an audience owned by an ad account |
| GET /businesses/{business_id}/audiences | List received audiences for 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 |
| GET /businesses/{business_id}/audiences/shared/accounts | List accounts with access to an audience owned by a business |
View, create, or update audiences.
| Operation | Description |
|---|---|
| POST /ad_accounts/{ad_account_id}/audiences | Create audience |
| GET /ad_accounts/{ad_account_id}/audiences | List audiences |
| PATCH /ad_accounts/{ad_account_id}/audiences/{audience_id} | Update audience |
| GET /ad_accounts/{ad_account_id}/audiences/{audience_id} | Get 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 |
| DELETE /boards/{board_id}/sections/{section_id} | Delete board section |
| PATCH /boards/{board_id}/sections/{section_id} | Update 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 | #/components/parameters/AdAccountsGetAdditionalParams |
| 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.
| 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 |
| 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/Pinterest.Lib.OrderingParams |
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| 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 retrieve keywords from. This feature is currently in BETA and is not available to all users. |
query | object | #/components/parameters/query_ad_group_ids |
| entity_statuses | Entity status |
query | object | #/components/parameters/query_entity_statuses |
| 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 |
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 |
Update multiple existing ad groups.
| 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: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:
To convert dollars to microdollars, multiply dollars by 1,000,000
To convert microdollars to dollars, divide microdollars by 1,000,000
Ad groups belong to ad campaigns. Some types of campaigns (e.g. budget optimization) have limits on the number of ad groups they can hold. If you exceed those limits, you will get an error message.
Certain organizations with closed beta access can set 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.
If the parent ad campaign has start and end times set, ad group start and end times must occur within the parent campaign schedule.
| 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:write |
Get analytics for the specified ad groups in the specified ad_account_id, filtered by the specified options.
| 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. For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound). If a column has no value, it may not be returned. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. DAY - metrics are broken down daily. HOUR - metrics are broken down hourly. WEEK - metrics are broken down weekly. MONTH - metrics are broken down monthly |
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 |
| 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 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/Pinterest.Lib.AdAccountId |
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 |
| 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/Pinterest.Lib.AdAccountId |
| 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 is independent from each other. ["AGE_BUCKET_AND_GENDER", "CREATIVE_ENHANCEMENTS"] are in BETA and not yet available to all users. |
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. For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound). If a column has no value, it may not be returned. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. DAY - metrics are broken down daily. HOUR - metrics are broken down hourly. WEEK - metrics are broken down weekly. MONTH - metrics are broken down monthly |
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 |
| sort_columns | Sort Columns. |
query | object | #/components/parameters/query_sort_columns |
| sort_ascending | Sort ascending. |
query | object | #/components/parameters/query_sort_ascending |
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 specific ad group given the ad group ID.
| ad_group_id | Ad group ID. |
path | object | #/components/parameters/AdGroupKey |
| 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 |
Validate and process the uploaded dynamic titles review CSV. Returns validation errors if the CSV is invalid.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| ad_group_id | Ad group ID. |
path | object | #/components/parameters/path_ad_group_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 | ads:write |
Get a presigned S3 download URL for the dynamic titles review CSV. Returns 400 if titles have not been generated yet.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| ad_group_id | Ad group ID. |
path | object | #/components/parameters/path_ad_group_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 | ads:read |
Get dynamic titles generation status for an ad group, including whether titles are ready for review and counts of generated and reviewed titles.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| ad_group_id | Ad group ID. |
path | object | #/components/parameters/path_ad_group_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 | ads:read |
Get a presigned S3 upload URL for the dynamic titles review CSV and a request_id for submission.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| ad_group_id | Ad group ID. |
path | object | #/components/parameters/path_ad_group_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 | 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.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
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 |
List ads that meet the filters provided: - Listed campaign ids or ad group ids or ad ids - Listed entity statuses
If no filter is provided, all ads in the ad account are returned.
Note:
Provide only campaign_id or ad_group_id or ad_id. Do not provide more than one type.
Review status is provided for each ad; if review_status is REJECTED, the rejected_reasons field will contain additional information.
For more, see Pinterest advertising standards.
| 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 |
| 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/Pinterest.Lib.OrderingParams |
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| 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 retrieve keywords from. This feature is currently in BETA and is not available to all users. |
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 |
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 |
Update multiple existing ads
| 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: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/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:write |
Get analytics for the specified ads in the specified `ad_account_id`, filtered by the specified options.
- The token's 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](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Campaign Manager.
- The request must contain either ad_ids or both campaign_ids and pin_ids.
- If granularity is not HOUR, you can pull data from up to 90 days before the current date in UTC time, with a maximum time range of 90 days.
- If granularity is HOUR, you can pull data from up to 8 days before the current date in UTC time, with a maximum time range of 3 days.| pin_ids | List of Pin IDs. |
query | object | #/components/parameters/query_string_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 |
| 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. For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound). If a column has no value, it may not be returned. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. DAY - metrics are broken down daily. HOUR - metrics are broken down hourly. WEEK - metrics are broken down weekly. MONTH - metrics are broken down monthly |
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 |
| 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 |
| 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 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/Pinterest.Lib.AdAccountId |
| 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 is independent from each other. ["AGE_BUCKET_AND_GENDER"] is in BETA and not yet available to all users. |
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. For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound). If a column has no value, it may not be returned. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. DAY - metrics are broken down daily. HOUR - metrics are broken down hourly. WEEK - metrics are broken down weekly. MONTH - metrics are broken down monthly |
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_daysOptimal |
| 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_daysOptimal |
| 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_daysOptimal |
| 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_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 |
| sort_columns | Sort Columns. |
query | object | #/components/parameters/query_sort_columns |
| sort_ascending | Sort ascending. |
query | object | #/components/parameters/query_sort_ascending |
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 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_id | The ID of this ad. |
path | object | #/components/parameters/AdKey |
| 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 |
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/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 , 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/Pinterest.Lib.AdAccountId |
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 , billing:write |
Untrack advertiser defined events for the given ad account.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| event_names | List of event names to delete |
query | object | #/components/parameters/AdvertiserDefinedEventsDeleteQuery |
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:write |
| client_credentials | ads:write |
Get advertiser defined events for the given ad account.
| 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 |
Update advertiser defined event names or mappings for the given ad account.
| 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:write |
| client_credentials | ads:write |
Map advertiser defined events to standard events for the given ad account.
| 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:write |
| client_credentials | ads:write |
Get analytics for the specified ad_account_id, filtered by the specified options.
The token's 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, Campaign Manager.
If granularity is not HOUR, you can pull data from up to 90 days before the current date in UTC time, with a maximum time range of 90 days.
If granularity is HOUR, you can pull data from up to 8 days before the current date in UTC time.
| 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. For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound). If a column has no value, it may not be returned. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. DAY - metrics are broken down daily. HOUR - metrics are broken down hourly. WEEK - metrics are broken down weekly. MONTH - metrics are broken down monthly |
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 |
| 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 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.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| audience_insight_type | Type of audience insights. |
query | object | #/components/parameters/audience_insights_query_params |
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 list of audiences for the ad account.
| 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 |
| 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/Pinterest.Lib.OrderingParams |
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| ownership_type | query | object | #/components/parameters/AudienceGetAdditionalParams.ownership_type | |
| exclude_nca | When true, excludes audiences derived from new customer acquisition (expanded matching) customer lists from the result. Defaults to false (include all). |
query | object | #/components/parameters/AudienceGetAdditionalParams.exclude_nca |
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 audience for the ad account.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
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 a specific audience given the audience ID.
| audience_id | Audience ID. |
path | object | #/components/parameters/AdAccountsAudienceKey |
| 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 |
Update an existing audience for the ad account.
| audience_id | Audience ID. |
path | object | #/components/parameters/AdAccountsAudienceKey |
| 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: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:
For more on bid floors see Set your bid.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
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 |
| client_credentials | ads:read |
Get download url for a billing invoice.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| billing_invoice_id | Unique identifier of a billing invoice. |
path | object | #/components/parameters/path_billing_invoice_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 | ads:read , billing:read |
Get billing invoices in the advertiser account.
| 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 |
| 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/Pinterest.Lib.OrderingParams |
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| sort | Field of which to sort billing invoices |
query | object | #/components/parameters/query_sort_billing_invoice |
| 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 |
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 , billing:read |
Get billing profiles in the advertiser account.
This endpoint might not be available to all apps. Learn more.
| is_active | Return active billing profiles, if false return all billing profiles. |
query | object | #/components/parameters/query_billing_profiles_is_active |
| 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 , billing:read |
Create an asynchronous report that may include information on campaigns, ad groups, product groups, ads, keywords, schedules,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/Pinterest.Lib.AdAccountId |
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 |
Either create or update any combination of campaigns, ad groups, product groups, ads, keywords, schedules, 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/Pinterest.Lib.AdAccountId |
The request has succeeded.
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, schedules, or keywords).
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| bulk_request_id | Bulk request ID that is from one of the entities bulk endpoints |
path | object | #/components/parameters/BulkRequestStatusParameters.bulk_request_id |
| include_details | If set to True then attach the errors/details to all the requests |
query | object | #/components/parameters/BulkRequestStatusParameters.include_details |
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 |
Delete ad preview records for one or more ad groups. All ad groups are validated before deleting any records.
| ad_group_ids | List of Ad group Ids to use to filter the results. |
query | object | #/components/parameters/query_ad_group_ids_required |
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
The request has succeeded.
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 |
Fetch ad preview records for one or more ad groups. Returns all active previews associated with the provided ad group IDs.
| ad_group_ids | List of Ad group Ids to use to filter the results. |
query | object | #/components/parameters/query_ad_group_ids_required |
| 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 |
Create ad preview records for one or more ad groups that can be shared. Each ad group is processed independently; individual failures do not block other previews.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
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 a list of the campaigns in the specified ad_account_id, filtered by the specified options.
| 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 |
| 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/Pinterest.Lib.OrderingParams |
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| 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 |
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 |
Update multiple ad campaigns based on campaign_ids.
Note:
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/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: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:
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/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:write |
Get analytics for the specified campaigns in the specified ad_account_id, filtered by the specified options.
| 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. For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound). If a column has no value, it may not be returned. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. DAY - metrics are broken down daily. HOUR - metrics are broken down hourly. WEEK - metrics are broken down weekly. MONTH - metrics are broken down monthly |
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 |
| 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 delivery estimates for an ads campaign
This endpoint is currently in beta and is not available to all apps Learn more.
| 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.
The service is temporarily unavailable.
An unexpected error response.
| pinterest_oauth2 | 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/Pinterest.Lib.AdAccountId |
| 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 is independent from each other. ["AGE_BUCKET_AND_GENDER"] is in BETA and not yet available to all users. |
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. For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound). If a column has no value, it may not be returned. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. DAY - metrics are broken down daily. HOUR - metrics are broken down hourly. WEEK - metrics are broken down weekly. MONTH - metrics are broken down monthly |
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 |
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 specific campaign given the campaign ID.
| campaign_id | Campaign ID, must be associated with the ad account ID provided in the path. |
path | object | #/components/parameters/CampaignKey |
| 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 |
This endpoint is currently in beta and not available to all apps.
Learn more.
Get a list of the conversion deletion requests for the specified 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 |
| 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/Pinterest.Lib.OrderingParams |
| 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 |
This endpoint is currently in beta and not available to all apps.
Learn more.
Create a request to delete conversion data for a list of user emails and/or EPIKs, limited to the specified ad_account_id.
After 72 hours the request is processed and submitted to our deletion process. Then the deletion process ensures deletion
within a 30 days period, once the request is submitted to the deletion process it cannot be canceled.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
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 |
| client_credentials | ads:write |
This endpoint is currently in beta and not available to all apps.
Learn more.
Delete a conversion deletion request from ad_account_id with request_id.
This will cancel the request and prevent it from being processed. This can only be
done if the request is in the PENDING status and before the 72 hours mark.
| request_id | Unique identifier of the conversion deletion request |
path | object | #/components/parameters/ConversionDeletionRequestKey |
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
The request has succeeded.
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 |
| client_credentials | ads:write |
This endpoint is currently in beta and not available to all apps.
Learn more.
Get a single conversion deletion request from ad_account_id with request_id.
| request_id | Unique identifier of the conversion deletion request |
path | object | #/components/parameters/ConversionDeletionRequestKey |
| 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 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 | path | object | #/components/parameters/CustomerListParentKey | |
| 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 |
| 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/Pinterest.Lib.OrderingParams |
| exclude_nca | When true, excludes customer lists uploaded for new customer acquisition (expanded matching) from the result. Defaults to false (include all). |
query | object | #/components/parameters/query_exclude_nca |
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 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 | path | object | #/components/parameters/CustomerListParentKey |
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 |
Gets a specific customer list given the customer list ID.
| ad_account_id | path | object | #/components/parameters/CustomerListKey.id | |
| customer_list_id | Customer list ID. |
path | object | #/components/parameters/CustomerListKey.customer_list_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 | 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 | path | object | #/components/parameters/CustomerListKey.id | |
| customer_list_id | Customer list ID. |
path | object | #/components/parameters/CustomerListKey.customer_list_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 | 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 | path | object | #/components/parameters/CustomerListUploadParentKey.id | |
| customer_list_id | Customer list ID. |
path | object | #/components/parameters/CustomerListUploadParentKey.customer_list_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 | ads:write |
Get the metadata for a given upload by its ID.
| ad_account_id | path | object | #/components/parameters/CustomerListUploadKey.id | |
| customer_list_id | Customer list ID. |
path | object | #/components/parameters/CustomerListUploadKey.customer_list_id |
| customer_list_upload_id | Customer List Upload ID. |
path | object | #/components/parameters/CustomerListUploadKey.customer_list_upload_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 | ads:read |
Begin processing a customer list upload.
| ad_account_id | path | object | #/components/parameters/CustomerListUploadKey.id | |
| customer_list_id | Customer list ID. |
path | object | #/components/parameters/CustomerListUploadKey.customer_list_id |
| customer_list_upload_id | Customer List Upload ID. |
path | object | #/components/parameters/CustomerListUploadKey.customer_list_upload_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 | ads:write |
Get a list of the customer segments in the specified 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 |
| 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/Pinterest.Lib.OrderingParams |
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| include_sizing | Include audience sizing in result or not |
query | object | #/components/parameters/customer_segments_include_sizing |
| search_query | Search query. Can contain pin description keywords or comma-separated pin IDs. |
query | object | #/components/parameters/customer_segments_search_query |
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 |
Update the customer segment given advertiser ID and customer segment ID
| 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:write |
Customer segments allow advertisers to define existing customers for Pinterest Performance+ campaigns. Customer segments are made up of audience lists.
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
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 |
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/Pinterest.Lib.AdAccountId |
| 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 | #/components/parameters/EventsCreateQueryParams |
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 request was well-formed but was unable to be followed due to semantic errors.
The user has sent too many requests in a given amount of time and is being rate limited.
The server is currently unable to handle the request due to a temporary overload or scheduled maintenance.
An unexpected error response.
| 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/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 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](https://help.pinterest.com/en/business/article/keyword-targeting).
**Notes:**
- Advertisers and campaigns can only be assigned keywords with excluding (`_NEGATIVE`).
- All keyword match types are available for ad groups.
For more information on match types, see [match type enums](/docs/api-features/targeting-overview/).
**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:
```json
{
"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."
]
}
]
}| 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/query_ad_group_ids |
| match_types | Keyword match type |
query | object | #/components/parameters/query_match_types |
| 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 |
| 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 are no longer visible within the parent entity's keywords list.
| 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:write |
Create keywords for the following entity types (advertiser, campaign, ad group, or ad). For more information, see Keyword targeting.
Notes:
Advertisers and campaigns can only be assigned keywords with excluding (_NEGATIVE).
All keyword match types are available for ad groups.
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:
```json
{
"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/Pinterest.Lib.AdAccountId |
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 |
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/Pinterest.Lib.AdAccountId |
| 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 |
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 |
See a list of labels for assets that your account owns, and filter the list by different criteria. If no filter is provided, it will default to labels associated with the 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 |
| 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 |
Change the properties of one or more labels.
| 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:write |
Apply one or more labels to a campaign. Future releases may support labels for other entities. 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/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:write |
Apply a label to one or more campaigns. Future releases may support labels for other entities in addition to campaigns. 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 up to 30 custom labels to a campaign.
| ad_account_id | path | object | #/components/parameters/LabeledEntitiesKey.id | |
| label_id | Label ID. |
path | object | #/components/parameters/LabeledEntitiesKey.label_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 | ads:write |
Remove a label from one or more entities.
| ad_account_id | path | object | #/components/parameters/LabeledEntitiesKey.id | |
| label_id | Label ID. |
path | object | #/components/parameters/LabeledEntitiesKey.label_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 | 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.
| 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 |
| 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/Pinterest.Lib.OrderingParams |
| 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 |
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/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: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/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: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.
| lead_form_id | The ID of this lead form |
path | object | #/components/parameters/LeadFormKey |
| 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 |
Create lead form test data based on the list of answers provided as part of the body.
| ad_account_id | path | object | #/components/parameters/LeadFormTestKey.id | |
| lead_form_id | Unique identifier of a lead form. |
path | object | #/components/parameters/LeadFormTestKey.lead_form_id |
The request has succeeded.
The request could not be understood by the server due to unexpected data.
The requested resource could not be found on this server.
An unexpected error response.
| 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 |
The request has succeeded.
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 leads_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/Pinterest.Lib.AdAccountId |
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 |
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/Pinterest.Lib.AdAccountId |
| leads_export_id | lead_export_id token returned from the create a lead export endpoint |
path | object | #/components/parameters/path_leads_export_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 | 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 | path | object | #/components/parameters/MMMReportKey | |
| token | Token returned from the post request creation call |
query | object | #/components/parameters/query_token_required |
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 |
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.
For the ADVERTISER_PAID_SPEND_IN_DOLLAR,
ADVERTISER_PAID_ECPC_IN_DOLLAR, and ADVERTISER_PAID_ECPM_IN_DOLLAR
columns: if you receive bonus media, this value still includes that spend, and it will
need to be removed manually with support from your Pinterest account team for a
fully netted value. Over time, we'll also subtract bonus media and other incentives as
data becomes available. Production and other non-media fees are excluded.| ad_account_id | path | object | #/components/parameters/MMMReportKey |
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 |
This feature is currently in beta and not available to all apps. If you are interested in joining the beta, 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/Pinterest.Lib.AdAccountId |
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 | msot:write |
List existing order lines associated with an ad account.
| 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 |
| 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/Pinterest.Lib.OrderingParams |
| 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 |
Get a specific existing order line associated with an ad account.
| order_line_id | Order line ID. |
path | object | #/components/parameters/OrderLineKey |
| 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 |
Get analytics for the pins given a campaign and pins in the specified ad_account_id, filtered by the specified options.
| 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. For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound). If a column has no value, it may not be returned. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. DAY - metrics are broken down daily. HOUR - metrics are broken down hourly. WEEK - metrics are broken down weekly. MONTH - metrics are broken down monthly |
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 |
| 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 |
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.
| 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 |
| 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/Pinterest.Lib.OrderingParams |
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| product_group_promotion_ids | List of Product group promotion Ids. |
query | object | #/components/parameters/product_group_promotions_list_query.product_group_promotion_ids |
| entity_statuses | Entity status |
query | object | #/components/parameters/product_group_promotions_list_query.entity_statuses |
| ad_group_id | Ad group Id. |
query | object | #/components/parameters/query_ad_group_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 | 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/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: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/Pinterest.Lib.AdAccountId |
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 a product group promotion by id
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| product_group_promotion_id | Unique identifier of a product group promotion |
path | object | #/components/parameters/path_product_group_promotion_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 | ads:read |
Get analytics for the specified product groups in the specified ad_account_id, filtered by the specified options.
| 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. For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound). If a column has no value, it may not be returned. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. DAY - metrics are broken down daily. HOUR - metrics are broken down hourly. WEEK - metrics are broken down weekly. MONTH - metrics are broken down monthly |
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 |
| 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 list of ad groups that are associated with those promotion ids
| 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 |
| 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/Pinterest.Lib.OrderingParams |
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| promotion_ids | List of Promotion IDs to use to filter the results. |
query | object | #/components/parameters/query_promotion_ids |
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 |
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.
| 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 |
| 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/Pinterest.Lib.OrderingParams |
| 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 |
Update multiple promotions.
| 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:write |
Create multiple new promotions.
| 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:write |
Delete a promotion within Pinterest.
| promotion_id | Promotion ID |
path | object | #/components/parameters/PromotionKey |
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
The request has succeeded.
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 a promotion by its Pinterest-specific id. It must be associated with the provided ad account id.
| promotion_id | Promotion ID |
path | object | #/components/parameters/PromotionKey |
| 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 |
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/Pinterest.Lib.AdAccountId |
| token | Token returned from the post request creation call |
query | object | #/components/parameters/query_report_token_required |
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 |
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/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 |
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/Pinterest.Lib.AdAccountId |
| token | Token returned from the post request creation call |
query | object | #/components/parameters/query_report_token_required |
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 |
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/Pinterest.Lib.AdAccountId |
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 |
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/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:write |
Get schedules for a specific advertiser
| ad_account_id | path | object | #/components/parameters/ScheduleParentKey | |
| 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 |
| 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/Pinterest.Lib.OrderingParams |
| schedule_statuses | Filter schedules by status (one or more) |
query | object | #/components/parameters/SchedulesFilters.schedule_statuses |
| schedule_type | Filter schedules by a type |
query | object | #/components/parameters/SchedulesFilters.schedule_type |
| entity_ids | List of Entity IDs, must be associated with the Ad Accound ID provided in the path. |
query | object | #/components/parameters/SchedulesFilters.entity_ids |
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 |
Update one or more schedules
| ad_account_id | path | object | #/components/parameters/ScheduleParentKey |
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:write |
Batch create schedules
| ad_account_id | path | object | #/components/parameters/ScheduleParentKey |
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 Salesforce account details including bill-to information to be used in insertion orders process for ad_account_id.
user_account must either be the owner of the specified ad account, or have one of the necessary roles granted via Business Access: Admin, Finance, Campaign.| 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 |
Edit insertion order through SSIO for ad_account_id.
user_account must either be the owner of the specified ad account, or have one of the necessary roles granted via Business Access: Admin, Finance, Campaign.| 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:write |
Create insertion order through SSIO for ad_account_id.
user_account must either be the owner of the specified ad account, or have one of the necessary roles granted via Business Access: Admin, Finance, Campaign.| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
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 insertion order status for ad_account_id.
user_account must either be the owner of the specified ad account, or have one of the necessary roles granted via Business Access: Admin, Finance, Campaign.| 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 |
Get insertion order status for pin_order_id.
user_account must either be the owner of the specified ad account, or have one of the necessary roles granted via Business Access: Admin, Finance, Campaign.| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| pin_order_id | The pin order id associated with the ssio insertion order |
path | object | #/components/parameters/path_pin_order_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 | ads:read |
Get Salesforce order lines for account id ad_account_id.
user_account must either be the owner of the specified ad account, or have one of the necessary roles granted via Business Access: Admin, Finance, Campaign.| pin_order_id | The pin order id associated with the SSIO insertion order |
query | object | #/components/parameters/query_pin_order_id |
| 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 |
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/Pinterest.Lib.AdAccountId |
| 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 is independent from each other. ["AGE_BUCKET_AND_GENDER"] is in BETA and not yet available to all users. |
query | object | #/components/parameters/query_ad_account_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. For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound). If a column has no value, it may not be returned. |
query | object | #/components/parameters/query_columns |
| granularity | TOTAL - metrics are aggregated over the specified date range. DAY - metrics are broken down daily. HOUR - metrics are broken down hourly. WEEK - metrics are broken down weekly. MONTH - metrics are broken down monthly |
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 |
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 list of the targeting templates in the specified 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 |
| 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/Pinterest.Lib.OrderingParams |
| ad_account_id | Unique identifier of an ad account. |
path | object | #/components/parameters/Pinterest.Lib.AdAccountId |
| include_sizing | Include audience sizing in result or not |
query | object | #/components/parameters/TargetingTemplatesListParams.include_sizing |
| search_query | Search query. Can contain pin description keywords or comma-separated pin IDs. |
query | object | #/components/parameters/TargetingTemplatesListParams.search_query |
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 |
Update the targeting template given advertiser ID and targeting template ID
| 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: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/Pinterest.Lib.AdAccountId |
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 |
Gets all Templates associated with an 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 |
| 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/Pinterest.Lib.OrderingParams |
| 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 |
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. WEEK - metrics are broken down weekly. MONTH - 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/Pinterest.Lib.AdAccountId |
| include_html | Return HTML in TOS text. |
query | object | #/components/parameters/terms_of_service_query_params.include_html |
| tos_type | Request type. |
query | object | #/components/parameters/terms_of_service_query_params.tos_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 | 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 |
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.
The server encountered an unexpected condition that prevented it from fulfilling the request.
An unexpected error response.
| 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 |
The request has succeeded.
Successful
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.
The server encountered an unexpected condition that prevented it from fulfilling the request.
An unexpected error response.
| 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 |
The request has succeeded.
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 |
| 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 |
| 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 |
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/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 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 |
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 |
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 |
The request has succeeded.
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 |
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 |
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 |
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/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 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 |
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 | biz_access:read , biz_access:write |
Update an existing Brand Account
| brand_account_id | path | object | #/components/parameters/BrandAccountKey | |
| business_hierarchy_id | business hierarchy node id |
path | object | #/components/parameters/path_business_hierarchy_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 request could not be processed because of a conflict in the current state of the resource.
The user has sent too many requests in a given amount of time and is being rate limited.
An unexpected error response.
| pinterest_oauth2 | biz_access:read , biz_access:write |
Get all of the viewing user's business employers.
| assets_summary | Include assets summary in the response if this is true. Defaults to 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_default_true |
| 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 | biz_access:read |
Accept or decline invites or requests.
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 | 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 |
The request has succeeded.
An unexpected error response.
| 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 |
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 | 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 |
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 | 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 | #/components/parameters/query_permissions_with_owner |
| child_asset_id | A child asset unique identifier. Used to fetch asset groups that contain the asset id as a child. |
query | object | #/components/parameters/query_child_asset_id |
| asset_group_id | An asset group unique identifier. Used to fetch assets contained within the specified asset group. |
query | object | #/components/parameters/query_asset_group_id |
| 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/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 | 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 |
| 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 |
| fetch_system_users | Fetches system users if True. Fetches regular user employees if False. |
query | object | #/components/parameters/query_fetch_system_users |
| 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 | 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/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 | 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 |
| 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/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 | 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 |
The request has succeeded.
An unexpected error response.
| 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/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 | 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 |
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 | 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 |
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 | 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 |
The request has succeeded.
An unexpected error response.
| 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/query_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 | #/components/parameters/query_member_business_roles |
| member_ids | A list of business members ids separated by comma. |
query | object | #/components/parameters/query_member_ids |
| 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/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 | biz_access:read |
Update a member's business role within the business.
| business_id | Business id |
path | object | #/components/parameters/path_business_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 | 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 |
The request has succeeded.
An unexpected error response.
| 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 |
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 | 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_with_conversion_tag |
| 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 |
| sort_by | The field to sort member assets by |
query | object | #/components/parameters/query_asset_sort_by |
| sort_ascending | Sort assets in ascending order |
query | object | #/components/parameters/query_asset_sort_ascending |
| search_by | The field to search member assets by |
query | object | #/components/parameters/query_asset_search_by |
| search_value | The value to search for |
query | object | #/components/parameters/query_asset_search_value |
| asset_permission_type | The type of asset permission to filter by |
query | object | #/components/parameters/query_asset_permission_type |
| ad_account_statuses | A list of ad account statuses to filter the assets by. Only used when asset_type is AD_ACCOUNT. |
query | object | #/components/parameters/query_ad_account_statuses_filter |
| bookmark | Cursor used to fetch the next page of items |
query | object | #/components/parameters/query_active_bookmark_params.bookmark |
| page_size | Maximum number of items to include in a single page. See documentation on Pagination for more information. |
query | object | #/components/parameters/query_active_bookmark_params.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 | 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 |
The request has succeeded.
The requested resource could not be found on this server.
An unexpected error response.
| 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. If partner_type=EXTERNAL, the asset being queried is for the accesses you have to the partner's business asset. |
query | object | #/components/parameters/query_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 | #/components/parameters/query_partner_ids |
| 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 |
| sort_ascending | Sort ascending. |
query | object | #/components/parameters/query_sort_ascending |
| 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 | 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 |
The request has succeeded.
An unexpected error response.
| 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 |
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 | 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_partner |
| 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. If partner_type=EXTERNAL, the asset being queried is for the accesses you have to the partner's business asset. |
query | object | #/components/parameters/query_business_partner_type_default |
| 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_internal |
| 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 |
| sort_by | The field to sort member assets by |
query | object | #/components/parameters/query_asset_sort_by |
| sort_ascending | Sort assets in ascending order |
query | object | #/components/parameters/query_asset_sort_ascending |
| search_by | The field to search member assets by |
query | object | #/components/parameters/query_asset_search_by |
| search_value | The value to search for |
query | object | #/components/parameters/query_asset_search_value |
| 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 | 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 |
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 | 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 | #/components/parameters/path_system_user_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 | 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.
| 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 | 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 |
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 | 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 | #/components/parameters/query_catalogs_catalog_id_required |
| 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 | #/components/parameters/query_catalogs_country |
| language | Language for the Catalogs Items |
query | object | #/components/parameters/query_catalogs_language |
| 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 | 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 partners, refer to Pinterest API for shopping.
| 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 |
| 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 | 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 partners, 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 |
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 | catalogs:read , catalogs:write |
| client_credentials | catalogs:read , catalogs:write |
Delete 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 partners, 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 |
The request has succeeded.
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 | 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 partners, 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 |
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 | 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 partners, 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 |
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 | 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 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 | 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 |
| 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 | 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 |
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 | 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 |
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 | 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 |
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 | 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.
| 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 |
| 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 | 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 |
| 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 | 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 |
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 | 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 |
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 | 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 |
The request has succeeded and a new resource has been created as a result.
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 | 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_product_group_id |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
The request has succeeded.
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 | catalogs:write |
Get a single 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_product_group_id |
| 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 | 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_product_group_id |
| 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 | 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_product_group_id |
| 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 | 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.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
| product_group_id | Unique identifier of a product group |
path | object | #/components/parameters/path_product_group_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 |
| 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 , catalogs:read , pins:read |
| client_credentials | 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/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 |
| 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 , 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 the post request creation call |
query | object | #/components/parameters/query_token_required |
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 | 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: The All Items report is limited to 25 million items per catalog.
| 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 | 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 |
| parameters | Contains the parameters for report identification. |
query | object | #/components/parameters/query_catalogs_report_stats_parameters |
| 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 | catalogs:read |
Managing local inventory information in batches supporting CREATE, UPDATE, UPSERT, DELETE operations. Up to 1000 items per request to match catalogs/items.
Must provide both item_id and store_code to identify a local inventory item.
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, Catalogs Manager.
| catalog_id | Unique identifier of a catalog. |
path | object | #/components/parameters/CatalogId |
| 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 | catalogs:write |
Get local inventory items for a catalog owned by the "operation user_account".
Must provide an array of {item_id, store_code} pairs in item filters to identify local inventory items.
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, Catalogs Manager.
| catalog_id | Unique identifier of a catalog. |
path | object | #/components/parameters/CatalogId |
| 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 | catalogs:read |
Delete multiple local stores for a catalog owned by the "operation user_account".
By default, the "operation user_account" is the token user_account.
Supports optional filtering by store codes.
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 | Unique identifier of a catalog. |
path | object | #/components/parameters/CatalogId |
| ids | List of local store IDs to filter by. |
query | object | #/components/parameters/query_local_store_ids_required |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
The request has succeeded.
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 | catalogs:write |
Fetch local stores 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.
| catalog_id | Unique identifier of a catalog. |
path | object | #/components/parameters/CatalogId |
| ids | List of local store IDs to filter by. |
query | object | #/components/parameters/query_local_store_ids |
| 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 | catalogs:read |
Update a local store for a catalog owned by the "operation user_account".
By default, the "operation user_account" is the token user_account.
Supports optional filtering by store codes.
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 | Unique identifier of a catalog. |
path | object | #/components/parameters/CatalogId |
| 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 | catalogs:write |
Create a local store 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.
| catalog_id | Unique identifier of a catalog. |
path | object | #/components/parameters/CatalogId |
| 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 | catalogs:write |
Fetch the status and results of a supplemental items batch operation.
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 | Unique identifier of a catalog. |
path | object | #/components/parameters/CatalogId |
| batch_id | Unique identifier of an items batch operation. |
path | object | #/components/parameters/ItemsBatchId |
| 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 | 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/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 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.
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 |
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 |
The request has succeeded.
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 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 |
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 |
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 |
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: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.
The request has succeeded.
The server could not understand the request due to invalid syntax.
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 integration metadata by ID. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager.
| id | Integration record ID. |
path | object | #/components/parameters/IntegrationRecordKey |
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 |
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.
The request has succeeded.
The request could not be understood by the server due to unexpected data.
An unexpected error response.
| 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.
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: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.
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.
| basic |
Revokes an access or refresh token. Only tokens issued for system users are currently supported. Revoked tokens become immediately invalid and unusable.
The request has succeeded.
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.
An unexpected error response.
| 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 |
| domain | Only return pins with links that match the exact domain. Domain should not include 'www.' prefix. For example, 'pinterest.com' is a valid domain, but 'www.pinterest.com' is not (will not match any pins). |
query | object | #/components/parameters/query_domain |
| domains | Only return pins with links whose domain matches any value in the list.
Values are joined comma-separated on the wire
(e.g. |
query | object | #/components/parameters/query_domains |
| include_product_tag_obj | Include product tag objects in the response with their associated links. |
query | object | #/components/parameters/query_include_product_tag_obj |
| 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 | #/components/parameters/query_multi_pins_analytics_metric_types |
| 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 , 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 |
The request has succeeded.
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 |
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 |
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 |
The request has succeeded and a new resource has been created as a result.
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 |
Get Ad Accounts countries
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 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 |
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 , 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.
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 |
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 | #/components/parameters/query_metrics_ready_state_date |
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 |
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 |
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 |
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](https://help.pinterest.com/en/business/article/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 |
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
| 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 |
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 |
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 |
| query | Search query. Can contain pin description keywords or comma-separated pin IDs. |
query | object | #/components/parameters/query_query |
| 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 , 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 | #/components/parameters/query_term |
| 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/Pinterest.Lib.BookmarkParams.bookmark |
| locale | Search locale. |
query | object | #/components/parameters/query_locale |
| limit | Max search result size |
query | object | #/components/parameters/query_result_limit |
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 |
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/Pinterest.Lib.BookmarkParams.bookmark |
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: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 |
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 |
Get a list of published editorial articles. Translations of the editorials will be provided if available; otherwise, the default language will be English.
| 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 |
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. The
|
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 | The list of supported interests is:
|
query | object | #/components/parameters/query_interest_list |
| genders | If set, filters the results to trends among users who identify with the
specified gender(s). If unset, trends among all genders will be returned.
The |
query | object | #/components/parameters/query_gender_list |
| ages | If set, filters the results to trends among users in the specified age range(s). If unset, trends among all age groups will be returned. |
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. If unset, no keyword filtering logic is applied. |
query | object | #/components/parameters/query_keyword_include_list |
| normalize_against_group | Governs how the resulting time series data will be normalized to a [0-100] scale. By default ( If set to |
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_demographics | Including the age and gender distribution for each keyword. By default
( |
query | object | #/components/parameters/query_include_demographics |
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 |
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 |
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 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 |
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 |
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 |
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 , 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 |
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 , user_accounts:read |
| client_credentials | pins:read , user_accounts:read |
Get a list of your linked business accounts.
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 your followers.
| 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 | user_accounts:read |
| client_credentials | user_accounts:read |
Get a list of who a certain user follows.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
| 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 |
| 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 |
| 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 | 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.
| ad_account_id | Unique identifier of an ad account. |
query | object | #/components/parameters/query_ad_account_id |
| 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 |
| 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 | 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 |
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 | user_accounts:write |
Unverify a website verified by the signed-in user.
| website | Website with path or domain only |
query | object | #/components/parameters/query_website |
The request has succeeded.
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 | user_accounts:write |
Get user websites, claimed or not
| 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 | 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 |
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 | 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 |
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 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/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 server could not understand the request due to invalid syntax.
Access is unauthorized.
The server cannot find the requested resource.
Unexpected error
| pinterest_oauth2 | user_accounts:read |
| client_credentials | user_accounts:read |