Get customers
Answer customers
Work for you
Reach people
Give agents tools
Run and ship
Pinterest pins, boards, ads, catalogs, and analytics
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](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Campaign
10 fields
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"). <p/> * The token's user_account must either be the Owner of the specified ad account, or have one of the ne
12 fields
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
1 field
Get an ad account
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](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts).
3 fields
[Restricted](/docs/getting-started/using-beta-and-restricted-features/) 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.
2 fields
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,
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. - The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles grante
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.
5 fields
[Restricted](/docs/getting-started/using-beta-and-restricted-features/) 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.
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.
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. - The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to t
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.
Gets all Templates associated with an ad account ID.
4 fields
Get Ad Accounts countries
Â
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](/docs/api-features/analytics-overview/) and [Ads Analytics](/docs/api-features/ads-reporting/) for more information.
Get details of a specific interest given interest ID. Click [here](https://docs.google.com/spreadsheets/d/1HxL-0Z3p2fgxis9YBP2HWC3tvPrs1hAuHDRtH-NJTIM/edit#gid=118370875) for a spreadsheet listing interests and their IDs.
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](/docs/getting-started/using-beta-and-restricted-features/).**
Learn whether conversion or non-conversion metrics are finalized and ready to query.
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 B
List all ad accounts and/or businesses that have access to a specific audience. The audience must be owned by the requesting ad account.
List 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, or it must have been shared with the requesting business. If the requesting business is not the owner of the audience, only ad accounts owned by the requesting business will be returned.
Get a list of received audiences for the given business.
From 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 share the audience. The recipient ad account(s) must be in the same [Pinterest Business Hierarchy](https://help.pinterest.com/en/business/article/create-and-manage-accounts) as the business owner of the
From 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 share the audience. The recipient business account must be in the same business hierarchy as the business owner of the ad account. This endpoint is not available to all apps. [Learn more](/docs/getting-
From 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 audience, it can share with any ad account within the same business hierarchy. - If the business is the recipient of the audience, it can share with any of its owned ad accounts. This endpoint is not a
From a business, share a specific audience with another business account, or revoke access to a previously shared audience. Only the audience owner can share the audience with other businesses, and the recipient business must be within the same business hierarchy. This endpoint is not available to all apps. [Learn more](/docs/getting-started/using-beta-and-
Delete an existing lead ads webhook subscription by ID. - Only requests for the OWNER or ADMIN of the ad_account will be allowed.'
Get an existing lead ads webhook subscription by ID. - Only requests for the OWNER or ADMIN of the ad_account will be allowed.'
Get the advertiser's list of lead ads subscriptions. Only requests for the OWNER or ADMIN of the ad_account will be allowed.
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. - Only requests for the OWNER or ADMIN of the ad_account will be allowed. - Advertisers can set up multiple integrations using ad_account_id + lead
Get 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 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): A
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, sea
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 profi
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](https://help.pinterest.com/en/business/article/campaign-structure). **Notes:** - `bid_in_micro_currency` and `budget_in_micro_currency` should be expressed in microcurrenc
Get a presigned S3 download URL for the dynamic titles review CSV. Returns 400 if titles have not been generated yet.
Get dynamic titles generation status for an ad group, including whether titles are ready for review and counts of generated and reviewed titles.
Get a presigned S3 upload URL for the dynamic titles review CSV and a request_id for submission.
Validate and process the uploaded dynamic titles review CSV. Returns validation errors if the CSV is invalid.
Get a specific ad group given the ad group ID.
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.
8 fields
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"). - The token's user_account must either be the Owner of the specified ad account, or have one of
15 fields
Update multiple existing ad groups.
Get a list of ad groups that are associated with those promotion ids
Get 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 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-ac
11 fields
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"). * The token's user_account must either be the Owner of the specified ad account, or have one of the
13 fields
Get 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 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): Ad
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](https://help.pinterest.com/en/business/article/set-up-your-campaign/). **Note:** - The values for `lifetime_spend_cap` and `daily_spend_cap` are microcurrency amounts based on the curren
Get a specific campaign given the campaign ID.
Get 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 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,
6 fields
Update multiple ad campaigns based on campaign_ids. **Note:** - The values for `lifetime_spend_cap` and `daily_spend_cap` are microcurrency amounts based on the currency field set in the advertiser's profile (e.g. USD). Microcurrency is used to track very small transactions, based on the currency set in the advertiser's profile. A microcurrency unit is 10
Get delivery estimates for an ads campaign **This endpoint is currently in beta and is not available to all apps [Learn more](/docs/new/about-beta-access/).**
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](https://help.pinterest.com/en/business/a
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"). * The token's user_account must either be the Owner of the specified ad account, or have one of the necessa
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):
Create multiple new ads. Request must contain ad_group_id, creative_type, and the source Pin pin_id.
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](https://www.pinterest.com/_/_/policy/advertising-guidelines/).
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 `REJECT
Update multiple existing ads
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.
Delete ad preview records for one or more ad groups. All ad groups are validated before deleting any records.
Fetch ad preview records for one or more ad groups. Returns all active previews associated with the provided ad group IDs.
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](/docs/getting-started/using-beta-and-restricted-features/).**
Returns the list of discounts applied to the account. **This endpoint might not be available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/).**
Get download url for a billing invoice.
Get billing invoices in the advertiser account.
9 fields
Get billing profiles in the advertiser account. **This endpoint might not be available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/).**
Get 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 the owner of the specified ad account, or have one of the necessary roles granted via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accou
Create 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 necessary roles granted via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Finance, Campaign.
Edit 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 necessary roles granted via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Finance, Campaign.
Get 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 roles granted via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Finance, Campaign.
Get 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 granted via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Finance, Campaign.
Get 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 necessary roles granted via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Finance, Campaign.
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.](/docs/api-features/shopping-overview/#Update%20items%20in%20batch) By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [Lis
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_accou
Map advertiser defined events to standard events for the given ad account.
Untrack advertiser defined events for the given ad account.
Get advertiser defined events for the given ad account.
Update advertiser defined event names or mappings for the given ad account.
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.
Cancel membership/partnership invites and/or requests.
Assign 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 existing partnership exists. If an existing partnership exists, use "Create a request to access an existing partner's assets" to request access to your partner's assets. - invite_type="PARTNER_REQUE
Create batch invites or requests. Can create batch invites or requests as described below. - Invite members to join the business. This would required specifying the following: - invite_type="MEMBER_INVITE" - business_role="EMPLOYEE" OR business_role="BIZ_ADMIN" (To learn more about business roles, visit https://help.pinterest.com/en/business/arti
Get the membership/partnership invites and/or requests for the authorized user.
Accept or decline invites or requests.
Create a new asset group with the specified parameters. - An [asset group](https://help.pinterest.com/en/business/article/asset-groups) is a custom group of assets based on how you would like to manage your accounts.
Delete a batch of asset groups.
Update a batch of asset groups with the specified parameters.
Get all the members the requesting business has granted access to on the given asset.
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.
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.
Get 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 type by using the asset_type query. The return response will include the permissions the member has to that asset and the asset type.
Terminate multiple members' access to an asset.
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.
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: - partner_type=INTERNAL, you will retrieve your business assets that the partner has access to. - partner_type=EXTERNAL, you will retrieve the partner's business assets that the partner has granted you
Terminate multiple partners' access to an asset. If - partner_type=INTERNAL: You will terminate a partner's asset access to your business assets. - partner_type=EXTERNAL: You will terminate your own access to your partner's business assets.
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
Get Audience Insights for an ad account. The response will return insights for 3 types of audiences: the ad account's engaged audience on Pinterest, the ad account's total audience on Pinterest and Pinterest's total audience. [Learn more about Audience Insights](https://help.pinterest.com/en/business/article/audience-insights).
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
Create a new audience for the ad account.
Get a specific audience given the audience ID.
Get list of audiences for the ad account.
Update an existing audience for the ad account.
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". - By default, the "operation user_account" is the token user_account.
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". - By default, the "operation user_account" is the token user_account.
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". - By default, the "operation user_account" is the token user_account.
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". - By default, the "operation user_account" is the token user_account.
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". - By default, the "operation user_account" is the token user_account.
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". * By default, the "operation user_account" is the token user_account.
Delete 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". * By default, the "operation user_account" is the token user_account.
Get 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". * By default, the "operation user_account" is the token user_account.
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. * If no privacy is speci
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. - Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". - By default, the "operation user_account" is the token user_account.
Update 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 "operation user_account". * By default, the "operation user_account" is the token user_account.
Get a list of the boards a user follows. The request returns a board summary object array.
**This endpoint is currently in beta and not available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/).** Use this request, as a signed-in user, to follow another user.
Get a list of your followers.
Get a list of your linked business accounts.
Unverify a website verified by the signed-in user.
Get analytics for the "operation user_account" - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
Gets 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 Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
Gets 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: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".
Get a list of a user's following interests in one place.
Get account information for the "operation user_account" - By default, the "operation user_account" is the token user_account. [Understanding Business Access]: https://developers.pinterest.com/docs/getting-started/using-business-access/ "Understanding Business Access" If using Business Access: Specify an ad_account_id to use the owner of that ad_account as
Get a list of who a certain user follows.
Get user websites, claimed or not
Verify a website as a signed-in user.
Get verification code for user to install on the website to claim it.
Create a Brand Account that will be a child business of a business hierarchy. Request must contain name, username, and country.
Update an existing Brand Account
Terminate memberships between the specified members and your business.
Terminate partnerships between the specified partners and your business. Note: You may only batch terminate partners of the same partner type.
Get all of the viewing user's business employers.
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
Get all partners of the specified business. If the assets_summary=TRUE and: - partner_type=INTERNAL, the business assets returned are your business assets the partner has access to. - partner_type=EXTERNAL, the business assets returned are your partner's business assets the partner has granted you access to.
Update a system user information such as name.
Update a member's business role within the business.
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.
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).
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 <code>request_id</code> that can be used to obtain the status of the request.
Get the available filter attributes and values associated with a given feed or catalog owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. - `country`, `language`, and `feed_id` are only used in retail catalogs. - Note: It is not guaranteed that all available filter values will be returned. Instead thi
Create a new catalog 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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token u
Fetch catalogs 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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_ac
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
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](/docs/api/v5/#ope
Create 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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as th
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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that
Fetch 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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the
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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_accou
Fetch the status and results of a supplemental items batch operation. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an ad_account_id (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, t
Get 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 user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation u
Create product group to use in Catalogs 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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to
Delete a product group owned by the "operation user_account" from being in use in Catalogs. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account"
Delete product groups 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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the toke
Get 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 user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation u
Get 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 user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_acc
Get a product counts for a given Catalogs Product Group 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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_accou
Update product group owned by the "operation user_account" to use in Catalogs. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to
List products Pins owned by the "operation user_account" that meet the criteria specified in the Catalogs Product Group Filter given in the request. - This endpoint has been implemented in POST to allow for complex filters. This specific POST endpoint is designed to be idempotent. - By default, the "operation user_account" is the token user_account. Optiona
**This endpoint is currently in beta and not available to all apps.** [Learn more](/docs/key-concepts/using-beta-and-restricted-features/). 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 deletio
**This endpoint is currently in beta and not available to all apps.** [Learn more](/docs/key-concepts/using-beta-and-restricted-features/). 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 th
**This endpoint is currently in beta and not available to all apps.** [Learn more](/docs/key-concepts/using-beta-and-restricted-features/). Get a single conversion deletion request from `ad_account_id` with `request_id`.
**This endpoint is currently in beta and not available to all apps.** [Learn more](/docs/key-concepts/using-beta-and-restricted-features/). Get a list of the conversion deletion requests for the specified `ad_account_id`.
Get the Event Quality Score (EQS) of your conversion signals. [Event Quality Score](https://help.pinterest.com/en/business/article/eqs) 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.
Create a conversion tag, also known as [Pinterest tag](https://help.pinterest.com/en/business/article/set-up-the-pinterest-tag), with the option to enable enhanced match. The Pinterest Tag tracks actions people take on the ad account's website after they view the ad account's ad on Pinterest. The advertiser needs to customize this tag to track conversions.
Get information about an existing conversion tag.
List conversion tags associated with an ad account.
Get Ocpm eligible conversion tag events for an ad account.
Get all page visit conversion tag events for an ad account.
See keyword metrics for a specified country, aggregated across all of Pinterest. (Definitions are available from the "Get delivery metrics definitions" [API endpoint](/docs/api/v5/#operation/delivery_metrics/get)).
Create keywords for the following entity types (advertiser, campaign, ad group, or ad). 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 grou
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 thro
7 fields
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.
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. Mul
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](/docs/api/v5/customer_list
Get the metadata for a given upload by its ID.
Begin processing a customer list upload.
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](https://help.pinterest.com/en/business/article/audience-targeting) or the [Audiences](/docs/api-features/targeting-overview/) section of the
Gets a specific customer list given the customer list ID.
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](https://help.pinterest.com/en/business/article/audience-targeting) or the [Audiences](/docs/api-features/targeting-overview/) section of the ads management guide.
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
Customer segments allow advertisers to define existing customers for Pinterest Performance+ campaigns. Customer segments are made up of audience lists.
Get a list of the customer segments in the specified `ad_account_id`.
Update the customer segment given advertiser ID and customer segment ID
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. - This endpoint requires an `access_token` be generated through Ads Manager. Review the [Conversions Guide](/docs/api-f
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. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_
Create a new feed owned by the "operation user_account". - By default, the "operation user_account" is the token 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_accoun
Delete a feed 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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_a
Get a single feed 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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token us
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](/docs/api/v5/#operation/ad_accounts/list)) 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
Fetch feeds 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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_acc
Update a feed 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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_a
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.
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.
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.
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.
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.
Get integration metadata by ID. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager.
Get integration metadata list. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager.
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.
Get a single catalogs items batch owned by the "operating user_account". [See detailed documentation here.](/docs/api-features/shopping-overview/#Update%20items%20in%20batch) - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_
This endpoint supports multiple operations on a set of one or more catalog items owned by the "operation user_account". [See detailed documentation here.](/docs/work-with-catalogs/modify-items-in-batch/) - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts
Get the items of the catalog owned by the "operation user_account". [See detailed documentation here.](/docs/api-features/shopping-overview/#Update%20items%20in%20batch) - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accou
[Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Apply a label to one or more campaigns. Future releases may support labels for other [entities](/docs/key-concepts/pinterest-entities/) in addition to campaigns. Currently, you can apply **brand** and **custom** labels. Future releases will provide more options. **Note:** Yo
[Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Apply one or more labels to a campaign. Future releases may support labels for other [entities](/docs/key-concepts/pinterest-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 campa
[Closed beta](/docs/getting-started/using-beta-and-restricted-features/) 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.
[Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Remove a label from one or more entities.
[Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Change the properties of one or more labels.
**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](https://help.pinterest.com/en/business/article/lead-ads).
Create 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.
**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](https:/
**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](https://help.pinterest.com/en/business/article/lead-ads).
**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 t
**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
**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 downl
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
Get details for a registered media upload, including its current status. **[Learn more](/docs/api-features/creating-boards-and-pins/#creating-video-pins)** about video Pin creation.
List media uploads filtered by given parameters. **[Learn more](/docs/api-features/creating-boards-and-pins/#creating-video-pins)** about video Pin creation.
**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. - These events will not be us
**This endpoint is currently in beta and not available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/).** Get analytics for multiple pins owned by the "operation user_account" - or on a group board that has been shared with this account. - The maximum number of pins supported in a single request is 100. - By default, the
Get 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 user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account
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
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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as
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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the
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 "oper
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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to d
Update a pin owned by the "operating 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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_ac
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.
Generate a new and long-lived OAuth access token dedicated for sending conversions using a valid access token.
Get a specific existing order line associated with an ad account.
List existing order lines associated with an ad account.
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.')
Get a product group promotion by id
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
Update multiple existing Product Group Promotions (by product_group_id)
Get 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 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-account
Add 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 pin_ids in the request will result in an error. - If any product tag fails eligibility check, the entire request fails (all-or-nothing). - If a product tag is already tagged on the pin, it is treated a
Delete product tags from a pin. - If a product tag is not found on the pin, it is treated as a no-op success.
Retrieve all product tags for a pin. - Returns an empty array if the pin has no product tags.
Create multiple new promotions.
Delete a promotion within Pinterest.
Get a promotion by its Pinterest-specific id. It must be associated with the provided ad account id.
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.
Update multiple promotions.
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. - By default, the "operation user_account" is the token user_account. Optional: Bus
This returns a URL to a report given a token returned from [Build catalogs report](/docs/api/v5/#operation/reports/create). You can use the URL to download the report. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_account
List aggregated numbers of issues for a catalog 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](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In
Batch create schedules
Get schedules for a specific advertiser
Update one or more schedules
**This endpoint is currently in beta and not available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/).** Get the top 10 Pins by a given search term.
Search for boards for the "operation user_account". This includes boards of all board types. - By default, the "operation user_account" is the token 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](/docs/getting-started/using-business-acc
Search for pins for the "operation user_account". - By default, the "operation user_account" is the token 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](/docs/getting-started/using-business-access/) for more information.
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 campai
Get a list of the targeting templates in the specified `ad_account_id`
Update the targeting template given advertiser ID and targeting template ID
Get the text of the terms of service and see whether the advertiser has accepted the terms of service.
Get a list of terms logically related to each input term. Example: the term 'workout' would list related terms like 'one song workout', 'yoga workout', 'workout motivation', etc.
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.
Get a list of published editorial articles. Translations of the editorials will be provided if available; otherwise, the default language will be English.
Enables advertisers to pull top five trending topics by interest and market, at full parity with the Pinterest Trends UI.
Enables advertisers to retrieve demographic information, related pins, and trend lines for specified product categories
Get a list of growing Shopping Product Categories in ranked order allowing filtering by engagement type, vertical, age, and gender.
