Social — entry 023 of 38
Pinterest's API v5 lets registered apps read and write Pins, boards, and account data, and separately covers the Ads API for managing campaigns programmatically. Every call runs over OAuth 2.0 against api.pinterest.com, and while core Pins/boards access is free, some scopes require moving through Pinterest's trial and standard API access tiers before going into production.
AuthenticationOAuthRequires an OAuth flow; expect app registration.
HTTPSSupportedTraffic is encrypted in transit.
CORSDisabledBrowser calls need a server-side proxy.
PricingFreeNo paid tier — free for the documented use case.
FormatsJSONResponses can be requested as JSON.
GreatAPIs Score
Score77
Authentication8/25OAuth flow required
Pricing20/20Free to use
Docs20/20Machine-readable spec file bundled
Formats9/15Single response format
Freshness20/20Verified within 6 months
Embed this badge
<a href="https://greatapis.com/api/pinterest/"><img src="https://greatapis.com/badge/pinterest.svg" alt="Scored 77 on greatapis.com"></a>Auth quickstart
- Register an app / run the OAuth flow to obtain a bearer token.
- Send it as an Authorization header
Authorization: Bearer <token>
Stored keyNo key stored
Your key is stored only in this browser (localStorage) and sent directly to the API — never to greatapis.
Endpoints
ad_accounts14
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 <a href='/docs/getting-started/using-business-access/'>Pinterest Business Access</a>, 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&...).
GET/ad_accountsList ad accounts
Parameters
| Name | In | Required | Type |
|---|---|---|---|
include_shared_accounts | query | no | boolean |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accountsCreate ad account
Request body
application/json — AdAccountCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdAccount |
201 | Resource create operation completed successfully. | AdAccount |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}Get ad account
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdAccount |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/analyticsGet ad account analytics
Parameters
| Name | In | Required | Type |
|---|---|---|---|
start_date | query | yes | string |
end_date | query | yes | string |
columns | query | yes | array |
granularity | query | yes | — |
click_window_days | query | no | number |
engagement_window_days | query | no | number |
view_window_days | query | no | number |
conversion_report_time | query | no | string |
reporting_timezone | query | no | — |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/mmm_reportsGet advertiser Marketing Mix Modeling (MMM) report.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
token | query | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | MMMReport |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/mmm_reportsCreate a request for a Marketing Mix Modeling (MMM) report
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — MMMReportCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | MMMReport |
201 | Resource create operation completed successfully. | MMMReport |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/reportsGet the account analytics report created by the async call
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
token | query | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdsAnalyticsGetAsyncResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/reportsCreate async request for an account analytics report
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — AdsAnalyticsCreateAsyncRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdsAnalyticsCreateAsyncResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/reports/brand_category_skuGet advertiser brand, category, SKU report
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
token | query | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | ConversionProductReport |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/reports/brand_category_skuCreate a request for a brand, category, SKU report
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — ConversionProductReportCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | ConversionProductReport |
201 | Resource create operation completed successfully. | ConversionProductReport |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/ad_accounts/{ad_account_id}/sandboxDelete ads data for ad account in API Sandbox
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/targeting_analyticsGet targeting analytics for an ad account
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
start_date | query | yes | string |
end_date | query | yes | string |
targeting_types | query | yes | array |
columns | query | yes | array |
granularity | query | yes | — |
click_window_days | query | no | number |
engagement_window_days | query | no | number |
view_window_days | query | no | number |
conversion_report_time | query | no | string |
attribution_types | query | no | array |
reporting_timezone | query | no | — |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | MetricsResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/templatesList templates
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/templates/{template_id}/reportsCreate async request for an analytics report using a template
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
template_id | path | yes | string |
start_date | query | no | string |
end_date | query | no | string |
granularity | query | no | — |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | TemplateBasedReport |
201 | Resource create operation completed successfully. | TemplateBasedReport |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
ad_groups13
View, create or update ad groups.
GET/ad_accounts/{ad_account_id}/ad_groupsList ad groups
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
ad_account_id | path | yes | string |
campaign_ids | query | no | array |
ad_group_ids | query | no | array |
entity_statuses | query | no | array |
translate_interests_to_names | query | no | boolean |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/ad_groupsCreate ad groups
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — AdGroupBatchCreateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/ad_accounts/{ad_account_id}/ad_groupsUpdate ad groups
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — AdGroupBatchUpdateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/ad_groups/analyticsGet ad group analytics
Parameters
| Name | In | Required | Type |
|---|---|---|---|
start_date | query | yes | string |
end_date | query | yes | string |
ad_group_ids | query | yes | array |
columns | query | yes | array |
granularity | query | yes | — |
click_window_days | query | no | number |
engagement_window_days | query | no | number |
view_window_days | query | no | number |
conversion_report_time | query | no | string |
aggregate_report_rows | query | no | boolean |
reporting_timezone | query | no | — |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/ad_groups/audience_sizingGet audience sizing
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — AdGroupAudienceSizingCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdGroupAudienceSizing |
201 | Resource create operation completed successfully. | AdGroupAudienceSizing |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/ad_groups/targeting_analyticsGet targeting analytics for ad groups
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
ad_group_ids | query | yes | array |
start_date | query | yes | string |
end_date | query | yes | string |
targeting_types | query | yes | array |
columns | query | yes | array |
granularity | query | yes | — |
click_window_days | query | no | number |
engagement_window_days | query | no | number |
view_window_days | query | no | number |
conversion_report_time | query | no | string |
attribution_types | query | no | array |
reporting_timezone | query | no | — |
sort_columns | query | no | array |
sort_ascending | query | no | boolean |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | MetricsResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}Get ad group
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_group_id | path | yes | string |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdGroup |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}/dynamic_titlesProcess dynamic titles CSV
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
ad_group_id | path | yes | string |
Request body
application/json — DynamicTitlesProcessCSVCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | DynamicTitlesProcessCSV |
201 | Resource create operation completed successfully. | DynamicTitlesProcessCSV |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}/dynamic_titles/csvGet dynamic titles CSV download URL
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
ad_group_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | DynamicTitlesDownloadCSV |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}/dynamic_titles/statusGet dynamic titles status
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
ad_group_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | DynamicTitlesGetStatus |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}/dynamic_titles/uploadsGet dynamic titles upload URL
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
ad_group_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | DynamicTitlesUploadURL |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/bid_floorGet bid floors
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — BidFloorCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | BidFloor |
201 | Resource create operation completed successfully. | BidFloor |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/promotion_applied_entitiesList of ad groups using promotions IDs.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
ad_account_id | path | yes | string |
promotion_ids | query | yes | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
ads10
View, create or update ads.
POST/ad_accounts/{ad_account_id}/ad_previewsCreate ad preview with pin or image
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — AdPreviewRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdPreviewURLResponse |
201 | Resource create operation completed successfully. | AdPreviewURLResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/adsList ads
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
ad_account_id | path | yes | string |
campaign_ids | query | no | array |
ad_group_ids | query | no | array |
ad_ids | query | no | array |
entity_statuses | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/adsCreate ads
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — AdBatchCreateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdBatchWriteResponseModel |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/ad_accounts/{ad_account_id}/adsUpdate ads
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — AdBatchUpdateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdBatchWriteResponseModel |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/ads/analyticsGet ad analytics
Parameters
| Name | In | Required | Type |
|---|---|---|---|
pin_ids | query | no | array |
start_date | query | yes | string |
end_date | query | yes | string |
ad_ids | query | no | array |
columns | query | yes | array |
granularity | query | yes | — |
click_window_days | query | no | number |
engagement_window_days | query | no | number |
view_window_days | query | no | number |
conversion_report_time | query | no | string |
campaign_ids | query | no | array |
reporting_timezone | query | no | — |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/ads/targeting_analyticsGet targeting analytics for ads
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
ad_ids | query | yes | array |
start_date | query | yes | string |
end_date | query | yes | string |
targeting_types | query | yes | array |
columns | query | yes | array |
granularity | query | yes | — |
click_window_days | query | no | — |
engagement_window_days | query | no | — |
view_window_days | query | no | — |
conversion_report_time | query | no | — |
attribution_types | query | no | array |
reporting_timezone | query | no | — |
sort_columns | query | no | array |
sort_ascending | query | no | boolean |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | MetricsResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/ads/{ad_id}Get ad
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_id | path | yes | string |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | Ad |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/campaign_ad_previewFetch ad preview records for one or more ad groups
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_group_ids | query | yes | array |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/campaign_ad_previewCreate ad preview records for one or more ad groups
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
201 | Resource create operation completed successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/ad_accounts/{ad_account_id}/campaign_ad_previewDelete ad preview records for one or more ad groups
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_group_ids | query | yes | array |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
204 | Resource deleted successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
advanced_auction2
View, create, or update advanced auction item bid options.
POST/advanced_auction/items/getGet item bid options (POST)
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
Request body
application/json — AdvancedAuctionItemsGetRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdvancedAuctionItems |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
500 | The server encountered an unexpected condition that prevented it from fulfilling the request. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/advanced_auction/items/submitOperate on item level bid options
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
Request body
application/json — AdvancedAuctionItemsSubmitRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdvancedAuctionProcessedItems |
206 | Successful | AdvancedAuctionProcessedItems |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
500 | The server encountered an unexpected condition that prevented it from fulfilling the request. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
audience_insights2
View audience insights.
GET/ad_accounts/{ad_account_id}/audience_insightsGet audience insights
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
audience_insight_type | query | yes | — |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AudienceInsights |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/insights/audiencesGet audience insights scope and type
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
audience_sharing7
View, share, or revoke shared audiences.<br> Audience Sharing endpoints are not available to all apps, if you are interested in using them, reach out to us on our help center page. <a href='/docs/getting-started/using-beta-and-restricted-features/'>Learn more</a>.
PATCH/ad_accounts/{ad_account_id}/audiences/ad_accounts/sharedUpdate audience sharing between ad accounts
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — AdAccountToAdAccountSharedAudienceUpdateWithRequiredBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdAccountToAdAccountSharedAudience |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/ad_accounts/{ad_account_id}/audiences/businesses/sharedUpdate audience sharing from an ad account to businesses
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — AdAccountToBusinessSharedAudienceUpdateWithRequiredBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdAccountToBusinessSharedAudience |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/audiences/shared/accountsList accounts with access to an audience owned by an ad account
Parameters
| Name | In | Required | Type |
|---|---|---|---|
audience_id | query | yes | string |
account_type | query | yes | — |
ad_account_id | path | yes | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/businesses/{business_id}/audiencesList received audiences for a business
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
order | query | no | — |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/businesses/{business_id}/audiences/ad_accounts/sharedUpdate audience sharing from a business to ad accounts
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
Request body
application/json — BusinessToAdAccountSharedAudienceUpdateWithRequiredBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | BusinessToAdAccountSharedAudience |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/businesses/{business_id}/audiences/businesses/sharedUpdate audience sharing between businesses
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
Request body
application/json — BusinessToBusinessSharedAudienceUpdateWithRequiredBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | BusinessToBusinessSharedAudience |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/businesses/{business_id}/audiences/shared/accountsList accounts with access to an audience owned by a business
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
audience_id | query | yes | string |
account_type | query | yes | — |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
audiences4
View, create, or update audiences.
GET/ad_accounts/{ad_account_id}/audiencesList audiences
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
ad_account_id | path | yes | string |
ownership_type | query | no | — |
exclude_nca | query | no | boolean |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/audiencesCreate audience
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — AdAccountsAudienceCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdAccountsAudience |
201 | Resource create operation completed successfully. | AdAccountsAudience |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/audiences/{audience_id}Get audience
Parameters
| Name | In | Required | Type |
|---|---|---|---|
audience_id | path | yes | string |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdAccountsAudience |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/ad_accounts/{ad_account_id}/audiences/{audience_id}Update audience
Parameters
| Name | In | Required | Type |
|---|---|---|---|
audience_id | path | yes | string |
ad_account_id | path | yes | string |
Request body
application/json — AdAccountsAudienceUpdate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdAccountsAudience |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
billing11
View, create, or update information related to billing.
GET/ad_accounts/{ad_account_id}/ads_credit/discountsGet ads credit discounts
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/ads_credit/redeemRedeem ad credits
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — AdsCreditRedeemCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AdsCreditRedeem |
201 | Resource create operation completed successfully. | AdsCreditRedeem |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/billing_invoice/{billing_invoice_id}/downloadGet download url for a billing invoice
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
billing_invoice_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | BillingInvoiceDownloadResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/billing_invoicesGet billing invoices
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
ad_account_id | path | yes | string |
sort | query | no | — |
status | query | no | — |
document_type | query | no | — |
start_due_date | query | no | string |
end_due_date | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/billing_profilesGet billing profiles
Parameters
| Name | In | Required | Type |
|---|---|---|---|
is_active | query | yes | boolean |
ad_account_id | path | yes | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/ssio/accountsGet Salesforce account details including bill-to information.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | SSIOAccount |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/ssio/insertion_ordersCreate insertion order through SSIO.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — SSIOInsertionOrderCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | SSIOInsertionOrder |
201 | Resource create operation completed successfully. | SSIOInsertionOrder |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/ad_accounts/{ad_account_id}/ssio/insertion_ordersEdit insertion order through SSIO.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — SSIOInsertionOrderUpdate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | SSIOInsertionOrder |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/ssio/insertion_orders/statusGet insertion order status by ad account id.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/ssio/insertion_orders/{pin_order_id}/statusGet insertion order status by pin order id.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
pin_order_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | SSIOInsertionOrderStatusResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/ssio/order_linesGet Salesforce order lines by ad account id.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
pin_order_id | query | no | string |
ad_account_id | path | yes | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
boards11
View, create, update, or delete information about boards.
GET/boardsList boards
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
privacy | query | no | — |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/boardsCreate board
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
Request body
application/json — BoardCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | Board |
201 | Resource create operation completed successfully. | Board |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/boards/{board_id}Get board
Parameters
| Name | In | Required | Type |
|---|---|---|---|
board_id | path | yes | string |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | Board |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/boards/{board_id}Update board
Parameters
| Name | In | Required | Type |
|---|---|---|---|
board_id | path | yes | string |
ad_account_id | query | no | string |
Request body
application/json — BoardWithUpdatePrivacyUpdate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | BoardWithUpdatePrivacy |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/boards/{board_id}Delete board
Parameters
| Name | In | Required | Type |
|---|---|---|---|
board_id | path | yes | string |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | Board |
204 | Resource deleted successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/boards/{board_id}/pinsList Pins on board
Parameters
| Name | In | Required | Type |
|---|---|---|---|
board_id | path | yes | string |
creative_types | query | no | array |
ad_account_id | query | no | string |
pin_metrics | query | no | boolean |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/boards/{board_id}/sectionsList board sections
Parameters
| Name | In | Required | Type |
|---|---|---|---|
board_id | path | yes | string |
ad_account_id | query | no | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/boards/{board_id}/sectionsCreate board section
Parameters
| Name | In | Required | Type |
|---|---|---|---|
board_id | path | yes | string |
ad_account_id | query | no | string |
Request body
application/json — BoardSectionCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | BoardSection |
201 | Resource create operation completed successfully. | BoardSection |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/boards/{board_id}/sections/{section_id}Update board section
Parameters
| Name | In | Required | Type |
|---|---|---|---|
board_id | path | yes | string |
section_id | path | yes | string |
ad_account_id | query | no | string |
Request body
application/json — BoardSectionUpdateWithRequiredBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | BoardSection |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/boards/{board_id}/sections/{section_id}Delete board section
Parameters
| Name | In | Required | Type |
|---|---|---|---|
board_id | path | yes | string |
section_id | path | yes | string |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | BoardSection |
204 | Resource deleted successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/boards/{board_id}/sections/{section_id}/pinsList Pins on board section
Parameters
| Name | In | Required | Type |
|---|---|---|---|
board_id | path | yes | string |
section_id | path | yes | string |
ad_account_id | query | no | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
bulk3
Create, update, or download ads-related entities in bulk.
POST/ad_accounts/{ad_account_id}/bulk/downloadGet advertiser entities in bulk
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — BulkDownloadCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | BulkDownload |
201 | Resource create operation completed successfully. | BulkDownload |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/bulk/upsertCreate/update ad entities in bulk
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — BulkUpsertRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | BulkUpsertResponse |
default | Unexpected error | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/bulk/{bulk_request_id}Download advertiser entities in bulk
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
bulk_request_id | path | yes | string |
include_details | query | no | boolean |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | BulkJobData |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
campaigns8
View, create or update campaigns.
GET/ad_accounts/{ad_account_id}/campaignsList campaigns
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
ad_account_id | path | yes | string |
campaign_ids | query | no | array |
entity_statuses | query | no | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/campaignsCreate campaigns
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — CampaignBatchCreateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CampaignBatchWriteResponseModel |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/ad_accounts/{ad_account_id}/campaignsUpdate campaigns
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — CampaignBatchUpdateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CampaignBatchWriteResponseModel |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/campaigns/analyticsGet campaign analytics
Parameters
| Name | In | Required | Type |
|---|---|---|---|
start_date | query | yes | string |
end_date | query | yes | string |
campaign_ids | query | yes | array |
columns | query | yes | array |
granularity | query | yes | — |
click_window_days | query | no | number |
engagement_window_days | query | no | number |
view_window_days | query | no | number |
conversion_report_time | query | no | string |
aggregate_report_rows | query | no | boolean |
reporting_timezone | query | no | — |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/campaigns/delivery_estimatesGet campaign delivery estimates
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — CampaignDeliveryEstimatesCampaignRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CampaignDeliveryEstimatesResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
503 | The service is temporarily unavailable. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/campaigns/targeting_analyticsGet targeting analytics for campaigns
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
campaign_ids | query | yes | array |
start_date | query | yes | string |
end_date | query | yes | string |
targeting_types | query | yes | array |
columns | query | yes | array |
granularity | query | yes | — |
click_window_days | query | no | number |
engagement_window_days | query | no | number |
view_window_days | query | no | number |
conversion_report_time | query | no | string |
attribution_types | query | no | array |
reporting_timezone | query | no | — |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | MetricsResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/campaigns/{campaign_id}Get campaign
Parameters
| Name | In | Required | Type |
|---|---|---|---|
campaign_id | path | yes | string |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | Campaign |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/pins/analyticsGet pins analytics
Parameters
| Name | In | Required | Type |
|---|---|---|---|
campaign_id | query | yes | string |
pin_ids | query | yes | array |
start_date | query | yes | string |
end_date | query | yes | string |
columns | query | yes | array |
granularity | query | yes | — |
click_window_days | query | no | number |
engagement_window_days | query | no | number |
view_window_days | query | no | number |
conversion_report_time | query | no | string |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
catalog_feeds8
View and manage catalog feeds.
GET/catalogs/feedsList feeds
Parameters
| Name | In | Required | Type |
|---|---|---|---|
catalog_id | query | no | string |
ad_account_id | query | no | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/catalogs/feedsCreate feed
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
Request body
application/json — CatalogsFeedCreateRequestSchema (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CatalogsFeed |
201 | Resource create operation completed successfully. | CatalogsFeed |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/catalogs/feeds/{feed_id}Get feed
Parameters
| Name | In | Required | Type |
|---|---|---|---|
feed_id | path | yes | string |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CatalogsFeed |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/catalogs/feeds/{feed_id}Update feed
Parameters
| Name | In | Required | Type |
|---|---|---|---|
feed_id | path | yes | string |
ad_account_id | query | no | string |
Request body
application/json — CatalogsFeedUpdateRequestSchema (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CatalogsFeed |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/catalogs/feeds/{feed_id}Delete feed
Parameters
| Name | In | Required | Type |
|---|---|---|---|
feed_id | path | yes | string |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CatalogsFeed |
204 | Resource deleted successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/catalogs/feeds/{feed_id}/ingestIngest feed items
Parameters
| Name | In | Required | Type |
|---|---|---|---|
feed_id | path | yes | string |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CatalogsFeedIngestion |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/catalogs/feeds/{feed_id}/processing_resultsList feed processing results
Parameters
| Name | In | Required | Type |
|---|---|---|---|
feed_id | path | yes | string |
ad_account_id | query | no | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/catalogs/processing_results/{processing_result_id}/item_issuesList item issues
Parameters
| Name | In | Required | Type |
|---|---|---|---|
processing_result_id | path | yes | string |
item_numbers | query | no | array |
item_validation_issue | query | no | — |
ad_account_id | query | no | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
catalog_items3
View and manage catalog items directly without a feed.
POST/catalogs/itemsGet catalogs items (POST)
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
Request body
application/json — CatalogsItemsRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/catalogs/items/batchOperate on item batch
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
Request body
application/json — CatalogsItemsBatchPostRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CatalogsItemsBatch |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/catalogs/items/batch/{batch_id}Get item batch status
Parameters
| Name | In | Required | Type |
|---|---|---|---|
batch_id | path | yes | — |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CatalogsItemsBatch |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
catalog_product_groups10
View and manage catalog product groups using filters.
GET/catalogs/product_groupsList product groups
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | query | no | array |
feed_id | query | no | string |
catalog_id | query | no | string |
ad_account_id | query | no | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/catalogs/product_groupsCreate product group
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
Request body
application/json — CatalogsProductGroupsCreateRequestSchema (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CatalogsVerticalProductGroup |
201 | Resource create operation completed successfully. | CatalogsVerticalProductGroup |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/catalogs/product_groups/multipleCreate product groups
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
Request body
application/json — CatalogsProductGroupsCreateManyRequestSchema (required)
Responses
| Status | Description | Schema |
|---|---|---|
201 | The request has succeeded and a new resource has been created as a result. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/catalogs/product_groups/multipleDelete product groups
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | query | yes | array |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
204 | Resource deleted successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/catalogs/product_groups/{product_group_id}Get product group
Parameters
| Name | In | Required | Type |
|---|---|---|---|
product_group_id | path | yes | string |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CatalogsVerticalProductGroup |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/catalogs/product_groups/{product_group_id}Update single product group
Parameters
| Name | In | Required | Type |
|---|---|---|---|
product_group_id | path | yes | string |
ad_account_id | query | no | string |
Request body
application/json — CatalogsProductGroupsUpdateRequestSchema (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CatalogsVerticalProductGroup |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/catalogs/product_groups/{product_group_id}Delete product group
Parameters
| Name | In | Required | Type |
|---|---|---|---|
product_group_id | path | yes | string |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CatalogsVerticalProductGroup |
204 | Resource deleted successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/catalogs/product_groups/{product_group_id}/product_countsGet product counts
Parameters
| Name | In | Required | Type |
|---|---|---|---|
product_group_id | path | yes | string |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CatalogsProductGroupProductCountsVertical |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/catalogs/product_groups/{product_group_id}/productsList products by product group
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
product_group_id | path | yes | string |
pin_metrics | query | no | boolean |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/catalogs/products/get_by_product_group_filtersList products by filter
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
ad_account_id | query | no | string |
pin_metrics | query | no | boolean |
Request body
application/json — CatalogsListProductsByFilterRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
catalog_reports3
View and manage reports about catalogs.
GET/catalogs/reportsGet catalogs report
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
token | query | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CatalogsReport |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/catalogs/reportsBuild catalogs report
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
Request body
application/json — CatalogsReportParameters (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CatalogsCreateReportResponse |
201 | Resource create operation completed successfully. | CatalogsCreateReportResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/catalogs/reports/statsList report stats
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
parameters | query | yes | — |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
catalog_supplemental7
View and manage catalog supplemental items.
POST/catalogs/{catalog_id}/local_inventory_items/batchOperate on local inventory item batch
Parameters
| Name | In | Required | Type |
|---|---|---|---|
catalog_id | path | yes | string |
ad_account_id | query | no | string |
Request body
application/json — LocalInventoryItemsBatchCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | SupplementalItemsBatchResponse |
201 | Resource create operation completed successfully. | LocalInventoryItemsBatch |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/catalogs/{catalog_id}/local_inventory_items/queryGet local inventory items (POST)
Parameters
| Name | In | Required | Type |
|---|---|---|---|
catalog_id | path | yes | string |
ad_account_id | query | no | string |
Request body
application/json — LocalInventoryItemsGetCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | LocalInventoryItemsGet |
201 | Resource create operation completed successfully. | LocalInventoryItemsGet |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/catalogs/{catalog_id}/local_storesList local stores
Parameters
| Name | In | Required | Type |
|---|---|---|---|
catalog_id | path | yes | string |
ids | query | no | array |
ad_account_id | query | no | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/catalogs/{catalog_id}/local_storesCreate local stores
Parameters
| Name | In | Required | Type |
|---|---|---|---|
catalog_id | path | yes | string |
ad_account_id | query | no | string |
Request body
application/json (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
201 | Resource create operation completed successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/catalogs/{catalog_id}/local_storesUpdate local stores
Parameters
| Name | In | Required | Type |
|---|---|---|---|
catalog_id | path | yes | string |
ad_account_id | query | no | string |
Request body
application/json (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/catalogs/{catalog_id}/local_storesDelete local stores
Parameters
| Name | In | Required | Type |
|---|---|---|---|
catalog_id | path | yes | string |
ids | query | yes | array |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
204 | Resource deleted successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/catalogs/{catalog_id}/supplemental_items/batch/{batch_id}Get supplemental items batch status
Parameters
| Name | In | Required | Type |
|---|---|---|---|
catalog_id | path | yes | string |
batch_id | path | yes | string |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | SupplementalItemsBatchResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
catalogs3
Manage information about shopping product catalogs and items.
GET/catalogsList catalogs
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/catalogsCreate catalog
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
Request body
application/json — CatalogCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | Catalog |
201 | Resource create operation completed successfully. | Catalog |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/catalogs/available_filter_valuesList available filter values
Parameters
| Name | In | Required | Type |
|---|---|---|---|
catalog_id | query | yes | string |
feed_id | query | no | string |
country | query | no | — |
language | query | no | — |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CatalogsAvailableFilterValues |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
conversion_deletion_requests4
View, create, or delete conversion data deletion requests.
GET/ad_accounts/{ad_account_id}/conversion_deletion_requestsList conversion deletion requests
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/conversion_deletion_requestsCreate a conversion deletion request
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — ConversionDeletionRequestCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | ConversionDeletionRequest |
201 | Resource create operation completed successfully. | ConversionDeletionRequest |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/conversion_deletion_requests/{request_id}Get a single conversion deletion request
Parameters
| Name | In | Required | Type |
|---|---|---|---|
request_id | path | yes | string |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | ConversionDeletionRequest |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/ad_accounts/{ad_account_id}/conversion_deletion_requests/{request_id}Delete a conversion deletion request
Parameters
| Name | In | Required | Type |
|---|---|---|---|
request_id | path | yes | string |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | ConversionDeletionRequest |
204 | Resource deleted successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
conversion_eqs1
Get the Event Quality Score (EQS) of your conversion signals.
GET/ad_accounts/{ad_account_id}/conversion_eqsGet event quality score (EQS)
Parameters
| Name | In | Required | Type |
|---|---|---|---|
lookback_period | query | yes | — |
source_platform | query | no | — |
ingestion_source | query | no | — |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
conversion_events1
Submit conversion events via the Pinterest API.
POST/ad_accounts/{ad_account_id}/eventsSend conversions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
test | query | no | boolean |
Request body
application/json — ConversionEventsCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | ConversionEvents |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
422 | The request was well-formed but was unable to be followed due to semantic errors. | DetailedError |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
503 | The server is currently unable to handle the request due to a temporary overload or scheduled maintenance. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
conversion_tags5
View, create, or update conversion tags.
GET/ad_accounts/{ad_account_id}/conversion_tagsList conversion tags
Parameters
| Name | In | Required | Type |
|---|---|---|---|
filter_deleted | query | no | boolean |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/conversion_tagsCreate conversion tag
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — ConversionTagCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | ConversionTag |
201 | Resource create operation completed successfully. | ConversionTag |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/conversion_tags/ocpm_eligibleGet Ocpm eligible conversion tags
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | ConversionTagsOcpmEligibleResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/conversion_tags/page_visitGet page visit conversion tags
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/conversion_tags/{conversion_tag_id}Get conversion tag
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
conversion_tag_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | ConversionTag |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
customer_list_uploads3
View, create, or manage customer list uploads.
POST/ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}/uploadsCreate customer list upload
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
customer_list_id | path | yes | string |
Request body
application/json — CustomerListUploadCreateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CustomerListUploadCreateResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}/uploads/{customer_list_upload_id}Get customer list upload
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
customer_list_id | path | yes | string |
customer_list_upload_id | path | yes | — |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CustomerListUpload |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}/uploads/{customer_list_upload_id}/runRun customer list upload
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
customer_list_id | path | yes | string |
customer_list_upload_id | path | yes | — |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CustomerListUpload |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
customer_lists4
View, create, or update customer lists.
GET/ad_accounts/{ad_account_id}/customer_listsGet customer lists
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
exclude_nca | query | no | boolean |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/customer_listsCreate customer lists
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — CustomerListCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CustomerList |
201 | Resource create operation completed successfully. | CustomerList |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}Get customer list
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
customer_list_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CustomerList |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}Update customer list
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
customer_list_id | path | yes | string |
Request body
application/json — CustomerListUpdateWithRequiredBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CustomerList |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
customer_segment3
View, create, or update customer segments.
GET/ad_accounts/{ad_account_id}/customer_segmentsList customer segments
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
ad_account_id | path | yes | string |
include_sizing | query | no | boolean |
search_query | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/customer_segmentsCreate customer segments
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — CustomerSegmentCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CustomerSegment |
201 | Resource create operation completed successfully. | CustomerSegment |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/ad_accounts/{ad_account_id}/customer_segmentsUpdate customer segments
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — CustomerSegmentUpdateRequestUpdateWithRequiredBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
integrations7
View, create, or update commerce integrations.
GET/integrationsGet integration metadata list
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/integrations/commerceCreate commerce integration
Request body
application/json — IntegrationMetadataCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | IntegrationMetadata |
201 | Resource create operation completed successfully. | IntegrationMetadata |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/integrations/commerce/{external_business_id}Get commerce integration
Parameters
| Name | In | Required | Type |
|---|---|---|---|
external_business_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | IntegrationMetadata |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/integrations/commerce/{external_business_id}Update commerce integration
Parameters
| Name | In | Required | Type |
|---|---|---|---|
external_business_id | path | yes | string |
Request body
application/json — IntegrationMetadataUpdate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | IntegrationMetadata |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/integrations/commerce/{external_business_id}Delete commerce integration
Parameters
| Name | In | Required | Type |
|---|---|---|---|
external_business_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | IntegrationMetadata |
204 | Resource deleted successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/integrations/logsReceives batched logs from integration applications.
Request body
application/json — IntegrationLogsRequestCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | IntegrationLogsSuccessResponse |
400 | The server could not understand the request due to invalid syntax. | IntegrationLogsInvalidLogResponse |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/integrations/{id}Get integration metadata
Parameters
| Name | In | Required | Type |
|---|---|---|---|
id | path | yes | — |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | IntegrationRecord |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
keywords5
View, create or update keywords.
GET/ad_accounts/{ad_account_id}/keywordsGet keywords
Parameters
| Name | In | Required | Type |
|---|---|---|---|
campaign_id | query | no | string |
ad_group_id | query | no | string |
ad_group_ids | query | no | array |
match_types | query | no | array |
ad_account_id | path | yes | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/keywordsCreate keywords
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — KeywordsCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | Keywords |
201 | Resource create operation completed successfully. | Keywords |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/ad_accounts/{ad_account_id}/keywordsUpdate keywords
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — KeywordsUpdate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | Keywords |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/keywords/metricsGet country's keyword metrics
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
country_code | query | yes | string |
keywords | query | yes | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | KeywordsMetricsArrayResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/trends/keywords/{region}/top/{trend_type}List trending keywords
Parameters
| Name | In | Required | Type |
|---|---|---|---|
region | path | yes | — |
trend_type | path | yes | — |
interests | query | no | array |
genders | query | no | array |
ages | query | no | array |
include_keywords | query | no | — |
normalize_against_group | query | no | boolean |
limit | query | no | integer |
include_demographics | query | no | boolean |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | TrendingKeywordsResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
labels5
View, create, or update ad account labels.
GET/ad_accounts/{ad_account_id}/labelsList labels
Parameters
| Name | In | Required | Type |
|---|---|---|---|
campaign_ids | query | no | array |
label_ids | query | no | array |
entity_statuses | query | no | array |
label_types | query | no | array |
ad_account_id | path | yes | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/labelsCreate labels
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — LabelCreateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | LabelsResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/ad_accounts/{ad_account_id}/labelsUpdate labels
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — LabelUpdateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | LabelsResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/labels/{label_id}/applyApply label to entity
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
label_id | path | yes | string |
Request body
application/json — LabeledEntitiesCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | LabeledEntities |
201 | Resource create operation completed successfully. | LabeledEntities |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/labels/{label_id}/removeRemove label from entities
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
label_id | path | yes | string |
Request body
application/json — LabeledEntitiesCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | LabeledEntities |
201 | Resource create operation completed successfully. | LabeledEntities |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
lead_ads4
View, create, or update lead ads.
GET/ad_accounts/{ad_account_id}/leads/subscriptionsGet lead ads subscriptions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/leads/subscriptionsCreate lead ads subscription
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — LeadSubscriptionPostParamsCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | LeadSubscription |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/leads/subscriptions/{subscription_id}Get lead ads subscription by ID
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
subscription_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | LeadSubscription |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/ad_accounts/{ad_account_id}/leads/subscriptions/{subscription_id}Delete lead ads subscription
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
subscription_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | LeadSubscription |
204 | Resource deleted successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
lead_forms5
View lead forms.
GET/ad_accounts/{ad_account_id}/lead_formsList lead forms
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/lead_formsCreate lead forms
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — LeadFormsCreateBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/ad_accounts/{ad_account_id}/lead_formsUpdate lead forms
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — LeadFormsUpdateBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/lead_forms/{lead_form_id}Get lead form by id
Parameters
| Name | In | Required | Type |
|---|---|---|---|
lead_form_id | path | yes | string |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | LeadForm |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/lead_forms/{lead_form_id}/testCreate lead form test data
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
lead_form_id | path | yes | string |
Request body
application/json — LeadFormTestCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | LeadFormTest |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
leads_export2
Create and export leads information from lead ads.
POST/ad_accounts/{ad_account_id}/leads_exportCreate a request to export leads collected from a lead ad
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — LeadsExportsCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | LeadsExports |
201 | Resource create operation completed successfully. | LeadsExports |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/leads_export/{leads_export_id}Get the lead export from the lead export create call
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
leads_export_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | LeadsExportResponseData |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
media3
Register and manage media uploads.
GET/mediaList media uploads
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/mediaRegister media upload
Request body
application/json — MediaUploadCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | MediaUpload |
201 | Resource create operation completed successfully. | MediaUpload |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/media/{media_id}Get media upload details
Parameters
| Name | In | Required | Type |
|---|---|---|---|
media_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | Media |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
msot_events1
Submit Measurement Source of Truth attributed conversion events via the Pinterest API.
POST/ad_accounts/{ad_account_id}/msot/eventsSend Measurement Source Of Truth (MSOT) attributed conversion events
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — ConversionMSOTEventsCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
201 | Resource create operation completed successfully. | ConversionMSOTEvents |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
notification1
Send notifications.
POST/notificationsReceive notifications from external partners.
Request body
application/json — NotificationPostRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | NotificationResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
oauth3
Generate and refresh OAuth access tokens.
POST/oauth/conversion_tokenGenerate OAuth access token for conversion API
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | ConversionAccessToken |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/oauth/tokenGenerate OAuth access token
Request body
application/x-www-form-urlencoded — OauthAccessTokenCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | OauthAccessToken |
201 | Resource create operation completed successfully. | OauthAccessToken |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/oauth/token/revokeRevoke a token
Request body
application/x-www-form-urlencoded — TokenRevocationRequestCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
order_lines2
View order lines.
GET/ad_accounts/{ad_account_id}/order_linesGet order lines.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/order_lines/{order_line_id}Get order line
Parameters
| Name | In | Required | Type |
|---|---|---|---|
order_line_id | path | yes | string |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | OrderLine |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
pins8
View, create, update, or delete information about Pins.
GET/pinsList Pins
Parameters
| Name | In | Required | Type |
|---|---|---|---|
pin_filter | query | no | — |
pin_metrics | query | no | boolean |
include_protected_pins | query | no | boolean |
pin_type | query | no | — |
creative_types | query | no | array |
ad_account_id | query | no | string |
domain | query | no | string |
domains | query | no | array |
include_product_tag_obj | query | no | boolean |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/pinsCreate Pin
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
Request body
application/json — PinCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | Pin |
201 | Resource create operation completed successfully. | Pin |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/pins/analyticsGet multiple Pin analytics
Parameters
| Name | In | Required | Type |
|---|---|---|---|
pin_ids | query | yes | array |
start_date | query | yes | string |
end_date | query | yes | string |
app_types | query | no | string |
metric_types | query | yes | array |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/pins/{pin_id}Get Pin
Parameters
| Name | In | Required | Type |
|---|---|---|---|
pin_id | path | yes | string |
ad_account_id | query | no | string |
pin_metrics | query | no | boolean |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | Pin |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/pins/{pin_id}Update Pin
Parameters
| Name | In | Required | Type |
|---|---|---|---|
pin_id | path | yes | string |
ad_account_id | query | no | string |
Request body
application/json — PinUpdate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | Pin |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/pins/{pin_id}Delete Pin
Parameters
| Name | In | Required | Type |
|---|---|---|---|
pin_id | path | yes | string |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | Pin |
204 | Resource deleted successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/pins/{pin_id}/analyticsGet Pin analytics
Parameters
| Name | In | Required | Type |
|---|---|---|---|
pin_id | path | yes | string |
start_date | query | yes | string |
end_date | query | yes | string |
app_types | query | no | string |
metric_types | query | yes | array |
split_field | query | no | string |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | PinAnalyticsResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/pins/{pin_id}/saveSave Pin
Parameters
| Name | In | Required | Type |
|---|---|---|---|
pin_id | path | yes | string |
ad_account_id | query | no | string |
Request body
application/json — PinsSaveRequestCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
201 | The request has succeeded and a new resource has been created as a result. | Pin |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
product_group_promotions5
View, create, update, or delete information about promoted product groups.
GET/ad_accounts/{ad_account_id}/product_group_promotionsGet product group promotions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
ad_account_id | path | yes | string |
product_group_promotion_ids | query | no | array |
entity_statuses | query | no | array |
ad_group_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/product_group_promotionsCreate product group promotions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — ProductGroupPromotionsCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | ProductGroupPromotions |
201 | Resource create operation completed successfully. | ProductGroupPromotions |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/ad_accounts/{ad_account_id}/product_group_promotionsUpdate product group promotions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — ProductGroupPromotionsUpdateWithRequiredBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | ProductGroupPromotions |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/product_group_promotions/{product_group_promotion_id}Get a product group promotion by id
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
product_group_promotion_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | ProductGroupPromotion |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/product_groups/analyticsGet product group analytics
Parameters
| Name | In | Required | Type |
|---|---|---|---|
start_date | query | yes | string |
end_date | query | yes | string |
product_group_ids | query | yes | array |
columns | query | yes | array |
granularity | query | yes | — |
click_window_days | query | no | number |
engagement_window_days | query | no | number |
view_window_days | query | no | number |
conversion_report_time | query | no | string |
reporting_timezone | query | no | — |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
product_tags3
Tag products to hero pins.
GET/pins/{pin_id}/product_tagsGet product tags for pin
Parameters
| Name | In | Required | Type |
|---|---|---|---|
pin_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | ProductTagsResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/pins/{pin_id}/product_tagsAdd product tags to pin
Parameters
| Name | In | Required | Type |
|---|---|---|---|
pin_id | path | yes | string |
Request body
application/json — ProductTagsBulkAddRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | ProductTagsResponse |
400 | The request contains ineligible product tags. | ProductTagsError |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/pins/{pin_id}/product_tags/bulk-deleteDelete product tags from pin
Parameters
| Name | In | Required | Type |
|---|---|---|---|
pin_id | path | yes | string |
Request body
application/json — ProductTagsBulkDeleteRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
204 | Resource deleted successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
promotions5
View, create, update, or delete promotions.
GET/ad_accounts/{ad_account_id}/promotionsGet promotions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/promotionsCreate promotions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — PromotionCreateBatch (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | PromotionsResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/ad_accounts/{ad_account_id}/promotionsUpdate promotions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — PromotionUpdateBatch (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | PromotionsResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/ad_accounts/{ad_account_id}/promotions/{promotion_id}Get promotion by id
Parameters
| Name | In | Required | Type |
|---|---|---|---|
promotion_id | path | yes | string |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | Promotion |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/ad_accounts/{ad_account_id}/promotions/{promotion_id}Delete promotion by id
Parameters
| Name | In | Required | Type |
|---|---|---|---|
promotion_id | path | yes | string |
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | Promotion |
204 | Resource deleted successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
resources6
View metadata about available metrics and targeting options in the Pinterest API.
GET/resources/ad_account_countriesGet ad accounts countries
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/resources/delivery_metricsGet available metrics' definitions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
report_type | query | no | — |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/resources/lead_form_questionsGet lead form questions
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/resources/metrics_ready_stateGet metrics ready state
Parameters
| Name | In | Required | Type |
|---|---|---|---|
date | query | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | BookClosed |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/resources/targeting/interests/{interest_id}Get interest details
Parameters
| Name | In | Required | Type |
|---|---|---|---|
interest_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | SingleInterestTargetingOption |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/resources/targeting/{targeting_type}Get targeting options
Parameters
| Name | In | Required | Type |
|---|---|---|---|
targeting_type | path | yes | — |
ad_account_id | query | no | string |
client_id | query | no | string |
oauth_signature | query | no | string |
timestamp | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
search3
Search for Pins and boards owned by the current user.
GET/search/boardsSearch user's boards
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
query | query | no | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/search/partner/pinsSearch pins by a given search term
Parameters
| Name | In | Required | Type |
|---|---|---|---|
term | query | yes | string |
country_code | query | yes | string |
bookmark | query | no | string |
locale | query | no | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/search/pinsSearch user's Pins
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
query | query | yes | string |
bookmark | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
targeting_template3
View, create or update targeting templates.
GET/ad_accounts/{ad_account_id}/targeting_templatesList targeting templates
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
ad_account_id | path | yes | string |
include_sizing | query | no | boolean |
search_query | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/targeting_templatesCreate targeting templates
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — TargetingTemplateCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | TargetingTemplate |
201 | Resource create operation completed successfully. | TargetingTemplate |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/ad_accounts/{ad_account_id}/targeting_templatesUpdate targeting templates
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — TargetingTemplateUpdateRequestReadOrUpdate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
terms2
View related and suggested terms for ads targeting.
GET/terms/relatedList related terms
Parameters
| Name | In | Required | Type |
|---|---|---|---|
terms | query | yes | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | RelatedTerms |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/terms/suggestedList suggested terms
Parameters
| Name | In | Required | Type |
|---|---|---|---|
term | query | yes | string |
limit | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | TermsSuggestedResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
terms_of_service1
View Advertising Terms Of Service.
GET/ad_accounts/{ad_account_id}/terms_of_serviceGet terms of service
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
include_html | query | no | boolean |
tos_type | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | TermsOfService |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
trends4
View trending terms, topics, and product categories.
GET/trends/editorial_articlesReturns editorial articles for a given region
Parameters
| Name | In | Required | Type |
|---|---|---|---|
region | query | yes | — |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/trends/product_categories/detailsGet product category details
Parameters
| Name | In | Required | Type |
|---|---|---|---|
product_categories | query | yes | array |
region | query | yes | — |
lookback_window | query | no | — |
engagement_type | query | no | — |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/trends/product_categories/trendingGet a list of growing Shopping Product Categories
Parameters
| Name | In | Required | Type |
|---|---|---|---|
region | query | yes | — |
verticals | query | no | array |
ages | query | no | array |
genders | query | no | array |
engagement_type | query | no | — |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/trends/topics/featuredGet featured topics
Parameters
| Name | In | Required | Type |
|---|---|---|---|
interest | query | no | — |
region | query | yes | — |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
user_account14
View user accounts associated with a given access token.
GET/user_accountGet user account
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | Account |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/user_account/analyticsGet user account analytics
Parameters
| Name | In | Required | Type |
|---|---|---|---|
start_date | query | yes | string |
end_date | query | yes | string |
from_claimed_content | query | no | string |
pin_format | query | no | string |
app_types | query | no | string |
content_type | query | no | string |
source | query | no | string |
metric_types | query | no | array |
split_field | query | no | string |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AnalyticsResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/user_account/analytics/top_pinsGet user account top pins analytics
Parameters
| Name | In | Required | Type |
|---|---|---|---|
start_date | query | yes | string |
end_date | query | yes | string |
sort_by | query | yes | — |
from_claimed_content | query | no | string |
pin_format | query | no | string |
app_types | query | no | string |
content_type | query | no | string |
source | query | no | string |
metric_types | query | no | array |
num_of_pins | query | no | integer |
created_in_last_n_days | query | no | number |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | TopPinsAnalyticsResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/user_account/analytics/top_video_pinsGet user account top video pins analytics
Parameters
| Name | In | Required | Type |
|---|---|---|---|
start_date | query | yes | string |
end_date | query | yes | string |
sort_by | query | yes | — |
from_claimed_content | query | no | string |
pin_format | query | no | string |
app_types | query | no | string |
content_type | query | no | string |
source | query | no | string |
metric_types | query | no | array |
num_of_pins | query | no | integer |
created_in_last_n_days | query | no | number |
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | TopVideoPinsAnalyticsResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/user_account/businessesList linked businesses
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/user_account/followersList followers
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/user_account/followingList following
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
explicit_following | query | no | boolean |
feed_type | query | no | — |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/user_account/following/boardsList following boards
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
explicit_following | query | no | boolean |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/user_account/following/{username}Follow user
Parameters
| Name | In | Required | Type |
|---|---|---|---|
username | path | yes | string |
Request body
application/json — FollowUserCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | FollowUser |
201 | Resource create operation completed successfully. | FollowUser |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/user_account/websitesGet user websites
Parameters
| Name | In | Required | Type |
|---|---|---|---|
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/user_account/websitesVerify website
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
Request body
application/json — UserWebsiteCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | UserWebsite |
201 | Resource create operation completed successfully. | UserWebsite |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/user_account/websitesUnverify website
Parameters
| Name | In | Required | Type |
|---|---|---|---|
website | query | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | UserWebsite |
204 | Resource deleted successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/user_account/websites/verificationGet user verification code for website claiming
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | query | no | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | UserWebsiteVerification |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/users/{username}/interests/followList following interests
Parameters
| Name | In | Required | Type |
|---|---|---|---|
username | path | yes | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The server could not understand the request due to invalid syntax. | Pinterest.Lib.Error |
401 | Access is unauthorized. | Pinterest.Lib.Error |
404 | The server cannot find the requested resource. | Pinterest.Lib.Error |
default | Unexpected error | Pinterest.Lib.Error |
business_access_assets12
POST/businesses/{business_id}/asset_groupsCreate a new asset group.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
Request body
application/json — AssetGroupInputCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AssetGroupInput |
201 | Resource create operation completed successfully. | AssetGroupInput |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/businesses/{business_id}/asset_groupsUpdate asset groups.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
Request body
application/json — AssetGroupModificationReadOrUpdate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AssetGroupModification |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/businesses/{business_id}/asset_groupsDelete asset groups.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
Request body
application/json — AssetGroupDeletionDelete (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | AssetGroupDeletion |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/businesses/{business_id}/assetsList business assets
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
permissions | query | no | array |
child_asset_id | query | no | string |
asset_group_id | query | no | string |
asset_type | query | no | string |
start_index | query | no | integer |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/businesses/{business_id}/assets/{asset_id}/membersGet members with access to asset
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
asset_id | path | yes | string |
start_index | query | no | integer |
fetch_system_users | query | no | boolean |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/businesses/{business_id}/assets/{asset_id}/partnersGet partners with access to asset
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
asset_id | path | yes | string |
start_index | query | no | integer |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/businesses/{business_id}/members/assets/accessAssign/Update member asset permissions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
Request body
application/json — UpdateMemberAssetAccessBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | UpdateMemberAssetsResultsResponseArray |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/businesses/{business_id}/members/assets/accessDelete member access to asset
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
Request body
application/json — BusinessMembersAssetAccessDeleteBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | DeleteMemberAccessResultsResponseArray |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/businesses/{business_id}/members/{member_id}/assetsGet assets assigned to a member
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
member_id | path | yes | string |
asset_type | query | no | string |
start_index | query | no | integer |
sort_by | query | no | — |
sort_ascending | query | no | boolean |
search_by | query | no | — |
search_value | query | no | string |
asset_permission_type | query | no | — |
ad_account_statuses | query | no | array |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | BusinessMemberAssetsGetResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/businesses/{business_id}/partners/assetsAssign/Update partner asset permissions
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
Request body
application/json — UpdatePartnerAssetAccessBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | UpdatePartnerAssetsResultsResponseArray |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/businesses/{business_id}/partners/assetsDelete partner access to asset
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
Request body
application/json — DeletePartnerAssetAccessBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | DeletePartnerAssetAccessResultsResponseArray |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/businesses/{business_id}/partners/{partner_id}/assetsGet assets assigned to a partner or assets assigned by a partner
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
partner_id | path | yes | string |
partner_type | query | no | string |
asset_type | query | no | string |
start_index | query | no | integer |
sort_by | query | no | — |
sort_ascending | query | no | boolean |
search_by | query | no | — |
search_value | query | no | string |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
business_access_invite6
PATCH/businesses/invitesAccept or decline an invite/request
Request body
application/json — AuthRespondInvitesBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | RespondToInvitesResponseArray |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/businesses/{business_id}/invitesGet invites/requests
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
is_member | query | no | boolean |
invite_status | query | no | array |
invite_type | query | no | — |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/businesses/{business_id}/invitesCreate invites or requests
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
Request body
application/json — CreateMembershipOrPartnershipInvitesBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CreateInvitesResultsResponseArray |
201 | Resource create operation completed successfully. | CreateInvitesResultsResponseArray |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/businesses/{business_id}/invitesCancel invites/requests
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
Request body
application/json — CancelInvitesRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CancelInvitesResponse |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/businesses/{business_id}/invites/assets/accessUpdate invite/request with an asset permission
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
Request body
application/json — CreateAssetInvitesRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | UpdateInvitesResultsResponseArray |
201 | Resource create operation completed successfully. | UpdateInvitesResultsResponseArray |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/businesses/{business_id}/requests/assets/accessCreate a request to access an existing partner's assets.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
Request body
application/json — CreateAssetAccessRequestBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | CreateAssetAccessRequestResponse |
201 | Resource create operation completed successfully. | CreateAssetAccessRequestResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
business_access_relationships9
POST/business_access/business_hierarchy/{business_hierarchy_id}/brand_accountsCreate a Brand Account
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_hierarchy_id | path | yes | string |
Request body
application/json — BrandAccountCreate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | BrandAccount |
201 | Resource create operation completed successfully. | BrandAccount |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/business_access/business_hierarchy/{business_hierarchy_id}/brand_accounts/{brand_account_id}Update a Brand Account
Parameters
| Name | In | Required | Type |
|---|---|---|---|
brand_account_id | path | yes | string |
business_hierarchy_id | path | yes | string |
Request body
application/json — BrandAccountUpdate (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | BrandAccount |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
409 | The request could not be processed because of a conflict in the current state of the resource. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/businesses/employersList business employers for user
Parameters
| Name | In | Required | Type |
|---|---|---|---|
assets_summary | query | no | boolean |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/businesses/{business_id}/membersGet business members
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
fetch_system_users | query | no | boolean |
assets_summary | query | no | boolean |
business_roles | query | no | array |
member_ids | query | no | string |
start_index | query | no | integer |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/businesses/{business_id}/membersUpdate member's business role
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
Request body
application/json — UpdateBusinessMembershipsBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | UpdateBusinessMembershipsResponse |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/businesses/{business_id}/membersTerminate business memberships
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
Request body
application/json — DeleteBusinessMembershipBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
default | An unexpected error response. | Pinterest.Lib.Error |
GET/businesses/{business_id}/partnersGet business partners
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
assets_summary | query | no | boolean |
partner_type | query | no | — |
partner_ids | query | no | string |
start_index | query | no | integer |
sort_ascending | query | no | boolean |
bookmark | query | no | string |
page_size | query | no | integer |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/businesses/{business_id}/partnersTerminate business partnerships
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
Request body
application/json — DeleteBusinessPartnersDelete (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | DeleteBusinessPartners |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/businesses/{business_id}/system_users/{system_user_id}Update a system user information.
Parameters
| Name | In | Required | Type |
|---|---|---|---|
business_id | path | yes | string |
system_user_id | path | yes | string |
Request body
application/json — SystemUserUpdateWithRequiredBody (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
conversions4
GET/ad_accounts/{ad_account_id}/advertiser_defined_eventsGet advertiser defined events
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/advertiser_defined_eventsCreate advertiser defined events
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — AdvertiserDefinedEventsCreateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/ad_accounts/{ad_account_id}/advertiser_defined_eventsUpdate advertiser defined events
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json — AdvertiserDefinedEventsCreateRequest (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
DELETE/ad_accounts/{ad_account_id}/advertiser_defined_eventsDelete advertiser defined events
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
event_names | query | yes | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
schedules3
GET/ad_accounts/{ad_account_id}/schedulesGet Schedules
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
bookmark | query | no | string |
page_size | query | no | integer |
order | query | no | — |
schedule_statuses | query | no | array |
schedule_type | query | no | — |
entity_ids | query | yes | array |
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
POST/ad_accounts/{ad_account_id}/schedulesCreate schedules
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
201 | Resource create operation completed successfully. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
PATCH/ad_accounts/{ad_account_id}/schedulesUpdate schedules
Parameters
| Name | In | Required | Type |
|---|---|---|---|
ad_account_id | path | yes | string |
Request body
application/json (required)
Responses
| Status | Description | Schema |
|---|---|---|
200 | The request has succeeded. | — |
400 | The request could not be understood by the server due to unexpected data. | Pinterest.Lib.Error |
401 | Authentication is required and has either failed or not been provided. | Pinterest.Lib.Error |
403 | The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. | Pinterest.Lib.Error |
404 | The requested resource could not be found on this server. | Pinterest.Lib.Error |
429 | The user has sent too many requests in a given amount of time and is being rate limited. | Pinterest.Lib.Error |
default | An unexpected error response. | Pinterest.Lib.Error |
Try it
Developer reference
Base URL
https://api.pinterest.com/v5Rate limit
Pinterest enforces a universal cap on top of per-category limits: Trial access is 1,000 requests per day for all API requests, Standard access is 100 requests per second per user per app for all API requests. Each endpoint also belongs to a rate-limit category with its own ceiling -- org_read (boards, board sections, Pins) allows 1,000 requests per day on Trial and 1,000 per minute per user per app on Standard, org_write drops to 300/day and 100/minute, and ads_conversions is the outlier at up to 120,000 per minute per ad account. Every response reports live usage via x-ratelimit-limit/-remaining/-reset headers.
Key endpoints
- GET/user_account
- GET/boards
- POST/boards
- GET/pins
- POST/pins
SDKs
Changelog
Spec version5.28.0
Tracked paths189