Pinterest REST API

Version: 5.3.0, Pinterest developer documentation main page

Pinterest's REST API

Schemes:

Summary

Tag: ad_accounts

View analytical information about advertising.

Note: If the current operation_user_account (defined by the access token) has access to another user's Ad Accounts via Pinterest Business Access, you can modify your request to use the current operation_user_account's permissions to those Ad Accounts by including the ad_account_id in the path parameters for the request (e.g. .../?ad_account_id=12345&...).

Operation	Description
GET /ad_accounts	List ad accounts
GET /ad_accounts/{ad_account_id}/analytics	Get ad account analytics
GET /ad_accounts/{ad_account_id}/campaigns	List campaigns
GET /ad_accounts/{ad_account_id}/campaigns/analytics	Get campaign analytics
GET /ad_accounts/{ad_account_id}/ad_groups	List ad groups
GET /ad_accounts/{ad_account_id}/ad_groups/analytics	Get ad group analytics
GET /ad_accounts/{ad_account_id}/ads	List ads
GET /ad_accounts/{ad_account_id}/ads/analytics	Get ad analytics
GET /ad_accounts/{ad_account_id}/product_groups/analytics	Get product group analytics
GET /ad_accounts/{ad_account_id}/reports	Get the account analytics report created by the async call
POST /ad_accounts/{ad_account_id}/reports	Create async request for an account analytics report

Tag: boards

View, create, update, or delete information about boards.

Operation	Description
GET /boards	List boards
POST /boards	Create board
GET /boards/{board_id}	Get board
PATCH /boards/{board_id}	Update board
DELETE /boards/{board_id}	Delete board
GET /boards/{board_id}/sections	List board sections
POST /boards/{board_id}/sections	Create board section
PATCH /boards/{board_id}/sections/{section_id}	Update board section
DELETE /boards/{board_id}/sections/{section_id}	Delete board section
GET /boards/{board_id}/sections/{section_id}/pins	List Pins on board section
GET /boards/{board_id}/pins	List Pins on board

Tag: catalogs

Manage information about shopping product catalogs and items.

Operation	Description
GET /catalogs/feeds	List feeds
POST /catalogs/feeds	Create feed
GET /catalogs/feeds/{feed_id}	Get feed
PATCH /catalogs/feeds/{feed_id}	Update feed
DELETE /catalogs/feeds/{feed_id}	Delete feed
GET /catalogs/feeds/{feed_id}/processing_results	List processing results for a given feed
GET /catalogs/items	Get catalogs items
GET /catalogs/items/batch/{batch_id}	Get catalogs items batch
POST /catalogs/items/batch	Perform an operation on an item batch
DELETE /catalogs/product_groups/{product_group_id}	Delete product group
PATCH /catalogs/product_groups/{product_group_id}	Update product group
GET /catalogs/product_groups	Get product groups list
POST /catalogs/product_groups	Create product group

Tag: media

Operation	Description
GET /media	List media uploads
POST /media	Register media upload
GET /media/{media_id}	Get media upload details

Tag: oauth

Generating and refreshing OAuth access tokens.

Operation	Description
POST /oauth/token	Generate OAuth access token

Tag: pins

View, create, update, or delete information about Pins.

Operation	Description
POST /pins	Create Pin
GET /pins/{pin_id}	Get Pin
DELETE /pins/{pin_id}	Delete Pin
GET /pins/{pin_id}/analytics	Get Pin analytics

Tag: user_account

Read-only information about user accounts associated with a given access token.

Operation	Description
GET /user_account	Get user account
GET /user_account/analytics	Get user account analytics

Paths

List ad accounts

GET /ad_accounts

Tags: ad_accounts

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.


bookmark	Cursor used to fetch the next page of items	query	object	#/components/parameters/query_bookmark
page_size	Maximum number of items to include in a single page of the response. See documentation on Pagination for more information.	query	object	#/components/parameters/query_page_size
include_shared_accounts	Include shared ad accounts	query	object	#/components/parameters/query_include_shared_accounts

200 OK: response
default: Unexpected error


pinterest_oauth2	ads:read

List ad groups

GET /ad_accounts/{ad_account_id}/ad_groups

Tags: ad_accounts

Get a list of the 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: Admin, Analyst, Campaign Manager.


ad_account_id	Unique identifier of an ad account.	path	object	#/components/parameters/path_ad_account_id
campaign_ids	List of Campaign Ids to use to filter the results.	query	object	#/components/parameters/query_campaign_ids
ad_group_ids	List of Ad group Ids to use to filter the results.	query	object	#/components/parameters/query_ad_group_ids
entity_statuses	Entity status	query	object	#/components/parameters/query_entity_statuses
page_size	Maximum number of items to include in a single page of the response. See documentation on Pagination for more information.	query	object	#/components/parameters/query_page_size
order	The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items.	query	object	#/components/parameters/query_order
bookmark	Cursor used to fetch the next page of items	query	object	#/components/parameters/query_bookmark
translate_interests_to_names	Return interests as text names (if value is true) rather than topic IDs.	query	object	#/components/parameters/query_translate_interests_to_names

200 OK: Success
400 Bad Request: Invalid ad account group parameters.
default: Unexpected error


pinterest_oauth2	ads:read

Get ad group analytics

GET /ad_accounts/{ad_account_id}/ad_groups/analytics

Tags: ad_accounts

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: Admin, Analyst, Campaign Manager.


ad_account_id	Unique identifier of an ad account.	path	object	#/components/parameters/path_ad_account_id
start_date	Metric report start date (UTC). Format: YYYY-MM-DD	query	object	#/components/parameters/query_start_date
end_date	Metric report end date (UTC). Format: YYYY-MM-DD	query	object	#/components/parameters/query_end_date
ad_group_ids	List of Ad group Ids to use to filter the results.	query	object	#/components/parameters/query_ad_group_ids_required
columns	Columns to retrieve. NOTE: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency. For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound). If a column has no value, it may not be returned	query	object	#/components/parameters/query_columns
granularity	Granularity	query	object	#/components/parameters/query_granularity
click_window_days	Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days.	query	object	#/components/parameters/query_conversion_attribution_click_window_days
engagement_window_days	Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days.	query	object	#/components/parameters/query_conversion_attribution_engagement_window_days
view_window_days	Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `1` day.	query	object	#/components/parameters/query_conversion_attribution_view_window_days
conversion_report_time	The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event.	query	object	#/components/parameters/query_conversion_attribution_conversion_report_time

200 OK: Success
400 Bad Request: Invalid ad account group analytics parameters.
default: Unexpected error


pinterest_oauth2	ads:read

List ads

GET /ad_accounts/{ad_account_id}/ads

Tags: ad_accounts

Get a list of the 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: Admin, Analyst, Campaign Manager.


ad_account_id	Unique identifier of an ad account.	path	object	#/components/parameters/path_ad_account_id
campaign_ids	List of Campaign Ids to use to filter the results.	query	object	#/components/parameters/query_campaign_ids
ad_group_ids	List of Ad group Ids to use to filter the results.	query	object	#/components/parameters/query_ad_group_ids
ad_ids	List of Ad Ids to use to filter the results.	query	object	#/components/parameters/query_ad_ids
entity_statuses	Entity status	query	object	#/components/parameters/query_entity_statuses
page_size	Maximum number of items to include in a single page of the response. See documentation on Pagination for more information.	query	object	#/components/parameters/query_page_size
order	The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items.	query	object	#/components/parameters/query_order
bookmark	Cursor used to fetch the next page of items	query	object	#/components/parameters/query_bookmark

200 OK: Success
400 Bad Request: Invalid ad account ads parameters.
default: Unexpected error


pinterest_oauth2	ads:read

Get ad analytics

GET /ad_accounts/{ad_account_id}/ads/analytics

Tags: ad_accounts

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: Admin, Analyst, Campaign Manager.


ad_account_id	Unique identifier of an ad account.	path	object	#/components/parameters/path_ad_account_id
start_date	Metric report start date (UTC). Format: YYYY-MM-DD	query	object	#/components/parameters/query_start_date
end_date	Metric report end date (UTC). Format: YYYY-MM-DD	query	object	#/components/parameters/query_end_date
ad_ids	List of Ad Ids to use to filter the results.	query	object	#/components/parameters/query_ad_ids_required
columns	Columns to retrieve. NOTE: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency. For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound). If a column has no value, it may not be returned	query	object	#/components/parameters/query_columns
granularity	Granularity	query	object	#/components/parameters/query_granularity
click_window_days	Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days.	query	object	#/components/parameters/query_conversion_attribution_click_window_days
engagement_window_days	Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days.	query	object	#/components/parameters/query_conversion_attribution_engagement_window_days
view_window_days	Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `1` day.	query	object	#/components/parameters/query_conversion_attribution_view_window_days
conversion_report_time	The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event.	query	object	#/components/parameters/query_conversion_attribution_conversion_report_time

200 OK: Success
400 Bad Request: Invalid ad account ads analytics parameters.
default: Unexpected error


pinterest_oauth2	ads:read

Get ad account analytics

GET /ad_accounts/{ad_account_id}/analytics

Tags: ad_accounts

Get analytics for the specified ad_account_id, filtered by the specified options.

The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.


ad_account_id	Unique identifier of an ad account.	path	object	#/components/parameters/path_ad_account_id
start_date	Metric report start date (UTC). Format: YYYY-MM-DD	query	object	#/components/parameters/query_start_date
end_date	Metric report end date (UTC). Format: YYYY-MM-DD	query	object	#/components/parameters/query_end_date
columns	Columns to retrieve. NOTE: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency. For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound). If a column has no value, it may not be returned	query	object	#/components/parameters/query_columns
granularity	Granularity	query	object	#/components/parameters/query_granularity
click_window_days	Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days.	query	object	#/components/parameters/query_conversion_attribution_click_window_days
engagement_window_days	Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days.	query	object	#/components/parameters/query_conversion_attribution_engagement_window_days
view_window_days	Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `1` day.	query	object	#/components/parameters/query_conversion_attribution_view_window_days
conversion_report_time	The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event.	query	object	#/components/parameters/query_conversion_attribution_conversion_report_time

200 OK: Success
400 Bad Request: Invalid ad account analytics parameters.
default: Unexpected error


pinterest_oauth2	ads:read

List campaigns

GET /ad_accounts/{ad_account_id}/campaigns

Tags: ad_accounts

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: Admin, Analyst, Campaign Manager.


ad_account_id	Unique identifier of an ad account.	path	object	#/components/parameters/path_ad_account_id
campaign_ids	List of Campaign Ids to use to filter the results.	query	object	#/components/parameters/query_campaign_ids
entity_statuses	Entity status	query	object	#/components/parameters/query_entity_statuses
page_size	Maximum number of items to include in a single page of the response. See documentation on Pagination for more information.	query	object	#/components/parameters/query_page_size
order	The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID. Note that higher-value IDs are associated with more-recently added items.	query	object	#/components/parameters/query_order
bookmark	Cursor used to fetch the next page of items	query	object	#/components/parameters/query_bookmark

200 OK: Success
400 Bad Request: Invalid ad account campaign parameters.
default: Unexpected error


pinterest_oauth2	ads:read

Get campaign analytics

GET /ad_accounts/{ad_account_id}/campaigns/analytics

Tags: ad_accounts

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: Admin, Analyst, Campaign Manager.


ad_account_id	Unique identifier of an ad account.	path	object	#/components/parameters/path_ad_account_id
start_date	Metric report start date (UTC). Format: YYYY-MM-DD	query	object	#/components/parameters/query_start_date
end_date	Metric report end date (UTC). Format: YYYY-MM-DD	query	object	#/components/parameters/query_end_date
campaign_ids	List of Campaign Ids to use to filter the results.	query	object	#/components/parameters/query_campaign_ids_required
columns	Columns to retrieve. NOTE: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency. For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound). If a column has no value, it may not be returned	query	object	#/components/parameters/query_columns
granularity	Granularity	query	object	#/components/parameters/query_granularity
click_window_days	Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days.	query	object	#/components/parameters/query_conversion_attribution_click_window_days
engagement_window_days	Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days.	query	object	#/components/parameters/query_conversion_attribution_engagement_window_days
view_window_days	Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `1` day.	query	object	#/components/parameters/query_conversion_attribution_view_window_days
conversion_report_time	The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event.	query	object	#/components/parameters/query_conversion_attribution_conversion_report_time

200 OK: Success
400 Bad Request: Invalid ad account campaign analytics parameters.
default: Unexpected error


pinterest_oauth2	ads:read

Get product group analytics

GET /ad_accounts/{ad_account_id}/product_groups/analytics

Tags: ad_accounts

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: Admin, Analyst, Campaign Manager.


ad_account_id	Unique identifier of an ad account.	path	object	#/components/parameters/path_ad_account_id
start_date	Metric report start date (UTC). Format: YYYY-MM-DD	query	object	#/components/parameters/query_start_date
end_date	Metric report end date (UTC). Format: YYYY-MM-DD	query	object	#/components/parameters/query_end_date
product_group_ids	List of Product group Ids to use to filter the results.	query	object	#/components/parameters/query_product_group_ids_required
columns	Columns to retrieve. NOTE: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency. For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound). If a column has no value, it may not be returned	query	object	#/components/parameters/query_columns
granularity	Granularity	query	object	#/components/parameters/query_granularity
click_window_days	Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days.	query	object	#/components/parameters/query_conversion_attribution_click_window_days
engagement_window_days	Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days.	query	object	#/components/parameters/query_conversion_attribution_engagement_window_days
view_window_days	Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `1` day.	query	object	#/components/parameters/query_conversion_attribution_view_window_days
conversion_report_time	The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event.	query	object	#/components/parameters/query_conversion_attribution_conversion_report_time

200 OK: Success
400 Bad Request: Invalid ad account ads analytics parameters.
default: Unexpected error


pinterest_oauth2	ads:read

Get the account analytics report created by the async call

GET /ad_accounts/{ad_account_id}/reports

Tags: ad_accounts

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 and it's valid for an 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 them via Business Access: Admin, Analyst, Campaign Manager.


ad_account_id	Unique identifier of an ad account.	path	object	#/components/parameters/path_ad_account_id
token	Token returned from the post request creation call	query	object	#/components/parameters/query_token_required

200 OK: Success
400 Bad Request: Invalid ad account ads analytics parameters.
default: Unexpected error


pinterest_oauth2	ads:read

Create async request for an account analytics report

POST /ad_accounts/{ad_account_id}/reports

Tags: ad_accounts

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 granted to them via Business Access: Admin, Analyst, Campaign Manager.


ad_account_id	Unique identifier of an ad account.	path	object	#/components/parameters/path_ad_account_id

200 OK: Success
400 Bad Request: Invalid ad account ads analytics parameters.
default: Unexpected error


pinterest_oauth2	ads:read

List boards

GET /boards

Tags: boards

Get a list of the boards owned by the "operation user_account" + group boards where this account is a collaborator

Optional: Specify a privacy type (public, protected, or secret) to indicate which boards to return.

If no privacy is specified, all boards that can be returned (based on the scopes of the token and ad_account role if applicable) will be returned.


bookmark	Cursor used to fetch the next page of items	query	object	#/components/parameters/query_bookmark
page_size	Maximum number of items to include in a single page of the response. See documentation on Pagination for more information.	query	object	#/components/parameters/query_page_size
privacy	Privacy setting for a board.	query	object

200 OK: response
default: Unexpected error


pinterest_oauth2	boards:read

Create board

POST /boards

Tags: boards

Create a board owned by the "operation user_account".

By default, the "operation user_account" is the token user_account.

201 Created: response
400 Bad Request: The board name is invalid or duplicated.
default: Unexpected error


pinterest_oauth2	boards:read , boards:write

Delete board

DELETE /boards/{board_id}

Tags: boards

Delete a board owned by the "operation user_account".

By default, the "operation user_account" is the token user_account.


board_id	Unique identifier of a board.	path	object	#/components/parameters/path_board_id

204 No Content: Board deleted successfully
403 Forbidden: Not authorized to delete the board.
404 Not Found: Board not found.
409 Conflict: Could not get exclusive access to delete the board.
429 Too Many Requests: This request exceeded a rate limit. This can happen if the client exceeds one of the published rate limits or if multiple write operations are applied to an object within a short time window.
default: Unexpected error


pinterest_oauth2	boards:read , boards:write

Get board

GET /boards/{board_id}

Tags: boards

Get a board owned by the operation user_account - or a group board that has been shared with this account.

By default, the "operation user_account" is the token user_account.


board_id	Unique identifier of a board.	path	object	#/components/parameters/path_board_id

200 OK: response
404 Not Found: Board not found.
default: Unexpected error


pinterest_oauth2	boards:read

Update board

PATCH /boards/{board_id}

Tags: boards

Update a board owned by the "operating user_account".


board_id	Unique identifier of a board.	path	object	#/components/parameters/path_board_id

200 OK: response
400 Bad Request: Invalid board parameters.
403 Forbidden: Not authorized to update the board.
429 Too Many Requests: This request exceeded a rate limit. This can happen if the client exceeds one of the published rate limits or if multiple write operations are applied to an object within a short time window.
default: Unexpected error


pinterest_oauth2	boards:read , boards:write

List Pins on board

GET /boards/{board_id}/pins

Tags: boards

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.

By default, the "operation user_account" is the token user_account.


board_id	Unique identifier of a board.	path	object	#/components/parameters/path_board_id
bookmark	Cursor used to fetch the next page of items	query	object	#/components/parameters/query_bookmark
page_size	Maximum number of items to include in a single page of the response. See documentation on Pagination for more information.	query	object	#/components/parameters/query_page_size

200 OK: response
404 Not Found: Board not found.
default: Unexpected error


pinterest_oauth2	boards:read , pins:read

List board sections

GET /boards/{board_id}/sections

Tags: boards

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.

By default, the "operation user_account" is the token user_account.


board_id	Unique identifier of a board.	path	object	#/components/parameters/path_board_id
bookmark	Cursor used to fetch the next page of items	query	object	#/components/parameters/query_bookmark
page_size	Maximum number of items to include in a single page of the response. See documentation on Pagination for more information.	query	object	#/components/parameters/query_page_size

200 OK: response
default: Unexpected error


pinterest_oauth2	boards:read

Create board section

POST /boards/{board_id}/sections

Tags: boards

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.

By default, the "operation user_account" is the token user_account.


board_id	Unique identifier of a board.	path	object	#/components/parameters/path_board_id

201 Created: response
400 Bad Request: Invalid board section parameters.
403 Forbidden: Not authorized to create board sections.
409 Conflict: Could not get exclusive access to the board to create a new section.
500 Internal Server Error: Could not create a new board section.
default: Unexpected error


pinterest_oauth2	boards:read , boards:write

Delete board section

DELETE /boards/{board_id}/sections/{section_id}

Tags: boards

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.

By default, the "operation user_account" is the token user_account.


board_id	Unique identifier of a board.	path	object	#/components/parameters/path_board_id
section_id	Unique identifier of a board section.	path	object	#/components/parameters/path_board_section_id

204 No Content: Board section deleted successfully
403 Forbidden: Not authorized to delete board section.
404 Not Found: Board section not found.
409 Conflict: Board section conflict.
default: Unexpected error


pinterest_oauth2	boards:read , boards:write

Update board section

PATCH /boards/{board_id}/sections/{section_id}

Tags: boards

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.

By default, the "operation user_account" is the token user_account.


board_id	Unique identifier of a board.	path	object	#/components/parameters/path_board_id
section_id	Unique identifier of a board section.	path	object	#/components/parameters/path_board_section_id

200 OK: response
400 Bad Request: Invalid board section parameters.
403 Forbidden: Not authorized to update board section.
409 Conflict: Board section conflict.
default: Unexpected error


pinterest_oauth2	boards:read , boards:write

List Pins on board section

GET /boards/{board_id}/sections/{section_id}/pins

Tags: boards

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.

By default, the "operation user_account" is the token user_account.


board_id	Unique identifier of a board.	path	object	#/components/parameters/path_board_id
section_id	Unique identifier of a board section.	path	object	#/components/parameters/path_board_section_id
bookmark	Cursor used to fetch the next page of items	query	object	#/components/parameters/query_bookmark
page_size	Maximum number of items to include in a single page of the response. See documentation on Pagination for more information.	query	object	#/components/parameters/query_page_size

200 OK: response
403 Forbidden: Not authorized to access Pins on board section.
404 Not Found: Board or section not found.
409 Conflict: Board section conflict.
default: Unexpected error


pinterest_oauth2	boards:read , pins:read

List feeds

GET /catalogs/feeds

Tags: catalogs

This endpoint is currently in beta and not available to all apps. Learn more.

Fetch feeds owned by the "operating user_account".


bookmark	Cursor used to fetch the next page of items	query	object	#/components/parameters/query_bookmark
page_size	Maximum number of items to include in a single page of the response. See documentation on Pagination for more information.	query	object	#/components/parameters/query_page_size

200 OK: Success
400 Bad Request: Invalid parameters.
401 Unauthorized: Unauthorized access.
default: Unexpected error.


pinterest_oauth2	catalogs:read

Create feed

POST /catalogs/feeds

Tags: catalogs

This endpoint is currently in beta and not available to all apps. Learn more.

Create a new feed owned by the "operating user_account".

201 Created: Success
400 Bad Request: Invalid feed parameters.
401 Unauthorized: Unauthorized access.
403 Forbidden: Business account required.
409 Conflict: User website required.
422 Unprocessable Entity: Unique feed name is required.
default: Unexpected error


pinterest_oauth2	catalogs:read , catalogs:write

Delete feed

DELETE /catalogs/feeds/{feed_id}

Tags: catalogs

This endpoint is currently in beta and not available to all apps. Learn more.

Delete a feed owned by the "operating user_account".


feed_id	Unique identifier of a feed	path	object	#/components/parameters/path_catalogs_feed_id

204 No Content: Feed deleted successfully.
400 Bad Request: Invalid feed parameters.
403 Forbidden: Forbidden. Account not approved for feed mutations yet.
404 Not Found: Data feed not found.
409 Conflict: Conflict. Can't delete a feed with active promotions.
default: Unexpected error


pinterest_oauth2	catalogs:read , catalogs:write

Get feed

GET /catalogs/feeds/{feed_id}

Tags: catalogs

This endpoint is currently in beta and not available to all apps. Learn more.

Get a single feed owned by the "operating user_account".


feed_id	Unique identifier of a feed	path	object	#/components/parameters/path_catalogs_feed_id

200 OK: Success
400 Bad Request: Invalid feed parameters.
401 Unauthorized: Unauthorized access.
404 Not Found: Data feed not found.
default: Unexpected error.


pinterest_oauth2	catalogs:read

Update feed

PATCH /catalogs/feeds/{feed_id}

Tags: catalogs

This endpoint is currently in beta and not available to all apps. Learn more.

Update a feed owned by the "operating user_account".


feed_id	Unique identifier of a feed	path	object	#/components/parameters/path_catalogs_feed_id

200 OK: Success
400 Bad Request: Invalid feed parameters.
403 Forbidden: Forbidden. Account not approved for feed mutations yet.
404 Not Found: Data feed not found.
default: Unexpected error


pinterest_oauth2	catalogs:read , catalogs:write

List processing results for a given feed

GET /catalogs/feeds/{feed_id}/processing_results

Tags: catalogs

This endpoint is currently in beta and not available to all apps. Learn more.

Fetch a feed processing results owned by the owner user account.


feed_id	Unique identifier of a feed	path	object	#/components/parameters/path_catalogs_feed_id
bookmark	Cursor used to fetch the next page of items	query	object	#/components/parameters/query_bookmark
page_size	Maximum number of items to include in a single page of the response. See documentation on Pagination for more information.	query	object	#/components/parameters/query_page_size

200 OK: Success
400 Bad Request: Invalid parameters.
401 Unauthorized: Unauthorized access.
404 Not Found: Feed not found.
default: Unexpected error.


pinterest_oauth2	catalogs:read

Get catalogs items

GET /catalogs/items

Tags: catalogs

Get the items of the catalog created by the "operating user_account"


country	Country for the Catalogs Items	query	object	#/components/parameters/query_catalogs_items_country
item_ids	Catalos Item ids	query	object	#/components/parameters/query_catalogs_items
language	Language for the Catalogs Items	query	object	#/components/parameters/query_catalogs_items_language

200 OK: Response containing the requested catalogs items
401 Unauthorized: Not authorized to access catalogs items
403 Forbidden: Not authorized to access catalogs items
default: Unexpected error


pinterest_oauth2	catalogs:read

Perform an operation on an item batch

POST /catalogs/items/batch

Tags: catalogs

This endpoint is currently in beta and not available to all apps. Learn more.

This endpoint supports multiple operations on a set of one or more catalog items.

200 OK: Response containing the requested catalogs items batch
401 Unauthorized: Not authorized to post catalogs items
403 Forbidden: Not authorized to post catalogs items
default: Unexpected error


pinterest_oauth2	catalogs:read , catalogs:write

Get catalogs items batch

GET /catalogs/items/batch/{batch_id}

Tags: catalogs

This endpoint is currently in beta and not available to all apps. Learn more.

Get a single catalogs items batch created by the "operating user_account".


batch_id	Id of a catalogs items batch to fetch	path	object	#/components/parameters/path_catalogs_items_batch_id

200 OK: Response containing the requested catalogs items batch
401 Unauthorized: Not authorized to access catalogs items batch
403 Forbidden: Not authorized to access catalogs items batch
404 Not Found: Catalogs items batch not found
default: Unexpected error


pinterest_oauth2	catalogs:read

Get product groups list

GET /catalogs/product_groups

Tags: catalogs

This endpoint is currently in beta and not available to all apps. Learn more.

Get a list of product groups for a given Catalogs Feed Id.


feed_id	Unique identifier of a feed	query	object	#/components/parameters/query_catalogs_feed_id
bookmark	Cursor used to fetch the next page of items	query	object	#/components/parameters/query_bookmark
page_size	Maximum number of items to include in a single page of the response. See documentation on Pagination for more information.	query	object	#/components/parameters/query_page_size

200 OK: Success
400 Bad Request: Invalid feed parameters.
401 Unauthorized: Unauthorized access.
403 Forbidden: Forbidden. Account not approved for feed mutations yet.
404 Not Found: Data feed not found.
409 Conflict: Conflict. Can't create this catalogs product group with this value.
default: Unexpected error.


pinterest_oauth2	catalogs:read

Create product group

POST /catalogs/product_groups

Tags: catalogs

This endpoint is currently in beta and not available to all apps. Learn more.

Create product group to use in Catalogs.

201 Created: Success
400 Bad Request: Invalid body.
401 Unauthorized: Unauthorized access.
403 Forbidden: Forbidden. Account not approved for feed mutations yet.
409 Conflict: Conflict. Can't create this catalogs product group with this value.
default: Unexpected error.


pinterest_oauth2	catalogs:write

Delete product group

DELETE /catalogs/product_groups/{product_group_id}

Tags: catalogs

This endpoint is currently in beta and not available to all apps. Learn more.

Delete a product group from being in use in Catalogs.


product_group_id	Unique identifier of a product group	path	object	#/components/parameters/path_catalogs_product_group_id

204 No Content: Catalogs Product Group deleted successfully.
400 Bad Request: Invalid catalogs product group id parameters.
401 Unauthorized: Unauthorized access.
403 Forbidden: Forbidden. Account not approved for feed mutations yet.
404 Not Found: Catalogs product group not found.
409 Conflict: Conflict. Can't delete this catalogs product group.
default: Unexpected error.


pinterest_oauth2	catalogs:write

Update product group

PATCH /catalogs/product_groups/{product_group_id}

Tags: catalogs

This endpoint is currently in beta and not available to all apps. Learn more.

Update product group to use in Catalogs.


product_group_id	Unique identifier of a product group	path	object	#/components/parameters/path_catalogs_product_group_id

200 OK: Success
400 Bad Request: Invalid parameters.
401 Unauthorized: Unauthorized access.
404 Not Found: Catalogs product group not found.
409 Conflict: Conflict. Can't update this catalogs product group to this value.
default: Unexpected error.


pinterest_oauth2	catalogs:write

List media uploads

GET /media

Tags: media

List media uploads filtered by given parameters.

Learn more about video Pin creation.


bookmark	Cursor used to fetch the next page of items	query	object	#/components/parameters/query_bookmark
page_size	Maximum number of items to include in a single page of the response. See documentation on Pagination for more information.	query	object	#/components/parameters/query_page_size

200 OK: response
default: Unexpected error


pinterest_oauth2	pins:read

POST /media

Tags: media

The response includes all of the information needed to upload the media to Pinterest.

To upload the media, make an HTTP POST request (using curl, for example) to upload_url using the Content-Type header value. Send the media file's contents as the request's file parameter and also include all of the parameters from upload_parameters.

Learn more about video Pin creation.

201 Created: response
default: Unexpected error


pinterest_oauth2	pins:read , pins:write

Get media upload details

GET /media/{media_id}

Tags: media

Get details for a registered media upload, including its current status.

Learn more about video Pin creation.


media_id	Media identifier	path	object	#/components/parameters/path_media_id

200 OK: response
404 Not Found: Media upload not found
default: Unexpected error


pinterest_oauth2	pins:read

Generate OAuth access token

POST /oauth/token

Tags: oauth

Generate an OAuth access token by using an authorization code or a refresh token.

See Authentication for more.

200 OK: response
default: Unexpected error

Create Pin

POST /pins

Tags: pins

Create a Pin on a board or board section owned by the "operation user_account".

Note: If the current "operation user_account" (defined by the access token) has access to another user's Ad Accounts via Pinterest Business Access, you can modify your request to make use of the current operation_user_account's permissions to those Ad Accounts by including the ad_account_id in the path parameters for the request (e.g. .../?ad_account_id=12345&...).

This function is intended solely for publishing new content created by the user. If you are interested in saving content created by others to your Pinterest boards, sometimes called 'curated content', please use our Save button instead. For more tips on creating fresh content for Pinterest, review our Content App Solutions Guide.

Learn more about video Pin creation.

201 Created: Successful pin creation.
400 Bad Request: Invalid Pin parameters response
403 Forbidden: The Pin's image is too small, too large or is broken
404 Not Found: Board or section not found
429 Too Many Requests: This request exceeded a rate limit. This can happen if the client exceeds one of the published rate limits or if multiple write operations are applied to an object within a short time window.
default: Unexpected error


pinterest_oauth2	boards:read , boards:write , pins:read , pins:write

Delete Pin

DELETE /pins/{pin_id}

Tags: pins

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.


pin_id	Unique identifier of a Pin.	path	object	#/components/parameters/path_pin_id

204 No Content: Successfully deleted Pin
403 Forbidden: Not authorized to access board or Pin.
404 Not Found: Pin not found.
default: Unexpected error


pinterest_oauth2	boards:read , boards:write , pins:read , pins:write

Get Pin

GET /pins/{pin_id}

Tags: pins

Get a Pin owned by the "operation user_account" - or on a group board that has been shared with this account.

By default, the "operation user_account" is the token user_account.

Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account:

For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager.
For Pins on secret boards: Owner, Admin.


pin_id	Unique identifier of a Pin.	path	object	#/components/parameters/path_pin_id
ad_account_id	Unique identifier of an ad account.	query	object	#/components/parameters/query_ad_account_id

200 OK: response
403 Forbidden: Not authorized to access board or Pin.
404 Not Found: Pin not found.
default: Unexpected error


pinterest_oauth2	boards:read , pins:read

Get Pin analytics

GET /pins/{pin_id}/analytics

Tags: pins

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.

For Pins on public or protected boards: Admin, Analyst.
For Pins on secret boards: Admin.


pin_id	Unique identifier of a Pin.	path	object	#/components/parameters/path_pin_id
start_date	Metric report start date (UTC). Format: YYYY-MM-DD	query	object	#/components/parameters/query_start_date
end_date	Metric report end date (UTC). Format: YYYY-MM-DD	query	object	#/components/parameters/query_end_date
app_types	Apps or devices to get data for, default is all.	query	object	#/components/parameters/query_app_types
metric_types	Pin metric types to get data for, default is all.	query	object	#/components/parameters/query_pin_analytics_metric_types
split_field	How to split the data into groups. Not including this param means data won't be split.	query	object	#/components/parameters/query_split_field_pins
ad_account_id	Unique identifier of an ad account.	query	object	#/components/parameters/query_ad_account_id

200 OK: response
403 Forbidden: Not authorized to access board or Pin.
404 Not Found: Pin not found.
default: Unexpected error


pinterest_oauth2	boards:read , pins:read

Get user account

GET /user_account

Tags: user_account

Get account information 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 for more information.


ad_account_id	Unique identifier of an ad account.	query	object	#/components/parameters/query_ad_account_id

200 OK: response
403 Forbidden: Not authorized to access the user account.
default: Unexpected error


pinterest_oauth2	user_accounts:read

Get user account analytics

GET /user_account/analytics

Tags: user_account

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".


start_date	Metric report start date (UTC). Format: YYYY-MM-DD	query	object	#/components/parameters/query_start_date
end_date	Metric report end date (UTC). Format: YYYY-MM-DD	query	object	#/components/parameters/query_end_date
from_claimed_content	Filter on Pins that match your claimed domain.	query	object	#/components/parameters/query_from_claimed_content
pin_format	Pin formats to get data for, default is all.	query	object	#/components/parameters/query_pin_format
app_types	Apps or devices to get data for, default is all.	query	object	#/components/parameters/query_app_types
metric_types	Metric types to get data for, default is all.	query	object	#/components/parameters/query_metric_types
split_field	How to split the data into groups. Not including this param means data won't be split.	query	object	#/components/parameters/query_split_field_user_account
ad_account_id	Unique identifier of an ad account.	query	object	#/components/parameters/query_ad_account_id

200 OK: Success
403 Forbidden: Not authorized to access the user account analytics.
default: Unexpected error


pinterest_oauth2	user_accounts:read