Pinterest

Pinterest REST API

Pinterest's REST API

Social#openapi

Fork copies the collection into your workspace, without the publisher's secrets, so you can add your own key and send requests. Star saves it to your starred APIs (Account › Marketplace) and helps others find it.

Overview

Pinterest's REST API

Endpoints 266

ad_accounts

  • GETList ad accounts/ad_accounts?include_shared_accounts=true&bookmark=string&page_size=25Get 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…
  • POSTCreate ad account/ad_accountsCreate a new ad account. Different ad accounts can support different currencies, payment methods, etc. An ad account is needed to create campaigns, ad groups,…
  • GETGet ad account/ad_accounts/:ad_account_idGet an ad account
  • GETGet ad account analytics/ad_accounts/:ad_account_id/analytics?start_date=2024-01-01&end_date=2024-01-01&columns=SPEND_IN_MICRO_DOLLAR&granularity=TOTAL&click_window_days=30&engagement_window_days=30&view_window_days=1&conversion_report_time=TIME_OF_AD_ACTION&reporting_timezone=PINTEREST_TIME_ZONEGet 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…
  • GETGet advertiser Marketing Mix Modeling (MMM) report./ad_accounts/:ad_account_id/mmm_reports?token=stringGet 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.
  • POSTCreate a request for a Marketing Mix Modeling (MMM) report/ad_accounts/:ad_account_id/mmm_reportsThis 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…
  • GETGet the account analytics report created by the async call/ad_accounts/:ad_account_id/reports?token=stringThis 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…
  • POSTCreate async request for an account analytics report/ad_accounts/:ad_account_id/reportsThis 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…
  • GETGet advertiser brand, category, SKU report/ad_accounts/:ad_account_id/reports/brand_category_sku?token=stringRestricted 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…
  • POSTCreate a request for a brand, category, SKU report/ad_accounts/:ad_account_id/reports/brand_category_skuRestricted 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…
  • DELETEDelete ads data for ad account in API Sandbox/ad_accounts/:ad_account_id/sandboxDelete 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…
  • GETGet targeting analytics for an ad account/ad_accounts/:ad_account_id/targeting_analytics?start_date=2024-01-01&end_date=2024-01-01&targeting_types=APPTYPE&columns=SPEND_IN_MICRO_DOLLAR&granularity=TOTAL&click_window_days=30&engagement_window_days=30&view_window_days=1&conversion_report_time=TIME_OF_AD_ACTION&attribution_types=INDIVIDUAL&reporting_timezone=PINTEREST_TIME_ZONEGet targeting analytics for an ad account. For the requested account and metrics, the response will include the requested metric information (e.g.…
  • GETList templates/ad_accounts/:ad_account_id/templates?bookmark=string&page_size=25&order=ASCENDINGGets all Templates associated with an ad account ID.
  • POSTCreate async request for an analytics report using a template/ad_accounts/:ad_account_id/templates/:template_id/reports?start_date=2024-01-01&end_date=2024-01-01&granularity=TOTALThis 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…

ad_groups

  • GETList ad groups/ad_accounts/:ad_account_id/ad_groups?bookmark=string&page_size=25&order=ASCENDING&campaign_ids=string&ad_group_ids=string&entity_statuses=ACTIVE,PAUSED&translate_interests_to_names=falseList 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…
  • POSTCreate ad groups/ad_accounts/:ad_account_id/ad_groupsCreate 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…
  • PATCHUpdate ad groups/ad_accounts/:ad_account_id/ad_groupsUpdate multiple existing ad groups.
  • GETGet ad group analytics/ad_accounts/:ad_account_id/ad_groups/analytics?start_date=2024-01-01&end_date=2024-01-01&ad_group_ids=string&columns=SPEND_IN_MICRO_DOLLAR&granularity=TOTAL&click_window_days=30&engagement_window_days=30&view_window_days=1&conversion_report_time=TIME_OF_AD_ACTION&aggregate_report_rows=false&reporting_timezone=PINTEREST_TIME_ZONEGet analytics for the specified ad groups in the specified ad_account_id, filtered by the specified options. The token's user_account must either be the Owner…
  • POSTGet audience sizing/ad_accounts/:ad_account_id/ad_groups/audience_sizingGet 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…
  • GETGet targeting analytics for ad groups/ad_accounts/:ad_account_id/ad_groups/targeting_analytics?ad_group_ids=string&start_date=2024-01-01&end_date=2024-01-01&targeting_types=APPTYPE&columns=SPEND_IN_MICRO_DOLLAR&granularity=TOTAL&click_window_days=30&engagement_window_days=30&view_window_days=1&conversion_report_time=TIME_OF_AD_ACTION&attribution_types=INDIVIDUAL&reporting_timezone=PINTEREST_TIME_ZONE&sort_columns=string&sort_ascending=trueGet 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.…
  • GETGet ad group/ad_accounts/:ad_account_id/ad_groups/:ad_group_idGet a specific ad group given the ad group ID.
  • POSTProcess dynamic titles CSV/ad_accounts/:ad_account_id/ad_groups/:ad_group_id/dynamic_titlesValidate and process the uploaded dynamic titles review CSV. Returns validation errors if the CSV is invalid.
  • GETGet dynamic titles CSV download URL/ad_accounts/:ad_account_id/ad_groups/:ad_group_id/dynamic_titles/csvGet a presigned S3 download URL for the dynamic titles review CSV. Returns 400 if titles have not been generated yet.
  • GETGet dynamic titles status/ad_accounts/:ad_account_id/ad_groups/:ad_group_id/dynamic_titles/statusGet dynamic titles generation status for an ad group, including whether titles are ready for review and counts of generated and reviewed titles.
  • GETGet dynamic titles upload URL/ad_accounts/:ad_account_id/ad_groups/:ad_group_id/dynamic_titles/uploadsGet a presigned S3 upload URL for the dynamic titles review CSV and a request_id for submission.
  • POSTGet bid floors/ad_accounts/:ad_account_id/bid_floorList bid floors for your campaign configuration. Bid floors are given in microcurrency values based on the currency in the bid floor specification.…
  • GETList of ad groups using promotions IDs./ad_accounts/:ad_account_id/promotion_applied_entities?bookmark=string&page_size=25&order=ASCENDING&promotion_ids=stringGet a list of ad groups that are associated with those promotion ids

ads

  • POSTCreate ad preview with pin or image/ad_accounts/:ad_account_id/ad_previewsCreate 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…
  • GETList ads/ad_accounts/:ad_account_id/ads?bookmark=string&page_size=25&order=ASCENDING&campaign_ids=string&ad_group_ids=string&ad_ids=string&entity_statuses=ACTIVE,PAUSEDList 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…
  • POSTCreate ads/ad_accounts/:ad_account_id/adsCreate multiple new ads. Request must contain ad_group_id, creative_type, and the source Pin pin_id.
  • PATCHUpdate ads/ad_accounts/:ad_account_id/adsUpdate multiple existing ads
  • GETGet ad analytics/ad_accounts/:ad_account_id/ads/analytics?pin_ids=string&start_date=2024-01-01&end_date=2024-01-01&ad_ids=string&columns=SPEND_IN_MICRO_DOLLAR&granularity=TOTAL&click_window_days=30&engagement_window_days=30&view_window_days=1&conversion_report_time=TIME_OF_AD_ACTION&campaign_ids=string&reporting_timezone=PINTEREST_TIME_ZONEGet 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…
  • GETGet targeting analytics for ads/ad_accounts/:ad_account_id/ads/targeting_analytics?ad_ids=string&start_date=2024-01-01&end_date=2024-01-01&targeting_types=APPTYPE&columns=SPEND_IN_MICRO_DOLLAR&granularity=TOTAL&click_window_days=0&engagement_window_days=0&view_window_days=0&conversion_report_time=TIME_OF_AD_ACTION&attribution_types=INDIVIDUAL&reporting_timezone=PINTEREST_TIME_ZONE&sort_columns=string&sort_ascending=trueGet targeting analytics for one or more ads. For the requested ad(s) and metrics, the response will include the requested metric information (e.g.…
  • GETGet ad/ad_accounts/:ad_account_id/ads/:ad_idGet 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…
  • GETFetch ad preview records for one or more ad groups/ad_accounts/:ad_account_id/campaign_ad_preview?ad_group_ids=stringFetch ad preview records for one or more ad groups. Returns all active previews associated with the provided ad group IDs.
  • POSTCreate ad preview records for one or more ad groups/ad_accounts/:ad_account_id/campaign_ad_previewCreate 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…
  • DELETEDelete ad preview records for one or more ad groups/ad_accounts/:ad_account_id/campaign_ad_preview?ad_group_ids=stringDelete ad preview records for one or more ad groups. All ad groups are validated before deleting any records.

advanced_auction

  • POSTGet item bid options (POST)/advanced_auction/items/get?ad_account_id=stringGet 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…
  • POSTOperate on item level bid options/advanced_auction/items/submit?ad_account_id=stringThis endpoint supports multiple operations on a set of one or more bid options (bid price and bid adjustments for targeting categories) for retail catalog…

audience_insights

  • GETGet audience insights/ad_accounts/:ad_account_id/audience_insights?audience_insight_type=YOUR_TOTAL_AUDIENCEGet 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…
  • GETGet audience insights scope and type/ad_accounts/:ad_account_id/insights/audiencesGet 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…

audience_sharing

  • PATCHUpdate audience sharing between ad accounts/ad_accounts/:ad_account_id/audiences/ad_accounts/sharedFrom an ad account, share a specific audience with another ad account, or revoke access to a previously shared audience. Only the audience owner account can…
  • PATCHUpdate audience sharing from an ad account to businesses/ad_accounts/:ad_account_id/audiences/businesses/sharedFrom an ad account, share a specific audience with a business account, or revoke access to a previously shared audience. Only the audience owner account can…
  • GETList accounts with access to an audience owned by an ad account/ad_accounts/:ad_account_id/audiences/shared/accounts?audience_id=string&account_type=AD_ACCOUNT&bookmark=string&page_size=25List all ad accounts and/or businesses that have access to a specific audience. The audience must be owned by the requesting ad account.
  • GETList received audiences for a business/businesses/:business_id/audiences?order=ASCENDING&bookmark=string&page_size=25Get a list of received audiences for the given business.
  • PATCHUpdate audience sharing from a business to ad accounts/businesses/:business_id/audiences/ad_accounts/sharedFrom a business, share a specific audience with other ad account(s), or revoke access to a previously shared audience. If the business is the owner of the…
  • PATCHUpdate audience sharing between businesses/businesses/:business_id/audiences/businesses/sharedFrom a business, share a specific audience with another business account, or revoke access to a previously shared audience. Only the audience owner can share…
  • GETList accounts with access to an audience owned by a business/businesses/:business_id/audiences/shared/accounts?audience_id=string&account_type=AD_ACCOUNT&bookmark=string&page_size=25List all ad accounts and/or businesses that have access to a specific audience. The audience must either be owned by an ad account in the requesting business,…

audiences

  • GETList audiences/ad_accounts/:ad_account_id/audiences?bookmark=string&page_size=25&order=ASCENDING&ownership_type=OWNED&exclude_nca=falseGet list of audiences for the ad account.
  • POSTCreate audience/ad_accounts/:ad_account_id/audiencesCreate a new audience for the ad account.
  • GETGet audience/ad_accounts/:ad_account_id/audiences/:audience_idGet a specific audience given the audience ID.
  • PATCHUpdate audience/ad_accounts/:ad_account_id/audiences/:audience_idUpdate an existing audience for the ad account.

billing

  • GETGet ads credit discounts/ad_accounts/:ad_account_id/ads_credit/discounts?bookmark=string&page_size=25Returns the list of discounts applied to the account. This endpoint might not be available to all apps. Learn more.
  • POSTRedeem ad credits/ad_accounts/:ad_account_id/ads_credit/redeemRedeem 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.
  • GETGet download url for a billing invoice/ad_accounts/:ad_account_id/billing_invoice/:billing_invoice_id/downloadGet download url for a billing invoice.
  • GETGet billing invoices/ad_accounts/:ad_account_id/billing_invoices?bookmark=string&page_size=25&order=ASCENDING&sort=DUE_DATE&status=OPEN&document_type=INVOICE&start_due_date=2024-01-01&end_due_date=2024-01-01Get billing invoices in the advertiser account.
  • GETGet billing profiles/ad_accounts/:ad_account_id/billing_profiles?is_active=true&bookmark=string&page_size=25Get billing profiles in the advertiser account. This endpoint might not be available to all apps. Learn more.
  • GETGet Salesforce account details including bill-to information./ad_accounts/:ad_account_id/ssio/accountsGet Salesforce account details including bill-to information to be used in insertion orders process for ad_account_id. The token's user_account must either be…
  • POSTCreate insertion order through SSIO./ad_accounts/:ad_account_id/ssio/insertion_ordersCreate insertion order through SSIO for ad_account_id. The token's user_account must either be the owner of the specified ad account, or have one of the…
  • PATCHEdit insertion order through SSIO./ad_accounts/:ad_account_id/ssio/insertion_ordersEdit insertion order through SSIO for ad_account_id. The token's user_account must either be the owner of the specified ad account, or have one of the…
  • GETGet insertion order status by ad account id./ad_accounts/:ad_account_id/ssio/insertion_orders/status?bookmark=string&page_size=25Get insertion order status for ad_account_id. The token's user_account must either be the owner of the specified ad account, or have one of the necessary…
  • GETGet insertion order status by pin order id./ad_accounts/:ad_account_id/ssio/insertion_orders/:pin_order_id/statusGet insertion order status for pin_order_id. The token's user_account must either be the owner of the specified ad account, or have one of the necessary roles…
  • GETGet Salesforce order lines by ad account id./ad_accounts/:ad_account_id/ssio/order_lines?pin_order_id=string&bookmark=string&page_size=25Get Salesforce order lines for account id ad_account_id. The token's user_account must either be the owner of the specified ad account, or have one of the…

boards

  • GETList boards/boards?ad_account_id=string&privacy=ALL&bookmark=string&page_size=25Get a list of the boards owned by the "operation user_account" + group boards where this account is a collaborator Optional: Business Access: Specify an…
  • POSTCreate board/boards?ad_account_id=stringCreate 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…
  • GETGet board/boards/:board_id?ad_account_id=stringGet a board owned by the operation user_account - or a group board that has been shared with this account. * Optional: Business Access: Specify an…
  • DELETEDelete board/boards/:board_id?ad_account_id=stringDelete 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…
  • PATCHUpdate board/boards/:board_id?ad_account_id=stringUpdate a board owned by the "operating user_account". * Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the…
  • GETList Pins on board/boards/:board_id/pins?creative_types=REGULAR&ad_account_id=string&pin_metrics=false&bookmark=string&page_size=25Get 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. Optional: Business…
  • GETList board sections/boards/:board_id/sections?ad_account_id=string&bookmark=string&page_size=25Get 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:…
  • POSTCreate board section/boards/:board_id/sections?ad_account_id=stringCreate 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…
  • DELETEDelete board section/boards/:board_id/sections/:section_id?ad_account_id=stringDelete 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…
  • PATCHUpdate board section/boards/:board_id/sections/:section_id?ad_account_id=stringUpdate 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…
  • GETList Pins on board section/boards/:board_id/sections/:section_id/pins?ad_account_id=string&bookmark=string&page_size=25Get 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.…

bulk

  • POSTGet advertiser entities in bulk/ad_accounts/:ad_account_id/bulk/downloadCreate an asynchronous report that may include information on campaigns, ad groups, product groups, ads, keywords, schedules,and/or labels; can filter by…
  • POSTCreate/update ad entities in bulk/ad_accounts/:ad_account_id/bulk/upsertEither create or update any combination of campaigns, ad groups, product groups, ads, keywords, schedules, or labels. Note that this request will be processed…
  • GETDownload advertiser entities in bulk/ad_accounts/:ad_account_id/bulk/:bulk_request_id?include_details=falseGet 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…

campaigns

  • GETList campaigns/ad_accounts/:ad_account_id/campaigns?bookmark=string&page_size=25&order=ASCENDING&campaign_ids=string&entity_statuses=ACTIVE,PAUSEDGet a list of the campaigns in the specified ad_account_id, filtered by the specified options. The token's user_account must either be the Owner of the…
  • POSTCreate campaigns/ad_accounts/:ad_account_id/campaignsCreate 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…
  • PATCHUpdate campaigns/ad_accounts/:ad_account_id/campaignsUpdate multiple ad campaigns based on campaign_ids. Note: The values for lifetime_spend_cap and daily_spend_cap are microcurrency amounts based on the…
  • GETGet campaign analytics/ad_accounts/:ad_account_id/campaigns/analytics?start_date=2024-01-01&end_date=2024-01-01&campaign_ids=string&columns=SPEND_IN_MICRO_DOLLAR&granularity=TOTAL&click_window_days=30&engagement_window_days=30&view_window_days=1&conversion_report_time=TIME_OF_AD_ACTION&aggregate_report_rows=false&reporting_timezone=PINTEREST_TIME_ZONEGet analytics for the specified campaigns in the specified ad_account_id, filtered by the specified options. The token's user_account must either be the Owner…
  • POSTGet campaign delivery estimates/ad_accounts/:ad_account_id/campaigns/delivery_estimatesGet delivery estimates for an ads campaign This endpoint is currently in beta and is not available to all apps Learn more.
  • GETGet targeting analytics for campaigns/ad_accounts/:ad_account_id/campaigns/targeting_analytics?campaign_ids=string&start_date=2024-01-01&end_date=2024-01-01&targeting_types=APPTYPE&columns=SPEND_IN_MICRO_DOLLAR&granularity=TOTAL&click_window_days=30&engagement_window_days=30&view_window_days=1&conversion_report_time=TIME_OF_AD_ACTION&attribution_types=INDIVIDUAL&reporting_timezone=PINTEREST_TIME_ZONEGet targeting analytics for one or more campaigns. For the requested account and metrics, the response will include the requested metric information (e.g.…
  • GETGet campaign/ad_accounts/:ad_account_id/campaigns/:campaign_idGet a specific campaign given the campaign ID.
  • GETGet pins analytics/ad_accounts/:ad_account_id/pins/analytics?campaign_id=string&pin_ids=string&start_date=2024-01-01&end_date=2024-01-01&columns=SPEND_IN_MICRO_DOLLAR&granularity=TOTAL&click_window_days=30&engagement_window_days=30&view_window_days=1&conversion_report_time=TIME_OF_AD_ACTIONGet analytics for the pins given a campaign and pins in the specified ad_account_id, filtered by the specified options. The token's user_account must either…

catalog_feeds

  • GETList feeds/catalogs/feeds?catalog_id=string&ad_account_id=string&bookmark=string&page_size=25Fetch feeds owned by the "operation user_account". By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an…
  • POSTCreate feed/catalogs/feeds?ad_account_id=stringCreate a new feed owned by the "operation user_account". By default, the "operation user_account" is the token user_account. Please, be aware that…
  • GETGet feed/catalogs/feeds/:feed_id?ad_account_id=stringGet a single feed owned by the "operation user_account". By default, the "operation user_account" is the token user_account. Optional: Business Access:…
  • DELETEDelete feed/catalogs/feeds/:feed_id?ad_account_id=stringDelete a feed owned by the "operation user_account". By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an…
  • PATCHUpdate feed/catalogs/feeds/:feed_id?ad_account_id=stringUpdate a feed owned by the "operation user_account". By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an…
  • POSTIngest feed items/catalogs/feeds/:feed_id/ingest?ad_account_id=stringIngest 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…
  • GETList feed processing results/catalogs/feeds/:feed_id/processing_results?ad_account_id=string&bookmark=string&page_size=25Fetch 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…
  • GETList item issues/catalogs/processing_results/:processing_result_id/item_issues?item_numbers=0&item_validation_issue=AD_IMAGE_0_LINK_LENGTH_TOO_LONG&ad_account_id=string&bookmark=string&page_size=25List 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…

catalog_items

  • POSTGet catalogs items (POST)/catalogs/items?ad_account_id=stringGet the items of the catalog owned by the "operation user_account". See detailed documentation here. By default, the "operation user_account" is the token…
  • POSTOperate on item batch/catalogs/items/batch?ad_account_id=stringThis endpoint supports multiple operations on a set of one or more catalog items owned by the "operation user_account". See detailed documentation here. By…
  • GETGet item batch status/catalogs/items/batch/:batch_id?ad_account_id=stringGet a single catalogs items batch owned by the "operating user_account". See detailed documentation here. By default, the "operation user_account" is the…

catalog_product_groups

  • GETList product groups/catalogs/product_groups?id=0&feed_id=string&catalog_id=string&ad_account_id=string&bookmark=string&page_size=25Get a list of product groups for a given Catalogs Feed Id owned by the "operation user_account". By default, the "operation user_account" is the token…
  • POSTCreate product group/catalogs/product_groups?ad_account_id=stringCreate product group to use in Catalogs owned by the "operation user_account". By default, the "operation user_account" is the token user_account. Optional:…
  • POSTCreate product groups/catalogs/product_groups/multiple?ad_account_id=stringCreate product group to use in Catalogs owned by the "operation user_account". By default, the "operation user_account" is the token user_account. Optional:…
  • DELETEDelete product groups/catalogs/product_groups/multiple?id=0&ad_account_id=stringDelete product groups owned by the "operation user_account". By default, the "operation user_account" is the token user_account. Optional: Business Access:…
  • GETGet product group/catalogs/product_groups/:product_group_id?ad_account_id=stringGet a single product group for a given Catalogs Product Group Id owned by the "operation user_account". By default, the "operation user_account" is the token…
  • DELETEDelete product group/catalogs/product_groups/:product_group_id?ad_account_id=stringDelete a product group owned by the "operation user_account" from being in use in Catalogs. By default, the "operation user_account" is the token…
  • PATCHUpdate single product group/catalogs/product_groups/:product_group_id?ad_account_id=stringUpdate product group owned by the "operation user_account" to use in Catalogs. By default, the "operation user_account" is the token user_account. Optional:…
  • GETGet product counts/catalogs/product_groups/:product_group_id/product_counts?ad_account_id=stringGet a product counts for a given Catalogs Product Group owned by the "operation user_account". By default, the "operation user_account" is the token…
  • GETList products by product group/catalogs/product_groups/:product_group_id/products?ad_account_id=string&pin_metrics=false&bookmark=string&page_size=25Get a list of product pins for a given Catalogs Product Group Id owned by the "operation user_account". By default, the "operation user_account" is the token…
  • POSTList products by filter/catalogs/products/get_by_product_group_filters?bookmark=string&page_size=25&ad_account_id=string&pin_metrics=falseList products Pins owned by the "operation user_account" that meet the criteria specified in the Catalogs Product Group Filter given in the request. This…

catalog_reports

  • GETGet catalogs report/catalogs/reports?ad_account_id=string&token=stringThis returns a URL to a report given a token returned from Build catalogs report. You can use the URL to download the report. By default, the "operation…
  • POSTBuild catalogs report/catalogs/reports?ad_account_id=stringAsync request to create a report of the catalog owned by the "operation user_account". This endpoint generates a report upon receiving the first approved…
  • GETList report stats/catalogs/reports/stats?ad_account_id=string&parameters={"catalog_type":"RETAIL","report":{"feed_id":"string","processing_result_id":"string","report_type":"FEED_INGESTION_ISSUES"}}&bookmark=string&page_size=25List aggregated numbers of issues for a catalog owned by the "operation user_account". By default, the "operation user_account" is the token user_account.…

catalog_supplemental

  • POSTOperate on local inventory item batch/catalogs/:catalog_id/local_inventory_items/batch?ad_account_id=stringManaging local inventory information in batches supporting CREATE, UPDATE, UPSERT, DELETE operations. Up to 1000 items per request to match catalogs/items.…
  • POSTGet local inventory items (POST)/catalogs/:catalog_id/local_inventory_items/query?ad_account_id=stringGet 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…
  • GETList local stores/catalogs/:catalog_id/local_stores?ids=string&ad_account_id=string&bookmark=string&page_size=25Fetch local stores for a catalog owned by the "operation user_account". By default, the "operation user_account" is the token user_account. Supports optional…
  • POSTCreate local stores/catalogs/:catalog_id/local_stores?ad_account_id=stringCreate a local store for a catalog owned by the "operation user_account". By default, the "operation user_account" is the token user_account. Supports…
  • DELETEDelete local stores/catalogs/:catalog_id/local_stores?ids=string&ad_account_id=stringDelete multiple local stores for a catalog owned by the "operation user_account". By default, the "operation user_account" is the token user_account. Supports…
  • PATCHUpdate local stores/catalogs/:catalog_id/local_stores?ad_account_id=stringUpdate a local store for a catalog owned by the "operation user_account". By default, the "operation user_account" is the token user_account. Supports…
  • GETGet supplemental items batch status/catalogs/:catalog_id/supplemental_items/batch/:batch_id?ad_account_id=stringFetch the status and results of a supplemental items batch operation. By default, the "operation user_account" is the token user_account. Optional: Business…

catalogs

  • GETList catalogs/catalogs?ad_account_id=string&bookmark=string&page_size=25Fetch catalogs owned by the "operation user_account". By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify…
  • POSTCreate catalog/catalogs?ad_account_id=stringCreate a new catalog owned by the "operation user_account". By default, the "operation user_account" is the token user_account. Optional: Business Access:…
  • GETList available filter values/catalogs/available_filter_values?catalog_id=string&feed_id=string&country=AD&language=af-ZA&ad_account_id=stringGet the available filter attributes and values associated with a given feed or catalog owned by the "operation user_account". By default, the "operation…

conversion_deletion_requests

  • GETList conversion deletion requests/ad_accounts/:ad_account_id/conversion_deletion_requests?bookmark=string&page_size=25&order=ASCENDINGThis 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.
  • POSTCreate a conversion deletion request/ad_accounts/:ad_account_id/conversion_deletion_requestsThis 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…
  • GETGet a single conversion deletion request/ad_accounts/:ad_account_id/conversion_deletion_requests/:request_idThis 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.
  • DELETEDelete a conversion deletion request/ad_accounts/:ad_account_id/conversion_deletion_requests/:request_idThis 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…

conversion_eqs

  • GETGet event quality score (EQS)/ad_accounts/:ad_account_id/conversion_eqs?lookback_period=1d&source_platform=WEB&ingestion_source=TAGGet the Event Quality Score (EQS) of your conversion signals. Event Quality Score indicates how effective the customer information and event insights…

conversion_events

  • POSTSend conversions/ad_accounts/:ad_account_id/events?test=trueThe Pinterest API offers advertisers a way to send Pinterest their conversion information (including web conversions, in-app conversions, or even offline…

conversion_tags

  • GETList conversion tags/ad_accounts/:ad_account_id/conversion_tags?filter_deleted=falseList conversion tags associated with an ad account.
  • POSTCreate conversion tag/ad_accounts/:ad_account_id/conversion_tagsCreate a conversion tag, also known as Pinterest tag, with the option to enable enhanced match. The Pinterest Tag tracks actions people take on the ad…
  • GETGet Ocpm eligible conversion tags/ad_accounts/:ad_account_id/conversion_tags/ocpm_eligibleGet Ocpm eligible conversion tag events for an ad account.
  • GETGet page visit conversion tags/ad_accounts/:ad_account_id/conversion_tags/page_visit?bookmark=string&page_size=25&order=ASCENDINGGet all page visit conversion tag events for an ad account.
  • GETGet conversion tag/ad_accounts/:ad_account_id/conversion_tags/:conversion_tag_idGet information about an existing conversion tag.

customer_list_uploads

  • POSTCreate customer list upload/ad_accounts/:ad_account_id/customer_lists/:customer_list_id/uploadsCreate 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.…
  • GETGet customer list upload/ad_accounts/:ad_account_id/customer_lists/:customer_list_id/uploads/:customer_list_upload_idGet the metadata for a given upload by its ID.
  • POSTRun customer list upload/ad_accounts/:ad_account_id/customer_lists/:customer_list_id/uploads/:customer_list_upload_id/runBegin processing a customer list upload.

customer_lists

  • GETGet customer lists/ad_accounts/:ad_account_id/customer_lists?bookmark=string&page_size=25&order=ASCENDING&exclude_nca=falseGet 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…
  • POSTCreate customer lists/ad_accounts/:ad_account_id/customer_listsCreate 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…
  • GETGet customer list/ad_accounts/:ad_account_id/customer_lists/:customer_list_idGets a specific customer list given the customer list ID.
  • PATCHUpdate customer list/ad_accounts/:ad_account_id/customer_lists/:customer_list_idAppend 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…

customer_segment

  • GETList customer segments/ad_accounts/:ad_account_id/customer_segments?bookmark=string&page_size=25&order=ASCENDING&include_sizing=false&search_query=stringGet a list of the customer segments in the specified ad_account_id.
  • POSTCreate customer segments/ad_accounts/:ad_account_id/customer_segmentsCustomer segments allow advertisers to define existing customers for Pinterest Performance+ campaigns. Customer segments are made up of audience lists.
  • PATCHUpdate customer segments/ad_accounts/:ad_account_id/customer_segmentsUpdate the customer segment given advertiser ID and customer segment ID

integrations

  • GETGet integration metadata list/integrations?bookmark=string&page_size=25Get integration metadata list. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager.
  • POSTCreate commerce integration/integrations/commerceCreate commerce integration metadata to link an external business ID with a Pinterest merchant & ad account. Note: If you're interested in joining the beta,…
  • GETGet commerce integration/integrations/commerce/:external_business_idGet commerce integration metadata associated with the given external business ID. Note: If you're interested in joining the beta, please reach out to your…
  • DELETEDelete commerce integration/integrations/commerce/:external_business_idDelete commerce integration metadata for the given external business ID. Note: If you're interested in joining the beta, please reach out to your Pinterest…
  • PATCHUpdate commerce integration/integrations/commerce/:external_business_idUpdate commerce integration metadata for the given external business ID. Note: If you're interested in joining the beta, please reach out to your Pinterest…
  • POSTReceives batched logs from integration applications./integrations/logsThis endpoint receives batched logs from integration applications on partner platforms. Note: If you're interested in joining the beta, please reach out to…
  • GETGet integration metadata/integrations/:idGet integration metadata by ID. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager.

keywords

  • GETGet keywords/ad_accounts/:ad_account_id/keywords?campaign_id=string&ad_group_id=string&ad_group_ids=string&match_types=BROAD&bookmark=string&page_size=25Get 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…
  • POSTCreate keywords/ad_accounts/:ad_account_id/keywordsCreate keywords for the following entity types (advertiser, campaign, ad group, or ad). For more information, see Keyword targeting. Notes: Advertisers and…
  • PATCHUpdate keywords/ad_accounts/:ad_account_id/keywordsUpdate one or more keywords' bid and archived fields. Archiving a keyword effectively deletes it - keywords no longer receive metrics and are no longer…
  • GETGet country's keyword metrics/ad_accounts/:ad_account_id/keywords/metrics?country_code=string&keywords=stringSee keyword metrics for a specified country, aggregated across all of Pinterest. (Definitions are available from the "Get delivery metrics definitions" API…
  • GETList trending keywords/trends/keywords/:region/top/:trend_type?interests=animals&genders=male&ages=18-24&include_keywords=recipes,dessert&normalize_against_group=false&limit=50&include_demographics=falseGet the top trending search keywords among the Pinterest user audience. Trending keywords can be used to inform ad targeting, budget strategy, and creative…

labels

  • GETList labels/ad_accounts/:ad_account_id/labels?campaign_ids=string&label_ids=string&entity_statuses=ACTIVE&label_types=BRAND,CUSTOM&bookmark=string&page_size=25Closed beta 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…
  • POSTCreate labels/ad_accounts/:ad_account_id/labelsClosed beta Apply one or more labels to a campaign. Future releases may support labels for other entities. Currently, you can apply brand and custom labels.…
  • PATCHUpdate labels/ad_accounts/:ad_account_id/labelsClosed beta Change the properties of one or more labels.
  • POSTApply label to entity/ad_accounts/:ad_account_id/labels/:label_id/applyClosed beta Apply a label to one or more campaigns. Future releases may support labels for other entities in addition to campaigns. Currently, you can apply…
  • POSTRemove label from entities/ad_accounts/:ad_account_id/labels/:label_id/removeClosed beta Remove a label from one or more entities.

lead_ads

  • GETGet lead ads subscriptions/ad_accounts/:ad_account_id/leads/subscriptions?bookmark=string&page_size=25Get the advertiser's list of lead ads subscriptions. Only requests for the OWNER or ADMIN of the ad_account will be allowed.
  • POSTCreate lead ads subscription/ad_accounts/:ad_account_id/leads/subscriptionsCreate a lead ads webhook subscription. Subscriptions allow Pinterest to deliver lead data from Ads Manager directly to the subscriber. Subscriptions can…
  • GETGet lead ads subscription by ID/ad_accounts/:ad_account_id/leads/subscriptions/:subscription_idGet an existing lead ads webhook subscription by ID. Only requests for the OWNER or ADMIN of the ad_account will be allowed.'
  • DELETEDelete lead ads subscription/ad_accounts/:ad_account_id/leads/subscriptions/:subscription_idDelete an existing lead ads webhook subscription by ID. Only requests for the OWNER or ADMIN of the ad_account will be allowed.'

lead_forms

  • GETList lead forms/ad_accounts/:ad_account_id/lead_forms?bookmark=string&page_size=25&order=ASCENDINGThis 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.…
  • POSTCreate lead forms/ad_accounts/:ad_account_id/lead_formsThis 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.…
  • PATCHUpdate lead forms/ad_accounts/:ad_account_id/lead_formsThis 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.…
  • GETGet lead form by id/ad_accounts/:ad_account_id/lead_forms/:lead_form_idThis 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.…
  • POSTCreate lead form test data/ad_accounts/:ad_account_id/lead_forms/:lead_form_id/testCreate lead form test data based on the list of answers provided as part of the body. List of answers should follow the questions creation order.

leads_export

  • POSTCreate a request to export leads collected from a lead ad/ad_accounts/:ad_account_id/leads_exportThis 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.…
  • GETGet the lead export from the lead export create call/ad_accounts/:ad_account_id/leads_export/:leads_export_idThis 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.…

media

  • GETList media uploads/media?bookmark=string&page_size=25List media uploads filtered by given parameters. Learn more about video Pin creation.
  • POSTRegister media upload/mediaRegister 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…
  • GETGet media upload details/media/:media_idGet details for a registered media upload, including its current status. Learn more about video Pin creation.

msot_events

  • POSTSend Measurement Source Of Truth (MSOT) attributed conversion events/ad_accounts/:ad_account_id/msot/eventsThis 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.…

notification

  • POSTReceive notifications from external partners./notificationsUsed by third-party partners to send notifications to Pinterest. These notifications could be specific for your use-case or generic notification that are…

oauth

  • POSTGenerate OAuth access token for conversion API/oauth/conversion_tokenGenerate a new and long-lived OAuth access token dedicated for sending conversions using a valid access token.
  • POSTGenerate OAuth access token/oauth/tokenGenerate a new OAuth access token using an authorization code; or refresh an existing one using a continuous refresh token. Follow the complete steps for…
  • POSTRevoke a token/oauth/token/revokeRevokes an access or refresh token. Only tokens issued for system users are currently supported. Revoked tokens become immediately invalid and unusable.

order_lines

  • GETGet order lines./ad_accounts/:ad_account_id/order_lines?bookmark=string&page_size=25&order=ASCENDINGList existing order lines associated with an ad account.
  • GETGet order line/ad_accounts/:ad_account_id/order_lines/:order_line_idGet a specific existing order line associated with an ad account.

pins

  • GETList Pins/pins?pin_filter=exclude_native&pin_metrics=false&include_protected_pins=false&pin_type=PRIVATE&creative_types=REGULAR&ad_account_id=string&domain=string&domains=string&include_product_tag_obj=true&bookmark=string&page_size=25Get 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…
  • POSTCreate Pin/pins?ad_account_id=stringCreate 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)…
  • GETGet multiple Pin analytics/pins/analytics?pin_ids=string&start_date=2024-01-01&end_date=2024-01-01&app_types=ALL&metric_types=IMPRESSION&ad_account_id=stringThis 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…
  • GETGet Pin/pins/:pin_id?ad_account_id=string&pin_metrics=falseGet 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…
  • DELETEDelete Pin/pins/:pin_id?ad_account_id=stringDelete 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…
  • PATCHUpdate Pin/pins/:pin_id?ad_account_id=stringUpdate a pin owned by the "operating user_account". By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an…
  • GETGet Pin analytics/pins/:pin_id/analytics?start_date=2024-01-01&end_date=2024-01-01&app_types=ALL&metric_types=IMPRESSION&split_field=NO_SPLIT&ad_account_id=stringGet analytics for a Pin owned by the "operation user_account" - or on a group board that has been shared with this account. By default, the "operation…
  • POSTSave Pin/pins/:pin_id/save?ad_account_id=stringSave 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:…

product_group_promotions

  • GETGet product group promotions/ad_accounts/:ad_account_id/product_group_promotions?bookmark=string&page_size=25&order=ASCENDING&product_group_promotion_ids=string&entity_statuses=ACTIVE,PAUSED&ad_group_id=stringList existing product group promotions associated with an ad account. Include either ad_group_id or product_group_promotion_ids in your request. Note:…
  • POSTCreate product group promotions/ad_accounts/:ad_account_id/product_group_promotionsAdd 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.')
  • PATCHUpdate product group promotions/ad_accounts/:ad_account_id/product_group_promotionsUpdate multiple existing Product Group Promotions (by product_group_id)
  • GETGet a product group promotion by id/ad_accounts/:ad_account_id/product_group_promotions/:product_group_promotion_idGet a product group promotion by id
  • GETGet product group analytics/ad_accounts/:ad_account_id/product_groups/analytics?start_date=2024-01-01&end_date=2024-01-01&product_group_ids=string&columns=SPEND_IN_MICRO_DOLLAR&granularity=TOTAL&click_window_days=30&engagement_window_days=30&view_window_days=1&conversion_report_time=TIME_OF_AD_ACTION&reporting_timezone=PINTEREST_TIME_ZONEGet analytics for the specified product groups in the specified ad_account_id, filtered by the specified options. The token's user_account must either be the…

product_tags

  • GETGet product tags for pin/pins/:pin_id/product_tagsRetrieve all product tags for a pin. Returns an empty array if the pin has no product tags.
  • POSTAdd product tags to pin/pins/:pin_id/product_tagsAdd product tags to a pin. Product tags allow you to tag product pins onto a hero pin. Maximum 24 product tags can be added in a single request. Duplicate…
  • POSTDelete product tags from pin/pins/:pin_id/product_tags/bulk-deleteDelete product tags from a pin. If a product tag is not found on the pin, it is treated as a no-op success.

promotions

  • GETGet promotions/ad_accounts/:ad_account_id/promotions?bookmark=string&page_size=25&order=ASCENDINGGets 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…
  • POSTCreate promotions/ad_accounts/:ad_account_id/promotionsCreate multiple new promotions.
  • PATCHUpdate promotions/ad_accounts/:ad_account_id/promotionsUpdate multiple promotions.
  • GETGet promotion by id/ad_accounts/:ad_account_id/promotions/:promotion_idGet a promotion by its Pinterest-specific id. It must be associated with the provided ad account id.
  • DELETEDelete promotion by id/ad_accounts/:ad_account_id/promotions/:promotion_idDelete a promotion within Pinterest.

resources

  • GETGet ad accounts countries/resources/ad_account_countriesGet Ad Accounts countries
  • GETGet available metrics' definitions/resources/delivery_metrics?report_type=SYNCGet the definitions for ads and organic metrics available across both synchronous and asynchronous report endpoints. The display_name attribute will match how…
  • GETGet lead form questions/resources/lead_form_questionsGet 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.
  • GETGet metrics ready state/resources/metrics_ready_state?date=stringLearn whether conversion or non-conversion metrics are finalized and ready to query.
  • GETGet interest details/resources/targeting/interests/:interest_idGet details of a specific interest given interest ID. Click here for a spreadsheet listing interests and their IDs.
  • GETGet targeting options/resources/targeting/:targeting_type?ad_account_id=string&client_id=string&oauth_signature=string&timestamp=stringYou can use targeting values in ads placement to define your intended audience. Targeting metrics are organized around targeting specifications. For more…

search

  • GETSearch user's boards/search/boards?ad_account_id=string&query=string&bookmark=string&page_size=25Search for boards for the "operation user_account". This includes boards of all board types. By default, the "operation user_account" is the token…
  • GETSearch pins by a given search term/search/partner/pins?term=string&country_code=string&bookmark=string&locale=string&limit=10This endpoint is currently in beta and not available to all apps. Learn more. Get the top 10 Pins by a given search term.
  • GETSearch user's Pins/search/pins?ad_account_id=string&query=string&bookmark=stringSearch for pins for the "operation user_account". By default, the "operation user_account" is the token user_account. If using Business Access: Specify an…

targeting_template

  • GETList targeting templates/ad_accounts/:ad_account_id/targeting_templates?bookmark=string&page_size=25&order=ASCENDING&include_sizing=false&search_query=stringGet a list of the targeting templates in the specified ad_account_id
  • POSTCreate targeting templates/ad_accounts/:ad_account_id/targeting_templatesTargeting templates allow advertisers to save a set of targeting details including audience lists, keywords & interest, demographics, and placements to use…
  • PATCHUpdate targeting templates/ad_accounts/:ad_account_id/targeting_templatesUpdate the targeting template given advertiser ID and targeting template ID

terms

  • GETList related terms/terms/related?terms=stringGet a list of terms logically related to each input term. Example: the term 'workout' would list related terms like 'one song workout', 'yoga workout',…
  • GETList suggested terms/terms/suggested?term=string&limit=4Get popular search terms that begin with your input term. Example: 'sport' would return popular terms like 'sports bar' and 'sportswear', but not 'motor…

terms_of_service

  • GETGet terms of service/ad_accounts/:ad_account_id/terms_of_service?include_html=false&tos_type=stringGet the text of the terms of service and see whether the advertiser has accepted the terms of service.

trends

  • GETReturns editorial articles for a given region/trends/editorial_articles?region=USGet a list of published editorial articles. Translations of the editorials will be provided if available; otherwise, the default language will be English.
  • GETGet product category details/trends/product_categories/details?product_categories=ACCENT_TABLES&region=US&lookback_window=90&engagement_type=ENGAGEMENTEnables advertisers to retrieve demographic information, related pins, and trend lines for specified product categories
  • GETGet a list of growing Shopping Product Categories/trends/product_categories/trending?region=US&verticals=FASHION&ages=18-24&genders=MALE&engagement_type=ENGAGEMENTGet a list of growing Shopping Product Categories in ranked order allowing filtering by engagement type, vertical, age, and gender.
  • GETGet featured topics/trends/topics/featured?interest=ALL&region=USEnables advertisers to pull top five trending topics by interest and market, at full parity with the Pinterest Trends UI.

user_account

  • GETGet user account/user_account?ad_account_id=stringGet account information for the "operation user_account" By default, the "operation user_account" is the token user_account. [Understanding Business Access]:…
  • GETGet user account analytics/user_account/analytics?start_date=2024-01-01&end_date=2024-01-01&from_claimed_content=BOTH&pin_format=ALL&app_types=ALL&content_type=ALL&source=ALL&metric_types=ENGAGEMENT&split_field=NO_SPLIT&ad_account_id=stringGet analytics for the "operation user_account" By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an…
  • GETGet user account top pins analytics/user_account/analytics/top_pins?start_date=2024-01-01&end_date=2024-01-01&sort_by=ENGAGEMENT&from_claimed_content=BOTH&pin_format=ALL&app_types=ALL&content_type=ALL&source=ALL&metric_types=ENGAGEMENT&num_of_pins=10&created_in_last_n_days=30&ad_account_id=stringGets analytics data about a user's top pins (limited to the top 50). By default, the "operation user_account" is the token user_account. Optional: Business…
  • GETGet user account top video pins analytics/user_account/analytics/top_video_pins?start_date=2024-01-01&end_date=2024-01-01&sort_by=SAVE&from_claimed_content=BOTH&pin_format=ALL&app_types=ALL&content_type=ALL&source=ALL&metric_types=IMPRESSION&num_of_pins=10&created_in_last_n_days=30&ad_account_id=stringGets analytics data about a user's top video pins (limited to the top 50). By default, the "operation user_account" is the token user_account. Optional:…
  • GETList linked businesses/user_account/businessesGet a list of your linked business accounts.
  • GETList followers/user_account/followers?bookmark=string&page_size=25Get a list of your followers.
  • GETList following/user_account/following?ad_account_id=string&explicit_following=false&feed_type=CREATOR_ONLY&bookmark=string&page_size=25Get a list of who a certain user follows.
  • GETList following boards/user_account/following/boards?ad_account_id=string&explicit_following=false&bookmark=string&page_size=25Get a list of the boards a user follows. The request returns a board summary object array.
  • POSTFollow user/user_account/following/:usernameThis 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.
  • GETGet user websites/user_account/websites?bookmark=string&page_size=25Get user websites, claimed or not
  • POSTVerify website/user_account/websites?ad_account_id=stringVerify a website as a signed-in user.
  • DELETEUnverify website/user_account/websites?website=stringUnverify a website verified by the signed-in user.
  • GETGet user verification code for website claiming/user_account/websites/verification?ad_account_id=stringGet verification code for user to install on the website to claim it.
  • GETList following interests/users/:username/interests/follow?bookmark=string&page_size=25Get a list of a user's following interests in one place.

conversions

  • GETGet advertiser defined events/ad_accounts/:ad_account_id/advertiser_defined_eventsGet advertiser defined events for the given ad account.
  • POSTCreate advertiser defined events/ad_accounts/:ad_account_id/advertiser_defined_eventsMap advertiser defined events to standard events for the given ad account.
  • DELETEDelete advertiser defined events/ad_accounts/:ad_account_id/advertiser_defined_events?event_names=stringUntrack advertiser defined events for the given ad account.
  • PATCHUpdate advertiser defined events/ad_accounts/:ad_account_id/advertiser_defined_eventsUpdate advertiser defined event names or mappings for the given ad account.

schedules

  • GETGet Schedules/ad_accounts/:ad_account_id/schedules?bookmark=string&page_size=25&order=ASCENDING&schedule_statuses=ACTIVE&schedule_type=CAMPAIGN_BUDGET_CHANGE&entity_ids=stringGet schedules for a specific advertiser
  • POSTCreate schedules/ad_accounts/:ad_account_id/schedulesBatch create schedules
  • PATCHUpdate schedules/ad_accounts/:ad_account_id/schedulesUpdate one or more schedules

business_access_relationships

  • POSTCreate a Brand Account/business_access/business_hierarchy/:business_hierarchy_id/brand_accountsCreate a Brand Account that will be a child business of a business hierarchy. Request must contain name, username, and country.
  • PATCHUpdate a Brand Account/business_access/business_hierarchy/:business_hierarchy_id/brand_accounts/:brand_account_idUpdate an existing Brand Account
  • GETList business employers for user/businesses/employers?assets_summary=true&bookmark=string&page_size=25Get all of the viewing user's business employers.
  • GETGet business members/businesses/:business_id/members?fetch_system_users=false&assets_summary=false&business_roles=BIZ_ADMIN&member_ids=string&start_index=0&bookmark=string&page_size=25Get 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
  • DELETETerminate business memberships/businesses/:business_id/membersTerminate memberships between the specified members and your business.
  • PATCHUpdate member's business role/businesses/:business_id/membersUpdate a member's business role within the business.
  • GETGet business partners/businesses/:business_id/partners?assets_summary=false&partner_type=INTERNAL&partner_ids=string&start_index=0&sort_ascending=true&bookmark=string&page_size=25Get all partners of the specified business. If the assets_summary=TRUE and: partner_type=INTERNAL, the business assets returned are your business assets the…
  • DELETETerminate business partnerships/businesses/:business_id/partnersTerminate partnerships between the specified partners and your business. Note: You may only batch terminate partners of the same partner type.
  • PATCHUpdate a system user information./businesses/:business_id/system_users/:system_user_idUpdate a system user information such as name.

business_access_invite

  • PATCHAccept or decline an invite/request/businesses/invitesAccept or decline invites or requests.
  • GETGet invites/requests/businesses/:business_id/invites?is_member=true&invite_status=PENDING&invite_type=MEMBER_INVITE&bookmark=string&page_size=25Get the membership/partnership invites and/or requests for the authorized user.
  • POSTCreate invites or requests/businesses/:business_id/invitesCreate batch invites or requests. Can create batch invites or requests as described below. Invite members to join the business. This would required specifying…
  • DELETECancel invites/requests/businesses/:business_id/invitesCancel membership/partnership invites and/or requests.
  • POSTUpdate invite/request with an asset permission/businesses/:business_id/invites/assets/accessAssign asset permissions information to an existing invite/request. Can be used to: Request access to a partner's asset. Note: This is only for when no…
  • POSTCreate a request to access an existing partner's assets./businesses/:business_id/requests/assets/accessCreate 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…

business_access_assets

  • POSTCreate a new asset group./businesses/:business_id/asset_groupsCreate a new asset group with the specified parameters. An asset group is a custom group of assets based on how you would like to manage your accounts.
  • DELETEDelete asset groups./businesses/:business_id/asset_groupsDelete a batch of asset groups.
  • PATCHUpdate asset groups./businesses/:business_id/asset_groupsUpdate a batch of asset groups with the specified parameters.
  • GETList business assets/businesses/:business_id/assets?permissions=ADMIN&child_asset_id=string&asset_group_id=string&asset_type=AD_ACCOUNT&start_index=0&bookmark=string&page_size=25Get all the assets the requesting business has access to. This includes assets the business owns and assets the business has access to through partnerships.
  • GETGet members with access to asset/businesses/:business_id/assets/:asset_id/members?start_index=0&fetch_system_users=false&bookmark=string&page_size=25Get all the members the requesting business has granted access to on the given asset.
  • GETGet partners with access to asset/businesses/:business_id/assets/:asset_id/partners?start_index=0&bookmark=string&page_size=25Get 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…
  • DELETEDelete member access to asset/businesses/:business_id/members/assets/accessTerminate multiple members' access to an asset.
  • PATCHAssign/Update member asset permissions/businesses/:business_id/members/assets/accessGrant multiple members access to assets and/or update multiple member's exisiting permissions to an asset. Note: Not all listed permissions are applicable to…
  • GETGet assets assigned to a member/businesses/:business_id/members/:member_id/assets?asset_type=AD_ACCOUNT&start_index=0&sort_by=NAME&sort_ascending=true&search_by=NAME&search_value=string&asset_permission_type=AGGREGATED_PERMISSION&ad_account_statuses=ACTIVE&bookmark=string&page_size=25Get assets on which you assigned asset permissions to the given member. Can be used to: get all assets, regardless of asset type or get assets of one asset…
  • DELETEDelete partner access to asset/businesses/:business_id/partners/assetsTerminate multiple partners' access to an asset. If partner_type=INTERNAL: You will terminate a partner's asset access to your business assets.…
  • PATCHAssign/Update partner asset permissions/businesses/:business_id/partners/assetsGrant multiple partners access to assets and/or update multiple partner's exisiting permissions to an asset. If your partner already had permissions on the…
  • GETGet assets assigned to a partner or assets assigned by a partner/businesses/:business_id/partners/:partner_id/assets?partner_type=INTERNAL&asset_type=AD_ACCOUNT&start_index=0&sort_by=NAME&sort_ascending=true&search_by=NAME&search_value=string&bookmark=string&page_size=25Can 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:…

API details

Base URL
https://api.pinterest.com/v5
Authentication
OAuth 2.0 (authorization code flow) with 19 scopes
OAuth 2.0 (client credentials flow) with 19 scopes
A bearer token in the Authorization header
HTTP Basic authentication (username and password)
Operations
266 operations on 189 pathsGET 138POST 74PATCH 33DELETE 21
Main resources
ad_accounts 14user_account 14ad_groups 13business_access_assets 12billing 11boards 11ads 10catalog_product_groups 10business_access_relationships 9campaigns 8
Response formats
application/json
Description format
OpenAPI 3.0.3, API version 5.28.0

How to test the Pinterest REST API in Swastik Codes

  1. Open the APISelect “Fork & run in Swastik Codes” on this page. Sign in or create a free account if asked.
  2. Fork it into your workspaceChoose a workspace. You get your own copy of the Pinterest REST API collection, without the publisher's secrets.
  3. Add your credentialsThis API uses OAuth 2.0 (authorization code flow) with 19 scopes. Add yours in the collection's variables or an environment; the requests already reference it.
  4. Send a requestPick an endpoint, for example “List ad accounts” (GET /ad_accounts?include_shared_accounts=true&bookmark=string&page_size=25), and press Send. Check the response, add tests and run the whole collection with the runner.

Frequently asked questions

What is the Pinterest REST API?

Pinterest's REST API It is listed under Social and has 266 endpoints.

Who publishes the Pinterest REST API?

It is listed from Pinterest's public API description (an OpenAPI document), not published by Pinterest on Swastik Codes. Anyone who controls pinterest.com can claim the profile by adding a DNS TXT record.

What is the base URL of the Pinterest REST API?

Requests go to https://api.pinterest.com/v5. Endpoint paths are added to this base URL.

How do I authenticate with the Pinterest REST API?

It accepts 4 methods: OAuth 2.0 (authorization code flow) with 19 scopes; OAuth 2.0 (client credentials flow) with 19 scopes; A bearer token in the Authorization header; HTTP Basic authentication (username and password).

How many endpoints does the Pinterest REST API have?

266 operations on 189 paths (138 GET, 74 POST, 33 PATCH, 21 DELETE). The largest groups are ad_accounts, user_account, ad_groups, business_access_assets.

Is forking the Pinterest REST API free?

Yes. Forking copies the collection into your workspace for free. It has been starred 0 times and forked 0 times.

Suggest an API

Tell us which public API is missing. We check it, then add it here with its endpoints when it has an OpenAPI (Swagger) description.