openapi: 3.0.3 info: title: Pinterest REST API version: 5.28.0 contact: name: Pinterest, Inc. url: https://developers.pinterest.com/ license: name: MIT url: https://spdx.org/licenses/MIT termsOfService: https://developers.pinterest.com/terms/ description: Pinterest's REST API servers: - url: https://api.pinterest.com/v5 paths: /ad_accounts: get: operationId: ad_accounts/list summary: List ad accounts description: |- Get a list of the ad_accounts that the "operation user_account" has access to. - This includes ad_accounts they own and ad_accounts that are owned by others who have granted them [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts). parameters: - $ref: '#/components/parameters/AdAccountsGetAdditionalParams' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/AdAccount' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - ad_accounts x-ratelimit-category: ads_read x-sandbox: enabled post: operationId: ad_accounts/create summary: Create ad account description: |- Create a new ad account. Different ad accounts can support different currencies, payment methods, etc. An ad account is needed to create campaigns, ad groups, and ads; other accounts (your employees or partners) can be assigned business access and appropriate roles to access an ad account. You can set up up to 50 ad accounts per user. (The user must have a business account to create an ad account.) For more, see [Create an advertiser account](https://help.pinterest.com/en/business/article/create-an-advertiser-account). requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdAccountCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdAccount' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/AdAccount' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - ad_accounts x-ratelimit-category: ads_write x-sandbox: enabled /ad_accounts/{ad_account_id}: get: operationId: ad_accounts/get summary: Get ad account description: Get an ad account parameters: - $ref: '#/components/parameters/AdAccountKey' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdAccount' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - ad_accounts x-ratelimit-category: ads_read x-sandbox: enabled /ad_accounts/{ad_account_id}/ad_groups: get: operationId: ad_groups/list summary: List ad groups description: |- List ad groups based on provided campaign IDs or ad group IDs.(campaign_ids or ad_group_ids). **Note:** Provide only campaign_id or ad_group_id. Do not provide both. parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/query_campaign_ids' - $ref: '#/components/parameters/query_ad_group_ids' - $ref: '#/components/parameters/query_entity_statuses' - $ref: '#/components/parameters/query_translate_interests_to_names' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/AdGroup' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - ad_groups x-ratelimit-category: ads_read x-sandbox: enabled post: operationId: ad_groups/create summary: Create ad groups description: |- Create multiple new ad groups. All ads in a given ad group will have the same budget, bid, run dates, targeting, and placement (search, browse, other). For more information, [click here](https://help.pinterest.com/en/business/article/campaign-structure). **Notes:** - `bid_in_micro_currency` and `budget_in_micro_currency` should be expressed in microcurrency amounts based on the currency field set in the advertiser's profile. Microcurrency is used to track very small transactions, based on the currency set in the advertiser's profile. A microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser's profile. **Equivalency equations**, using dollars as an example currency: - $1 = 1,000,000 microdollars - 1 microdollar = $0.000001 **To convert between currency and microcurrency**, using dollars as an example currency: - To convert dollars to microdollars, multiply dollars by 1,000,000 - To convert microdollars to dollars, divide microdollars by 1,000,000 - Ad groups belong to ad campaigns. Some types of campaigns (e.g. budget optimization) have limits on the number of ad groups they can hold. If you exceed those limits, you will get an error message. - Certain organizations with [closed beta](/docs/getting-started/using-beta-and-restricted-features/) access can set `start_time` and `end_time` at the ad group level for campaigns with Campaign Budget Optimization (CBO) objectives: `TRAFFIC`, `AWARENESS`, `WEB_CONVERSIONS`, and `CATALOG_SALES`. All other organizations can set these scheduling parameters for non-CBO campaigns only. - If the parent ad campaign has start and end times set, ad group start and end times must occur within the parent campaign schedule. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdGroupBatchCreateRequest' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: items: type: array items: type: object properties: data: $ref: '#/components/schemas/AdGroup' exceptions: type: array items: $ref: '#/components/schemas/Pinterest.Lib.BatchItemException' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - ad_groups x-ratelimit-category: ads_write x-sandbox: enabled patch: operationId: ad_groups/update summary: Update ad groups description: Update multiple existing ad groups. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdGroupBatchUpdateRequest' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: items: type: array items: type: object properties: data: $ref: '#/components/schemas/AdGroup' exceptions: type: array items: $ref: '#/components/schemas/Pinterest.Lib.BatchItemException' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - ad_groups x-ratelimit-category: ads_write x-sandbox: enabled /ad_accounts/{ad_account_id}/ad_groups/analytics: get: operationId: ad_groups/analytics summary: Get ad group analytics description: |- Get analytics for the specified ad groups in the specified `ad_account_id`, filtered by the specified options. - The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Campaign Manager. - If granularity is not HOUR, you can pull data from up to 90 days before the current date in UTC time, with a maximum time range of 90 days. - If granularity is HOUR, you can pull data from up to 8 days before the current date in UTC time, with a maximum time range of 3 days. parameters: - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_ad_group_ids_required' - $ref: '#/components/parameters/query_columns' - $ref: '#/components/parameters/query_granularity' - $ref: '#/components/parameters/query_conversion_attribution_click_window_days' - $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days' - $ref: '#/components/parameters/query_conversion_attribution_view_window_days' - $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time' - $ref: '#/components/parameters/aggregate_report_rows' - $ref: '#/components/parameters/query_reporting_timezone' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: $ref: '#/components/schemas/AdGroupsAnalyticsMetrics' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - ad_groups x-ratelimit-category: ads_analytics x-sandbox: enabled /ad_accounts/{ad_account_id}/ad_groups/audience_sizing: post: operationId: ad_groups/audience_sizing summary: Get audience sizing description: |- Get potential audience size for an ad group with given targeting criteria. Potential audience size estimates the number of people you may be able to reach per month with your campaign. It is based on historical advertising data and the targeting criteria you select. It does not guarantee results or take into account factors such as bid, budget, schedule, seasonality or product experiments. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdGroupAudienceSizingCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdGroupAudienceSizing' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/AdGroupAudienceSizing' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - ad_groups x-ratelimit-category: ads_read x-sandbox: enabled /ad_accounts/{ad_account_id}/ad_groups/targeting_analytics: get: operationId: ad_groups_targeting_analytics/get summary: Get targeting analytics for ad groups description: |- Get targeting analytics for one or more ad groups. For the requested ad group(s) and metrics, the response will include the requested metric information (e.g. SPEND_IN_DOLLAR) for the requested target type (e.g. "age_bucket") for applicable values (e.g. "45-49"). - The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Campaign Manager. - If granularity is not HOUR, you can pull data from up to 90 days before the current date in UTC time, with a maximum time range of 90 days. - If granularity is HOUR, you can pull data from up to 8 days before the current date in UTC time, with a maximum time range of 3 days. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/query_ad_group_ids_required' - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_ad_group_targeting_types' - $ref: '#/components/parameters/query_columns' - $ref: '#/components/parameters/query_granularity' - $ref: '#/components/parameters/query_conversion_attribution_click_window_days' - $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days' - $ref: '#/components/parameters/query_conversion_attribution_view_window_days' - $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time' - $ref: '#/components/parameters/query_attribution_types' - $ref: '#/components/parameters/query_reporting_timezone' - $ref: '#/components/parameters/query_sort_columns' - $ref: '#/components/parameters/query_sort_ascending' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/MetricsResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - ad_groups x-ratelimit-category: ads_analytics x-sandbox: enabled /ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}: get: operationId: ad_groups/get summary: Get ad group description: Get a specific ad group given the ad group ID. parameters: - $ref: '#/components/parameters/AdGroupKey' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdGroup' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - ad_groups x-ratelimit-category: ads_read x-sandbox: enabled /ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}/dynamic_titles: post: operationId: ad_groups_dynamic_titles/process_csv summary: Process dynamic titles CSV description: Validate and process the uploaded dynamic titles review CSV. Returns validation errors if the CSV is invalid. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/path_ad_group_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DynamicTitlesProcessCSVCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/DynamicTitlesProcessCSV' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/DynamicTitlesProcessCSV' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - ad_groups x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}/dynamic_titles/csv: get: operationId: ad_groups_dynamic_titles/download_csv summary: Get dynamic titles CSV download URL description: Get a presigned S3 download URL for the dynamic titles review CSV. Returns 400 if titles have not been generated yet. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/path_ad_group_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/DynamicTitlesDownloadCSV' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - ad_groups x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}/dynamic_titles/status: get: operationId: ad_groups_dynamic_titles/get_status summary: Get dynamic titles status description: Get dynamic titles generation status for an ad group, including whether titles are ready for review and counts of generated and reviewed titles. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/path_ad_group_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/DynamicTitlesGetStatus' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - ad_groups x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}/dynamic_titles/uploads: get: operationId: ad_groups_dynamic_titles/get_upload_url summary: Get dynamic titles upload URL description: Get a presigned S3 upload URL for the dynamic titles review CSV and a request_id for submission. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/path_ad_group_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/DynamicTitlesUploadURL' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - ad_groups x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/ad_previews: post: operationId: ad_previews/create summary: Create ad preview with pin or image description: |- Create an ad preview given an ad account ID and either an existing organic pin ID or the URL for an image to be used to create the Pin and the ad. If you are creating a preview from an existing Pin, that Pin must be promotable: that is, it must have a clickthrough link and meet other requirements. (See [Ads Overview](https://help.pinterest.com/en/business/article/promoted-pins-overview).) You can view the returned preview URL on a webpage or iframe for 7 days, after which the URL expires. Collection ads are not currently supported ad preview. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdPreviewRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdPreviewURLResponse' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/AdPreviewURLResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - ads x-ratelimit-category: ads_write x-sandbox: enabled /ad_accounts/{ad_account_id}/ads: get: operationId: ads/list summary: List ads description: |- List ads that meet the filters provided: - Listed campaign ids or ad group ids or ad ids - Listed entity statuses If no filter is provided, all ads in the ad account are returned. **Note:** Provide only `campaign_id` or `ad_group_id` or `ad_id`. Do not provide more than one type. Review status is provided for each ad; if `review_status` is `REJECTED`, the `rejected_reasons` field will contain additional information. For more, see [Pinterest advertising standards](https://policy.pinterest.com/en/advertising-guidelines). parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/query_campaign_ids' - $ref: '#/components/parameters/query_ad_group_ids' - $ref: '#/components/parameters/query_ad_ids' - $ref: '#/components/parameters/query_entity_statuses' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/Ad' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - ads x-ratelimit-category: ads_read x-sandbox: enabled post: operationId: ads/create summary: Create ads description: Create multiple new ads. Request must contain ad_group_id, creative_type, and the source Pin pin_id. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdBatchCreateRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdBatchWriteResponseModel' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - ads x-ratelimit-category: ads_write x-sandbox: enabled patch: operationId: ads/update summary: Update ads description: Update multiple existing ads parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdBatchUpdateRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdBatchWriteResponseModel' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - ads x-ratelimit-category: ads_write x-sandbox: enabled /ad_accounts/{ad_account_id}/ads/analytics: get: operationId: ads/analytics summary: Get ad analytics description: |2- Get analytics for the specified ads in the specified `ad_account_id`, filtered by the specified options. - The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Campaign Manager. - The request must contain either ad_ids or both campaign_ids and pin_ids. - If granularity is not HOUR, you can pull data from up to 90 days before the current date in UTC time, with a maximum time range of 90 days. - If granularity is HOUR, you can pull data from up to 8 days before the current date in UTC time, with a maximum time range of 3 days. parameters: - $ref: '#/components/parameters/query_string_pin_ids' - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_ad_ids' - $ref: '#/components/parameters/query_columns' - $ref: '#/components/parameters/query_granularity' - $ref: '#/components/parameters/query_conversion_attribution_click_window_days' - $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days' - $ref: '#/components/parameters/query_conversion_attribution_view_window_days' - $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time' - $ref: '#/components/parameters/query_campaign_ids' - $ref: '#/components/parameters/query_reporting_timezone' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: $ref: '#/components/schemas/AdsAnalytics' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - ads x-ratelimit-category: ads_analytics x-sandbox: enabled /ad_accounts/{ad_account_id}/ads/targeting_analytics: get: operationId: ad_targeting_analytics/get summary: Get targeting analytics for ads description: |- Get targeting analytics for one or more ads. For the requested ad(s) and metrics, the response will include the requested metric information (e.g. SPEND_IN_DOLLAR) for the requested target type (e.g. "age_bucket") for applicable values (e.g. "45-49"). * The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Campaign Manager. * If granularity is not HOUR, you can pull data from up to 90 days before the current date in UTC time, with a maximum time range of 90 days. * If granularity is HOUR, you can pull data from up to 8 days before the current date in UTC time, with a maximum time range of 3 days. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/query_ad_ids_required' - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_ad_targeting_types' - $ref: '#/components/parameters/query_columns' - $ref: '#/components/parameters/query_granularity' - $ref: '#/components/parameters/query_conversion_attribution_click_window_daysOptimal' - $ref: '#/components/parameters/query_conversion_attribution_engagement_window_daysOptimal' - $ref: '#/components/parameters/query_conversion_attribution_view_window_daysOptimal' - $ref: '#/components/parameters/query_conversion_report_time' - $ref: '#/components/parameters/query_attribution_types' - $ref: '#/components/parameters/query_reporting_timezone' - $ref: '#/components/parameters/query_sort_columns' - $ref: '#/components/parameters/query_sort_ascending' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/MetricsResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - ads x-ratelimit-category: ads_analytics x-sandbox: enabled /ad_accounts/{ad_account_id}/ads/{ad_id}: get: operationId: ads/get summary: Get ad description: |- Get a specific ad given the ad ID. If your pin is rejected, rejected_reasons will contain additional information from the Ad Review process. For more information about our policies and rejection reasons see the [Pinterest advertising standards](https://www.pinterest.com/_/_/policy/advertising-guidelines/). parameters: - $ref: '#/components/parameters/AdKey' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Ad' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - ads x-ratelimit-category: ads_read x-sandbox: enabled /ad_accounts/{ad_account_id}/ads_credit/discounts: get: operationId: ads_credits_discounts/get summary: Get ads credit discounts description: |- Returns the list of discounts applied to the account. **This endpoint might not be available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/).** parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/AdsCreditDiscountsResponse' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - billing:read tags: - billing x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/ads_credit/redeem: post: operationId: ads_credit/redeem summary: Redeem ad credits description: |- Redeem ads credit on behalf of the ad account id and apply it towards billing. **This endpoint might not be available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/).** parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdsCreditRedeemCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdsCreditRedeem' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/AdsCreditRedeem' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write - billing:write tags: - billing x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/advertiser_defined_events: get: operationId: advertiser_defined_events/get summary: Get advertiser defined events description: Get advertiser defined events for the given ad account. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/AdvertiserDefinedEvent' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - conversions x-ratelimit-category: ads_read x-sandbox: disabled post: operationId: advertiser_defined_events/create summary: Create advertiser defined events description: Map advertiser defined events to standard events for the given ad account. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdvertiserDefinedEventsCreateRequest' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/AdvertiserDefinedEventProcessingRecord' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write - client_credentials: - ads:write tags: - conversions x-ratelimit-category: ads_write x-sandbox: disabled patch: operationId: advertiser_defined_events/update summary: Update advertiser defined events description: Update advertiser defined event names or mappings for the given ad account. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdvertiserDefinedEventsCreateRequest' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/AdvertiserDefinedEventProcessingRecord' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write - client_credentials: - ads:write tags: - conversions x-ratelimit-category: ads_write x-sandbox: disabled delete: operationId: advertiser_defined_events/delete summary: Delete advertiser defined events description: Untrack advertiser defined events for the given ad account. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/AdvertiserDefinedEventsDeleteQuery' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/AdvertiserDefinedEventProcessingRecord' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write - client_credentials: - ads:write tags: - conversions x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/analytics: get: operationId: ad_account/analytics summary: Get ad account analytics description: |2- Get analytics for the specified `ad_account_id`, filtered by the specified options. - The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Campaign Manager. - If granularity is not HOUR, you can pull data from up to 90 days before the current date in UTC time, with a maximum time range of 90 days. - If granularity is HOUR, you can pull data from up to 8 days before the current date in UTC time. parameters: - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_columns' - $ref: '#/components/parameters/query_granularity' - $ref: '#/components/parameters/query_conversion_attribution_click_window_days' - $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days' - $ref: '#/components/parameters/query_conversion_attribution_view_window_days' - $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time' - $ref: '#/components/parameters/query_reporting_timezone' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: $ref: '#/components/schemas/AdAccountAnalyticsItems' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - ad_accounts x-ratelimit-category: ads_analytics x-sandbox: enabled /ad_accounts/{ad_account_id}/audience_insights: get: operationId: audience_insights/get summary: Get audience insights description: |- Get Audience Insights for an ad account. The response will return insights for 3 types of audiences: the ad account's engaged audience on Pinterest, the ad account's total audience on Pinterest and Pinterest's total audience. [Learn more about Audience Insights](https://help.pinterest.com/en/business/article/audience-insights). parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/audience_insights_query_params' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AudienceInsights' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - audience_insights x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/audiences: post: operationId: audiences/create summary: Create audience description: Create a new audience for the ad account. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdAccountsAudienceCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdAccountsAudience' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/AdAccountsAudience' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - audiences x-ratelimit-category: ads_write x-sandbox: disabled get: operationId: audiences/list summary: List audiences description: Get list of audiences for the ad account. parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/AudienceGetAdditionalParams.ownership_type' - $ref: '#/components/parameters/AudienceGetAdditionalParams.exclude_nca' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/AdAccountsAudience' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - audiences x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/audiences/ad_accounts/shared: patch: operationId: update_ad_account_to_ad_account_shared_audience summary: Update audience sharing between ad accounts description: |- From an ad account, share a specific audience with another ad account, or revoke access to a previously shared audience. Only the audience owner account can share the audience. The recipient ad account(s) must be in the same [Pinterest Business Hierarchy](https://help.pinterest.com/en/business/article/create-and-manage-accounts) as the business owner of the ad account. This endpoint is not available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/). parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdAccountToAdAccountSharedAudienceUpdateWithRequiredBody' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdAccountToAdAccountSharedAudience' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - audience_sharing x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/audiences/businesses/shared: patch: operationId: update_ad_account_to_business_shared_audience summary: Update audience sharing from an ad account to businesses description: |- From an ad account, share a specific audience with a business account, or revoke access to a previously shared audience. Only the audience owner account can share the audience. The recipient business account must be in the same business hierarchy as the business owner of the ad account. This endpoint is not available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/). parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdAccountToBusinessSharedAudienceUpdateWithRequiredBody' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdAccountToBusinessSharedAudience' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - audience_sharing x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/audiences/shared/accounts: get: operationId: ad_accounts_audiences_shared_accounts/list summary: List accounts with access to an audience owned by an ad account description: List all ad accounts and/or businesses that have access to a specific audience. The audience must be owned by the requesting ad account. parameters: - $ref: '#/components/parameters/query_audience_id' - $ref: '#/components/parameters/query_account_type' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/SharedAudienceAccount' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - audience_sharing x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/audiences/{audience_id}: patch: operationId: audiences/update summary: Update audience description: Update an existing audience for the ad account. parameters: - $ref: '#/components/parameters/AdAccountsAudienceKey' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdAccountsAudienceUpdate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdAccountsAudience' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - audiences x-ratelimit-category: ads_write x-sandbox: disabled get: operationId: audiences/get summary: Get audience description: Get a specific audience given the audience ID. parameters: - $ref: '#/components/parameters/AdAccountsAudienceKey' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdAccountsAudience' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - audiences x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/bid_floor: post: operationId: ad_groups_bid_floor/get summary: Get bid floors description: |- List bid floors for your campaign configuration. Bid floors are given in microcurrency values based on the currency in the bid floor specification. Microcurrency is used to track very small transactions, based on the currency set in the advertiser's profile. A microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser's profile. **Equivalency equations**, using dollars as an example currency: * $1 = 1,000,000 microdollars * 1 microdollar = $0.000001 **To convert between currency and microcurrency**, using dollars as an example currency: * To convert dollars to microdollars, mutiply dollars by 1,000,000 * To convert microdollars to dollars, divide microdollars by 1,000,000 For more on bid floors see [Set your bid](https://help.pinterest.com/en/business/article/set-your-bid). parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BidFloorCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/BidFloor' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/BidFloor' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - ad_groups x-ratelimit-category: ads_read x-sandbox: enabled /ad_accounts/{ad_account_id}/billing_invoice/{billing_invoice_id}/download: get: operationId: billing_invoice_download/get summary: Get download url for a billing invoice description: Get download url for a billing invoice. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/path_billing_invoice_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/BillingInvoiceDownloadResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - billing:read tags: - billing x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/billing_invoices: get: operationId: billing_invoices/get summary: Get billing invoices description: Get billing invoices in the advertiser account. parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/query_sort_billing_invoice' - $ref: '#/components/parameters/query_billing_invoice_status' - $ref: '#/components/parameters/query_billing_document_type' - $ref: '#/components/parameters/query_billing_start_due_date' - $ref: '#/components/parameters/query_billing_end_due_date' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/BillingInvoice' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - billing:read tags: - billing x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/billing_profiles: get: operationId: billing_profiles/get summary: Get billing profiles description: |- Get billing profiles in the advertiser account. **This endpoint might not be available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/).** parameters: - $ref: '#/components/parameters/query_billing_profiles_is_active' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/BillingProfilesResponse' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - billing:read tags: - billing x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/bulk/download: post: operationId: bulk_download/create summary: Get advertiser entities in bulk description: |- Create an asynchronous report that may include information on campaigns, ad groups, product groups, ads, keywords, schedules,and/or labels; can filter by campaigns. Though the entities may be active, archived, or paused, only active entities will return data. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BulkDownloadCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/BulkDownload' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/BulkDownload' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - bulk x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/bulk/upsert: post: operationId: bulk_upsert/create summary: Create/update ad entities in bulk description: |- Either create or update any combination of campaigns, ad groups, product groups, ads, keywords, schedules, or labels. Note that this request will be processed asynchronously; the response will include a request_id that can be used to obtain the status of the request. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: description: Parameters to get create/update ad entities in bulk required: true content: application/json: schema: $ref: '#/components/schemas/BulkUpsertRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/BulkUpsertResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - bulk x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/bulk/{bulk_request_id}: get: operationId: bulk_request/get summary: Download advertiser entities in bulk description: |- Get the status of a bulk request by `request_id`, along with a download URL that will allow you to download the new or updated entity data (campaigns, ad groups, product groups, ads, schedules, or keywords). parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/BulkRequestStatusParameters.bulk_request_id' - $ref: '#/components/parameters/BulkRequestStatusParameters.include_details' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/BulkJobData' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - bulk x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/campaign_ad_preview: post: operationId: campaign_ad_preview/create summary: Create ad preview records for one or more ad groups description: |- Create ad preview records for one or more ad groups that can be shared. Each ad group is processed independently; individual failures do not block other previews. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/CampaignAdPreviewCreate' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: type: object required: - data properties: data: description: Created/updated resource on success or error details on failure oneOf: - $ref: '#/components/schemas/CampaignAdPreview' - type: object required: - exceptions properties: exceptions: $ref: '#/components/schemas/Pinterest.Lib.Error' '201': description: Resource create operation completed successfully. content: application/json: schema: type: array items: $ref: '#/components/schemas/CampaignAdPreview' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - ads x-ratelimit-category: ads_write x-sandbox: enabled get: operationId: campaign_ad_preview/read summary: Fetch ad preview records for one or more ad groups description: |- Fetch ad preview records for one or more ad groups. Returns all active previews associated with the provided ad group IDs. parameters: - $ref: '#/components/parameters/query_ad_group_ids_required' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: $ref: '#/components/schemas/CampaignAdPreview' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - ads x-ratelimit-category: ads_read x-sandbox: enabled delete: operationId: campaign_ad_preview/delete summary: Delete ad preview records for one or more ad groups description: |- Delete ad preview records for one or more ad groups. All ad groups are validated before deleting any records. parameters: - $ref: '#/components/parameters/query_ad_group_ids_required' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: type: object required: - status properties: status: oneOf: - $ref: '#/components/schemas/Pinterest.Lib.Status204' - $ref: '#/components/schemas/Pinterest.Lib.Error' '204': description: Resource deleted successfully. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - ads x-ratelimit-category: ads_write x-sandbox: enabled /ad_accounts/{ad_account_id}/campaigns: get: operationId: campaigns/list summary: List campaigns description: |- Get a list of the campaigns in the specified `ad_account_id`, filtered by the specified options. - The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Campaign Manager. parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/query_campaign_ids' - $ref: '#/components/parameters/query_entity_statuses' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/Campaign' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - campaigns x-ratelimit-category: ads_read x-sandbox: enabled post: operationId: campaigns/create summary: Create campaigns description: |- Create multiple new campaigns. Every campaign has its own campaign_id and houses one or more ad groups, which contain one or more ads. For more, see [Set up your campaign](https://help.pinterest.com/en/business/article/set-up-your-campaign/). **Note:** - The values for `lifetime_spend_cap` and `daily_spend_cap` are microcurrency amounts based on the currency field set in the advertiser's profile (e.g. USD). Microcurrency is used to track very small transactions, based on the currency set in the advertiser's profile. A microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser's profile. **Equivalency equations**, using dollars as an example currency: - $1 = 1,000,000 microdollars - 1 microdollar = $0.000001 **To convert between currency and microcurrency**, using dollars as an example currency: - To convert dollars to microdollars, multiply dollars by 1,000,000 - To convert microdollars to dollars, divide microdollars by 1,000,000 parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CampaignBatchCreateRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CampaignBatchWriteResponseModel' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - campaigns x-ratelimit-category: ads_write x-sandbox: enabled patch: operationId: campaigns/update summary: Update campaigns description: |- Update multiple ad campaigns based on campaign_ids. **Note:** - The values for `lifetime_spend_cap` and `daily_spend_cap` are microcurrency amounts based on the currency field set in the advertiser's profile (e.g. USD). Microcurrency is used to track very small transactions, based on the currency set in the advertiser's profile. A microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser's profile. **Equivalency equations**, using dollars as an example currency: - $1 = 1,000,000 microdollars - 1 microdollar = $0.000001 **To convert between currency and microcurrency**, using dollars as an example currency: - To convert dollars to microdollars, multiply dollars by 1,000,000 - To convert microdollars to dollars, divide microdollars by 1,000,000 parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CampaignBatchUpdateRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CampaignBatchWriteResponseModel' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - campaigns x-ratelimit-category: ads_write x-sandbox: enabled /ad_accounts/{ad_account_id}/campaigns/analytics: get: operationId: campaigns/analytics summary: Get campaign analytics description: |- Get analytics for the specified campaigns in the specified `ad_account_id`, filtered by the specified options. - The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Campaign Manager. - If granularity is not HOUR, you can pull data from up to 90 days before the current date in UTC time, with a maximum time range of 90 days. - If granularity is HOUR, you can pull data from up to 8 days before the current date in UTC time, with a maximum time range of 3 days. parameters: - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_campaign_ids_required' - $ref: '#/components/parameters/query_columns' - $ref: '#/components/parameters/query_granularity' - $ref: '#/components/parameters/query_conversion_attribution_click_window_days' - $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days' - $ref: '#/components/parameters/query_conversion_attribution_view_window_days' - $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time' - $ref: '#/components/parameters/aggregate_report_rows' - $ref: '#/components/parameters/query_reporting_timezone' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: $ref: '#/components/schemas/CampaignsAnalyticsMetrics' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - campaigns x-ratelimit-category: ads_analytics x-sandbox: enabled /ad_accounts/{ad_account_id}/campaigns/delivery_estimates: post: operationId: get_campaign_delivery_estimates summary: Get campaign delivery estimates description: |- Get delivery estimates for an ads campaign **This endpoint is currently in beta and is not available to all apps [Learn more](/docs/new/about-beta-access/).** parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CampaignDeliveryEstimatesCampaignRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CampaignDeliveryEstimatesResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '503': description: The service is temporarily unavailable. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - campaigns x-ratelimit-category: ads_estimates_read x-sandbox: disabled /ad_accounts/{ad_account_id}/campaigns/targeting_analytics: get: operationId: campaign_targeting_analytics/get summary: Get targeting analytics for campaigns description: |- Get targeting analytics for one or more campaigns. For the requested account and metrics, the response will include the requested metric information (e.g. SPEND_IN_DOLLAR) for the requested target type (e.g. "age_bucket") for applicable values (e.g. "45-49"). * The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Campaign Manager. * If granularity is not HOUR, you can pull data from up to 90 days before the current date in UTC time, with a maximum time range of 90 days. * If granularity is HOUR, you can pull data from up to 8 days before the current date in UTC time, with a maximum time range of 3 days. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/query_campaign_ids_required' - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_campaign_targeting_types' - $ref: '#/components/parameters/query_columns' - $ref: '#/components/parameters/query_granularity' - $ref: '#/components/parameters/query_conversion_attribution_click_window_days' - $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days' - $ref: '#/components/parameters/query_conversion_attribution_view_window_days' - $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time' - $ref: '#/components/parameters/query_attribution_types' - $ref: '#/components/parameters/query_reporting_timezone' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/MetricsResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - campaigns x-ratelimit-category: ads_analytics x-sandbox: enabled /ad_accounts/{ad_account_id}/campaigns/{campaign_id}: get: operationId: campaigns/get summary: Get campaign description: Get a specific campaign given the campaign ID. parameters: - $ref: '#/components/parameters/CampaignKey' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Campaign' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - campaigns x-ratelimit-category: ads_read x-sandbox: enabled /ad_accounts/{ad_account_id}/conversion_deletion_requests: get: operationId: conversion_deletion_request/list summary: List conversion deletion requests description: |- **This endpoint is currently in beta and not available to all apps.** [Learn more](/docs/key-concepts/using-beta-and-restricted-features/). Get a list of the conversion deletion requests for the specified `ad_account_id`. parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/ConversionDeletionRequest' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - conversion_deletion_requests x-ratelimit-category: ads_read x-sandbox: disabled post: operationId: conversion_deletion_request/create summary: Create a conversion deletion request description: |- **This endpoint is currently in beta and not available to all apps.** [Learn more](/docs/key-concepts/using-beta-and-restricted-features/). Create a request to delete conversion data for a list of user emails and/or EPIKs, limited to the specified `ad_account_id`. After 72 hours the request is processed and submitted to our deletion process. Then the deletion process ensures deletion within a 30 days period, once the request is submitted to the deletion process it cannot be canceled. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConversionDeletionRequestCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/ConversionDeletionRequest' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/ConversionDeletionRequest' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write - client_credentials: - ads:write tags: - conversion_deletion_requests x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/conversion_deletion_requests/{request_id}: get: operationId: conversion_deletion_request/get summary: Get a single conversion deletion request description: |- **This endpoint is currently in beta and not available to all apps.** [Learn more](/docs/key-concepts/using-beta-and-restricted-features/). Get a single conversion deletion request from `ad_account_id` with `request_id`. parameters: - $ref: '#/components/parameters/ConversionDeletionRequestKey' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/ConversionDeletionRequest' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - conversion_deletion_requests x-ratelimit-category: ads_read x-sandbox: disabled delete: operationId: conversion_deletion_request/delete summary: Delete a conversion deletion request description: |- **This endpoint is currently in beta and not available to all apps.** [Learn more](/docs/key-concepts/using-beta-and-restricted-features/). Delete a conversion deletion request from `ad_account_id` with `request_id`. This will cancel the request and prevent it from being processed. This can only be done if the request is in the `PENDING` status and before the 72 hours mark. parameters: - $ref: '#/components/parameters/ConversionDeletionRequestKey' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/ConversionDeletionRequest' '204': description: Resource deleted successfully. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write - client_credentials: - ads:write tags: - conversion_deletion_requests x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/conversion_eqs: get: operationId: conversion_eqs/list summary: Get event quality score (EQS) description: |- Get the Event Quality Score (EQS) of your conversion signals. [Event Quality Score](https://help.pinterest.com/en/business/article/eqs) indicates how effective the customer information and event insights (metadata) passed with your web, app and offline conversion events may be at matching to a Pinterest user. parameters: - $ref: '#/components/parameters/EventQualityScoreListParams.lookback_period' - $ref: '#/components/parameters/EventQualityScoreListParams.source_platform' - $ref: '#/components/parameters/EventQualityScoreListParams.ingestion_source' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: $ref: '#/components/schemas/EventQualityScore' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - conversion_eqs x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/conversion_tags: post: operationId: conversion_tags/create summary: Create conversion tag description: |- Create a conversion tag, also known as [Pinterest tag](https://help.pinterest.com/en/business/article/set-up-the-pinterest-tag), with the option to enable enhanced match. The Pinterest Tag tracks actions people take on the ad account's website after they view the ad account's ad on Pinterest. The advertiser needs to customize this tag to track conversions. For more information, see: [Set up the Pinterest tag](https://help.pinterest.com/en/business/article/set-up-the-pinterest-tag) [Pinterest Tag](/docs/track-conversions/pinterest-tag/) [Enhanced match](/docs/track-conversions/pinterest-tag/#enhanced-match) parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConversionTagCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/ConversionTag' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/ConversionTag' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - conversion_tags x-ratelimit-category: ads_write x-sandbox: disabled get: operationId: conversion_tags/list summary: List conversion tags description: List conversion tags associated with an ad account. parameters: - $ref: '#/components/parameters/query_filter_deleted' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/ConversionTag' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - conversion_tags x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/conversion_tags/ocpm_eligible: get: operationId: ocpm_eligible_conversion_tags/get summary: Get Ocpm eligible conversion tags description: Get Ocpm eligible conversion tag events for an ad account. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/ConversionTagsOcpmEligibleResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - conversion_tags x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/conversion_tags/page_visit: get: operationId: page_visit_conversion_tags/get summary: Get page visit conversion tags description: Get all page visit conversion tag events for an ad account. parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/ConversionEventResponse' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - conversion_tags x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/conversion_tags/{conversion_tag_id}: get: operationId: conversion_tags/get summary: Get conversion tag description: Get information about an existing conversion tag. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/path_conversion_tag_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/ConversionTag' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - conversion_tags x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/customer_lists: get: operationId: customer_lists/list summary: Get customer lists description: |- Get a set of customer lists including id and name based on the filters provided. (Customer lists are a type of audience.) For more information, see [Audience targeting](https://help.pinterest.com/en/business/article/audience-targeting) or the [Audiences](/docs/api-features/targeting-overview/) section of the ads management guide. parameters: - $ref: '#/components/parameters/CustomerListParentKey' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/query_exclude_nca' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/CustomerList' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - customer_lists x-ratelimit-category: ads_read x-sandbox: disabled post: operationId: customer_lists/create summary: Create customer lists description: |- Create a customer list from your records (hashed or plain-text email addresses, or hashed MAIDs or IDFAs). A customer list is one of the four types of Pinterest audiences: for more information, see [Audience targeting](https://help.pinterest.com/en/business/article/audience-targeting) or the [Audiences](/docs/api-features/targeting-overview/) section of the ads management guide. **Please review our [requirements](https://help.pinterest.com/en/business/article/audience-targeting#section-13341) for what type of information is allowed when uploading a customer list.** When you create a customer list, the system scans the list for existing Pinterest accounts; the list must include at least 100 Pinterest accounts. Your original list will be deleted when the matching process is complete. The filtered list – containing only the Pinterest accounts that were included in your starting list – is what will be used to create the audience. To use your customer list after creating it, convert it into a customer list audience by passing the `CUSTOMER_LIST` audience type at the [create audience endpoint](https://developer.pinterest.com/docs/api/v5/audiences-create). parameters: - $ref: '#/components/parameters/CustomerListParentKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomerListCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CustomerList' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/CustomerList' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - customer_lists x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}: get: operationId: customer_lists/get summary: Get customer list description: Gets a specific customer list given the customer list ID. parameters: - $ref: '#/components/parameters/CustomerListKey.id' - $ref: '#/components/parameters/CustomerListKey.customer_list_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CustomerList' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - customer_lists x-ratelimit-category: ads_read x-sandbox: disabled patch: operationId: customer_lists/update summary: Update customer list description: |- Append or remove records to/from an existing customer list. (A customer list is one of the four types of Pinterest audiences.) When you add records to an existing customer list, the system scans the additions for existing Pinterest accounts; those are the records that will be added to your "CUSTOMER_LIST" audience. Your original list of records to add will be deleted when the matching process is complete. For more information, see [Audience targeting](https://help.pinterest.com/en/business/article/audience-targeting) or the [Audiences](/docs/api-features/targeting-overview/) section of the ads management guide. parameters: - $ref: '#/components/parameters/CustomerListKey.id' - $ref: '#/components/parameters/CustomerListKey.customer_list_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomerListUpdateWithRequiredBody' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CustomerList' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - customer_lists x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}/uploads: post: operationId: customer_list_uploads/create summary: Create customer list upload description: |- Create a customer list upload request for multipart S3 upload. Note: Each part must be at least 5mb; however the last part can be any size greater than 0. Clients with smaller files can request a single part count. This minimal part size restriction is defined by the AWS S3 API. **Please review the [update customer list endpoint](/docs/api/v5/customer_lists-update/) documentation for additional information.** parameters: - $ref: '#/components/parameters/CustomerListUploadParentKey.id' - $ref: '#/components/parameters/CustomerListUploadParentKey.customer_list_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomerListUploadCreateRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CustomerListUploadCreateResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - customer_list_uploads x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}/uploads/{customer_list_upload_id}: get: operationId: customer_list_uploads/get summary: Get customer list upload description: Get the metadata for a given upload by its ID. parameters: - $ref: '#/components/parameters/CustomerListUploadKey.id' - $ref: '#/components/parameters/CustomerListUploadKey.customer_list_id' - $ref: '#/components/parameters/CustomerListUploadKey.customer_list_upload_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CustomerListUpload' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - customer_list_uploads x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}/uploads/{customer_list_upload_id}/run: post: operationId: customer_list_uploads/run summary: Run customer list upload description: Begin processing a customer list upload. parameters: - $ref: '#/components/parameters/CustomerListUploadKey.id' - $ref: '#/components/parameters/CustomerListUploadKey.customer_list_id' - $ref: '#/components/parameters/CustomerListUploadKey.customer_list_upload_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CustomerListUpload' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - customer_list_uploads x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/customer_segments: get: operationId: customer_segment/list summary: List customer segments description: Get a list of the customer segments in the specified `ad_account_id`. parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/customer_segments_include_sizing' - $ref: '#/components/parameters/customer_segments_search_query' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/CustomerSegment' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - customer_segment x-ratelimit-category: ads_read x-sandbox: disabled post: operationId: customer_segment/create summary: Create customer segments description: Customer segments allow advertisers to define existing customers for Pinterest Performance+ campaigns. Customer segments are made up of audience lists. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomerSegmentCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CustomerSegment' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/CustomerSegment' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - customer_segment x-ratelimit-category: ads_write x-sandbox: disabled patch: operationId: customer_segment/update summary: Update customer segments description: Update the customer segment given advertiser ID and customer segment ID parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CustomerSegmentUpdateRequestUpdateWithRequiredBody' responses: '200': description: The request has succeeded. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - customer_segment x-ratelimit-category: ads_write x-sandbox: enabled /ad_accounts/{ad_account_id}/events: post: operationId: events/create summary: Send conversions description: |- The Pinterest API offers advertisers a way to send Pinterest their conversion information (including web conversions, in-app conversions, or even offline conversions) based on their `ad_account_id`. The request body should be a JSON object. - This endpoint requires an `access_token` be generated through Ads Manager. Review the [Conversions Guide](/docs/api-features/conversion-overview/) for more details. (Note that the authorization header required is `Authorization: Bearer `). - The token's `user_account` must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Audience, Campaign. (Note that the token can be used across multiple ad accounts under an user ID.) - This endpoint has a rate limit of 5,000 calls per minute per ad account. - If the merchant is submitting this information using both Pinterest conversion tags and the Pinterest API, Pinterest will remove duplicate information before reporting. (Note that events that took place offline cannot be deduplicated.) parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/EventsCreateQueryParams' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConversionEventsCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/ConversionEvents' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '422': description: The request was well-formed but was unable to be followed due to semantic errors. content: application/json: schema: $ref: '#/components/schemas/DetailedError' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '503': description: The server is currently unable to handle the request due to a temporary overload or scheduled maintenance. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write - conversion_token: [] tags: - conversion_events x-ratelimit-category: ads_conversions x-sandbox: disabled /ad_accounts/{ad_account_id}/insights/audiences: get: operationId: audience_insights_scope_and_type/get summary: Get audience insights scope and type description: Get the scope and type of available audiences, which along with a date, is an audience that has recently had an interaction (referred to here as a type) on pins. Interacted pins can belong to at least the most common **partner** or **Pinterest** scopes. This means that user interactions made on advertiser or partner pins will have the **partner** scope. You can also have user interactions performed in general on Pinterest with the **Pinterest** scope. In that case, you can then use the returned type and scope values together on requests to other endpoints to retrieve insight metrics for a desired audience. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/AudienceDefinition' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - audience_insights x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/keywords: get: operationId: keywords/get summary: Get keywords description: |2- Get a list of keywords based on the filters provided. If no filter is provided, it will default to the `ad_account_id` filter, which means it will only return keywords that specifically have `parent_id` set to the `ad_account_id`. Note: Keywords can have `ad_account_ids`, `campaign_ids`, and `ad_group_ids` set as their `parent_ids`. Keywords created through Ads Manager will have their `parent_id` set to an `ad_group_id`, not `ad_account_id`. For more information, see [Keyword targeting](https://help.pinterest.com/en/business/article/keyword-targeting). **Notes:** - Advertisers and campaigns can only be assigned keywords with excluding (`_NEGATIVE`). - All keyword match types are available for ad groups. For more information on match types, see [match type enums](/docs/api-features/targeting-overview/). **Returns:** - A successful call returns an object containing an array of new keyword objects and an empty `errors` object array. - An unsuccessful call returns an empty keywords array, and instead, inserts the entire object with nulled/negated properties into the `errors` object array: ```json { "keywords": [], "errors": [ { "data": { "archived": null, "match_type": "EXACT", "parent_type": null, "value": "foobar", "parent_id": null, "type": "keyword", "id": null }, "error_messages": [ "Advertisers and Campaigns only accept excluded targeting attributes." ] } ] } parameters: - $ref: '#/components/parameters/query_campaign_id' - $ref: '#/components/parameters/query_ad_group_id' - $ref: '#/components/parameters/query_ad_group_ids' - $ref: '#/components/parameters/query_match_types' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/Keyword' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - keywords x-ratelimit-category: ads_read x-sandbox: enabled post: operationId: keywords/create summary: Create keywords description: |2- Create keywords for the following entity types (advertiser, campaign, ad group, or ad). For more information, see [Keyword targeting](https://help.pinterest.com/en/business/article/keyword-targeting). **Notes:** - Advertisers and campaigns can only be assigned keywords with excluding (`_NEGATIVE`). - All keyword match types are available for ad groups. For more information on match types, see [match type enums](/docs/api-features/targeting-overview/). **Returns:** - A successful call returns an object containing an array of new keyword objects and an empty `errors` object array. - An unsuccessful call returns an empty keywords array, and instead, inserts the entire object with nulled/negated properties into the `errors` object array: ```json { "keywords": [], "errors": [ { "data": { "archived": null, "match_type": "EXACT", "parent_type": null, "value": "foobar", "parent_id": null, "type": "keyword", "id": null }, "error_messages": [ "Advertisers and Campaigns only accept excluded targeting attributes." ] } ] } parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/KeywordsCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Keywords' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/Keywords' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - keywords x-ratelimit-category: ads_write x-sandbox: enabled patch: operationId: keywords/update summary: Update keywords description: |2- Update one or more keywords' bid and archived fields. Archiving a keyword effectively deletes it - keywords no longer receive metrics and are no longer visible within the parent entity's keywords list. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/KeywordsUpdate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Keywords' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - keywords x-ratelimit-category: ads_write x-sandbox: enabled /ad_accounts/{ad_account_id}/keywords/metrics: get: operationId: country_keywords_metrics/get summary: Get country's keyword metrics description: |2- See keyword metrics for a specified country, aggregated across all of Pinterest. (Definitions are available from the "Get delivery metrics definitions" [API endpoint](/docs/api/v5/#operation/delivery_metrics/get)). parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/query_country_code' - $ref: '#/components/parameters/query_keywords' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/KeywordsMetricsArrayResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - keywords x-ratelimit-category: ads_read x-sandbox: enabled /ad_accounts/{ad_account_id}/labels: get: operationId: labels/list summary: List labels description: |- [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) See a list of labels for assets that your account owns, and filter the list by different criteria. If no filter is provided, it will default to labels associated with the ad account id. parameters: - $ref: '#/components/parameters/query_campaign_ids' - $ref: '#/components/parameters/query_label_ids' - $ref: '#/components/parameters/query_label_entity_statuses' - $ref: '#/components/parameters/query_label_types' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/Label' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - labels x-ratelimit-category: ads_read x-sandbox: enabled post: operationId: labels/create summary: Create labels description: |- [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Apply one or more labels to a campaign. Future releases may support labels for other [entities](/docs/key-concepts/pinterest-entities/). Currently, you can apply brand and custom labels. Future releases will provide more options. **Note:** You can only apply one brand label to a campaign. You can apply 30 custom labels to a campaign. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LabelCreateRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/LabelsResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - labels x-ratelimit-category: ads_write x-sandbox: enabled patch: operationId: labels/update summary: Update labels description: |- [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Change the properties of one or more labels. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LabelUpdateRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/LabelsResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - labels x-ratelimit-category: ads_write x-sandbox: enabled /ad_accounts/{ad_account_id}/labels/{label_id}/apply: post: operationId: labels/apply summary: Apply label to entity description: |2- [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Apply a label to one or more campaigns. Future releases may support labels for other [entities](/docs/key-concepts/pinterest-entities/) in addition to campaigns. Currently, you can apply **brand** and **custom** labels. Future releases will provide more options. **Note:** You can only apply one brand label to a campaign. You can apply up to 30 custom labels to a campaign. parameters: - $ref: '#/components/parameters/LabeledEntitiesKey.id' - $ref: '#/components/parameters/LabeledEntitiesKey.label_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LabeledEntitiesCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/LabeledEntities' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/LabeledEntities' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - labels x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/labels/{label_id}/remove: post: operationId: labels/remove summary: Remove label from entities description: |2- [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Remove a label from one or more entities. parameters: - $ref: '#/components/parameters/LabeledEntitiesKey.id' - $ref: '#/components/parameters/LabeledEntitiesKey.label_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LabeledEntitiesCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/LabeledEntities' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/LabeledEntities' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - labels x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/lead_forms: get: operationId: lead_forms/list summary: List lead forms description: |- **This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.** List lead forms associated with an ad account ID. For more, see [Lead ads](https://help.pinterest.com/en/business/article/lead-ads). parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/LeadForm' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - lead_forms x-ratelimit-category: ads_read x-sandbox: enabled post: operationId: lead_forms/create summary: Create lead forms description: |- **This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.** Create lead forms. Lead forms are used in lead ads and allow you to control what text appears on the lead form's description, questions and confirmation sections. For more, see [Lead ads](https://help.pinterest.com/en/business/article/lead-ads). parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LeadFormsCreateBody' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: items: type: array items: type: object properties: data: $ref: '#/components/schemas/LeadForm' exceptions: type: array items: $ref: '#/components/schemas/Pinterest.Lib.BatchItemException' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - lead_forms x-ratelimit-category: ads_write x-sandbox: disabled patch: operationId: lead_forms/update summary: Update lead forms description: |- **This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.** Update lead forms. Lead ads help you reach people who are actively looking for, and interested in, your goods and services. The lead form can be associated with an ad to allow people to fill out the form. For more, see [Lead ads](https://help.pinterest.com/en/business/article/lead-ads). parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LeadFormsUpdateBody' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: items: type: array items: type: object properties: data: $ref: '#/components/schemas/LeadForm' exceptions: type: array items: $ref: '#/components/schemas/Pinterest.Lib.BatchItemException' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - lead_forms x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/lead_forms/{lead_form_id}: get: operationId: lead_form/get summary: Get lead form by id description: |- **This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.** Gets a lead form given it's ID. It must also be associated with the provided ad account ID. For more, see [Lead ads](https://help.pinterest.com/en/business/article/lead-ads). parameters: - $ref: '#/components/parameters/LeadFormKey' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/LeadForm' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - lead_forms x-ratelimit-category: ads_read x-sandbox: enabled /ad_accounts/{ad_account_id}/lead_forms/{lead_form_id}/test: post: operationId: lead_form_test/create summary: Create lead form test data description: |- Create lead form test data based on the list of answers provided as part of the body. - List of answers should follow the questions creation order. parameters: - $ref: '#/components/parameters/LeadFormTestKey.id' - $ref: '#/components/parameters/LeadFormTestKey.lead_form_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LeadFormTestCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/LeadFormTest' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - lead_forms x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/leads/subscriptions: get: operationId: ad_accounts_subscriptions/get_list summary: Get lead ads subscriptions description: Get the advertiser's list of lead ads subscriptions. Only requests for the OWNER or ADMIN of the ad_account will be allowed. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/LeadSubscription' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - lead_ads x-ratelimit-category: ads_read x-sandbox: disabled post: operationId: ad_accounts_subscriptions/post summary: Create lead ads subscription description: |- Create a lead ads webhook subscription. Subscriptions allow Pinterest to deliver lead data from Ads Manager directly to the subscriber. Subscriptions can exist for a specific lead form or at ad account level. - Only requests for the OWNER or ADMIN of the ad_account will be allowed. - Advertisers can set up multiple integrations using ad_account_id + lead_form_id but only one integration per unique records. - For data security, egress lead data is encrypted with AES-256-GCM. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LeadSubscriptionPostParamsCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/LeadSubscription' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - lead_ads x-ratelimit-category: ads_write x-sandbox: enabled /ad_accounts/{ad_account_id}/leads/subscriptions/{subscription_id}: get: operationId: ad_accounts_subscriptions/get_by_id summary: Get lead ads subscription by ID description: |- Get an existing lead ads webhook subscription by ID. - Only requests for the OWNER or ADMIN of the ad_account will be allowed.' parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/SubscriptionIdPathParam' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/LeadSubscription' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - lead_ads x-ratelimit-category: ads_read x-sandbox: disabled delete: operationId: ad_accounts_subscriptions/del_by_id summary: Delete lead ads subscription description: |- Delete an existing lead ads webhook subscription by ID. - Only requests for the OWNER or ADMIN of the ad_account will be allowed.' parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/SubscriptionIdPathParam' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/LeadSubscription' '204': description: Resource deleted successfully. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - lead_ads x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/leads_export: post: operationId: leads_export/create summary: Create a request to export leads collected from a lead ad description: |- **This feature is currently in beta and not available to all apps. If you're interested in joining the beta, please reach out to your Pinterest account manager.** Create an export of leads collected from a lead ad. This returns a `leads_export_id` token that you can use to download the export when it is ready. Note: Lead ad data will be available up to 30 days after the lead has been submitted. For more, see [Lead ads](https://help.pinterest.com/en/business/article/lead-ads). parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LeadsExportsCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/LeadsExports' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/LeadsExports' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - leads_export x-ratelimit-category: ads_write x-sandbox: enabled /ad_accounts/{ad_account_id}/leads_export/{leads_export_id}: get: operationId: leads_export/get summary: Get the lead export from the lead export create call description: |- **This feature is currently in beta and not available to all apps. If you're interested in joining the beta, please reach out to your Pinterest account manager.** Get the export of leads collected from a lead ad. This returns a URL to a list of lead export given a lead_export_id token returned from the create a lead export call. You can use the URL to download the report. Note: Lead ad data will be available up to 30 days after the lead has been submitted. For more, see [Lead ads](https://help.pinterest.com/en/business/article/lead-ads). parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/path_leads_export_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/LeadsExportResponseData' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - leads_export x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/mmm_reports: get: operationId: analytics/get_mmm_report summary: Get advertiser Marketing Mix Modeling (MMM) report. description: |2- Get an mmm report for an ad account. This returns a URL to an mmm metrics report given a token returned from the create mmm report endpoint. parameters: - $ref: '#/components/parameters/MMMReportKey' - $ref: '#/components/parameters/query_token_required' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/MMMReport' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - ad_accounts x-ratelimit-category: ads_read x-sandbox: disabled post: operationId: analytics/create_mmm_report summary: Create a request for a Marketing Mix Modeling (MMM) report description: |2- This creates an asynchronous mmm report based on the given request. It returns a token that you can use to download the report when it is ready. NOTE: An additional limit of 5 queries per minute per advertiser applies to this endpoint while it's in beta release. For the ADVERTISER_PAID_SPEND_IN_DOLLAR, ADVERTISER_PAID_ECPC_IN_DOLLAR, and ADVERTISER_PAID_ECPM_IN_DOLLAR columns: if you receive bonus media, this value still includes that spend, and it will need to be removed manually with support from your Pinterest account team for a fully netted value. Over time, we'll also subtract bonus media and other incentives as data becomes available. Production and other non-media fees are excluded. parameters: - $ref: '#/components/parameters/MMMReportKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MMMReportCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/MMMReport' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/MMMReport' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - ad_accounts x-ratelimit-category: ads_analytics x-sandbox: disabled /ad_accounts/{ad_account_id}/msot/events: post: operationId: msot_events/create summary: Send Measurement Source Of Truth (MSOT) attributed conversion events description: |- **This feature is currently in beta and not available to all apps.** If you are interested in joining the beta, reach out to your Pinterest account manager. Advertisers or their measurement partners can send attributed MSOT conversion events to Pinterest based on their `ad_account_id`. The request body should be a JSON object. - These events will not be used in Reporting. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConversionMSOTEventsCreate' responses: '200': description: The request has succeeded. '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/ConversionMSOTEvents' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - msot:write tags: - msot_events x-ratelimit-category: msot_write x-sandbox: disabled /ad_accounts/{ad_account_id}/order_lines: get: operationId: order_lines/list summary: Get order lines. description: List existing order lines associated with an ad account. parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/OrderLine' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - order_lines x-ratelimit-category: ads_read x-sandbox: enabled /ad_accounts/{ad_account_id}/order_lines/{order_line_id}: get: operationId: order_lines/get summary: Get order line description: Get a specific existing order line associated with an ad account. parameters: - $ref: '#/components/parameters/OrderLineKey' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/OrderLine' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - order_lines x-ratelimit-category: ads_read x-sandbox: enabled /ad_accounts/{ad_account_id}/pins/analytics: get: operationId: ad_pins/analytics summary: Get pins analytics description: |- Get analytics for the pins given a campaign and pins in the specified `ad_account_id`, filtered by the specified options. - The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Campaign Manager. - If granularity is not HOUR, the furthest back you can are allowed to pull data is 90 days before the current date in UTC time and the max time range supported is 90 days. - If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days. Data will not be provided for conversion metrics but will be available for non-conversion metrics. parameters: - $ref: '#/components/parameters/query_campaign_id_required' - $ref: '#/components/parameters/query_required_pin_ids' - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_columns' - $ref: '#/components/parameters/query_granularity' - $ref: '#/components/parameters/query_conversion_attribution_click_window_days' - $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days' - $ref: '#/components/parameters/query_conversion_attribution_view_window_days' - $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: $ref: '#/components/schemas/AdPinAnalytics' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - campaigns x-ratelimit-category: ads_analytics x-sandbox: disabled /ad_accounts/{ad_account_id}/product_group_promotions: post: operationId: product_group_promotions/create summary: Create product group promotions description: Add one or more product groups from your catalog to an existing ad group. (Product groups added to an ad group are a 'product group promotion.') parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProductGroupPromotionsCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/ProductGroupPromotions' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/ProductGroupPromotions' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - product_group_promotions x-ratelimit-category: ads_write x-sandbox: disabled patch: operationId: product_group_promotions/update summary: Update product group promotions description: Update multiple existing Product Group Promotions (by product_group_id) parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProductGroupPromotionsUpdateWithRequiredBody' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/ProductGroupPromotions' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - product_group_promotions x-ratelimit-category: ads_write x-sandbox: disabled get: operationId: product_group_promotions/list summary: Get product group promotions description: |- List existing product group promotions associated with an ad account. Include either ad_group_id or product_group_promotion_ids in your request. **Note:** ad_group_ids and product_group_promotion_ids are mutually exclusive parameters. Only provide one. If multiple options are provided, product_group_promotion_ids takes precedence over ad_group_ids. If none are provided, the endpoint returns an error. parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/product_group_promotions_list_query.product_group_promotion_ids' - $ref: '#/components/parameters/product_group_promotions_list_query.entity_statuses' - $ref: '#/components/parameters/query_ad_group_id' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/ProductGroupPromotion' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - product_group_promotions x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/product_group_promotions/{product_group_promotion_id}: get: operationId: product_group_promotions/get summary: Get a product group promotion by id description: Get a product group promotion by id parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/path_product_group_promotion_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/ProductGroupPromotion' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - product_group_promotions x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/product_groups/analytics: get: operationId: product_groups/analytics summary: Get product group analytics description: |- Get analytics for the specified product groups in the specified `ad_account_id`, filtered by the specified options. - The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Campaign Manager. - If granularity is not HOUR, you can pull data from up to 90 days before the current date in UTC time, with a maximum time range of 90 days. - If granularity is HOUR, you can pull data from up to 8 days before the current date in UTC time, with a maximum time range of 3 days. parameters: - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_product_group_ids_required' - $ref: '#/components/parameters/query_columns' - $ref: '#/components/parameters/query_granularity' - $ref: '#/components/parameters/query_conversion_attribution_click_window_days' - $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days' - $ref: '#/components/parameters/query_conversion_attribution_view_window_days' - $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time' - $ref: '#/components/parameters/query_reporting_timezone' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: $ref: '#/components/schemas/ProductGroupAnalyticsItems' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - product_group_promotions x-ratelimit-category: ads_analytics x-sandbox: disabled /ad_accounts/{ad_account_id}/promotion_applied_entities: get: operationId: get_ad_groups_by_promotion_ids/list summary: List of ad groups using promotions IDs. description: ' Get a list of ad groups that are associated with those promotion ids' parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/query_promotion_ids' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/AdGroup' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - ad_groups x-ratelimit-category: ads_read x-sandbox: disabled /ad_accounts/{ad_account_id}/promotions: get: operationId: promotions/list summary: Get promotions description: |- Gets all promotions associated with an ad account ID that can be applied to an ad group. Can be either internally-saved promotions or external promotions imported from a commerce integration. parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/Promotion' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - promotions x-ratelimit-category: ads_read x-sandbox: disabled post: operationId: promotions/create summary: Create promotions description: Create multiple new promotions. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PromotionCreateBatch' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/PromotionsResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - promotions x-ratelimit-category: ads_write x-sandbox: disabled patch: operationId: promotions/update summary: Update promotions description: Update multiple promotions. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PromotionUpdateBatch' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/PromotionsResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - promotions x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/promotions/{promotion_id}: get: operationId: promotions/get summary: Get promotion by id description: Get a promotion by its Pinterest-specific id. It must be associated with the provided ad account id. parameters: - $ref: '#/components/parameters/PromotionKey' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Promotion' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - promotions x-ratelimit-category: ads_read x-sandbox: disabled delete: operationId: promotions/delete summary: Delete promotion by id description: Delete a promotion within Pinterest. parameters: - $ref: '#/components/parameters/PromotionKey' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Promotion' '204': description: Resource deleted successfully. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - promotions x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/reports: get: operationId: analytics/get_report summary: Get the account analytics report created by the async call description: |2- This returns a URL to an analytics report given a token returned from the post request report creation call. You can use the URL to download the report. The link is valid for five minutes and the report is valid for one hour. - The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Campaign Manager. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/query_report_token_required' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdsAnalyticsGetAsyncResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - ad_accounts x-ratelimit-category: ads_analytics x-sandbox: disabled post: operationId: analytics/create_report summary: Create async request for an account analytics report description: |2- This returns a token that you can use to download the report when it is ready. Note that this endpoint requires the parameters to be passed as JSON-formatted in the request body. This endpoint does not support URL query parameters. - The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Campaign Manager. - If granularity is not HOUR, you can pull data from up to 914 days before the current date in UTC time, with a maximum time range of 186 days. - If granularity is HOUR, you can pull data from up to 8 days before the current date in UTC time, with a maximum time range of 3 days. - If level is PRODUCT_ITEM, you can pull data from up to 92 days before the current date in UTC time, with a maximum time range of 31 days. - If level is PRODUCT_ITEM, ad_ids and ad_statuses parameters are not allowed. Any columns related to pin promotion and ad is not allowed either. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdsAnalyticsCreateAsyncRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdsAnalyticsCreateAsyncResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - ad_accounts x-ratelimit-category: ads_analytics x-sandbox: disabled /ad_accounts/{ad_account_id}/reports/brand_category_sku: get: operationId: analytics/get_conversion_product_report summary: Get advertiser brand, category, SKU report description: |2- [Restricted](/docs/getting-started/using-beta-and-restricted-features/) Get a brand, category, SKU report for an ad account. This call returns the URL for the report that matches the token returned in the request to the Create brand, category, SKU report endpoint. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/query_report_token_required' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/ConversionProductReport' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - ad_accounts x-ratelimit-category: ads_read x-sandbox: disabled post: operationId: analytics/create_conversion_product_report summary: Create a request for a brand, category, SKU report description: |2- [Restricted](/docs/getting-started/using-beta-and-restricted-features/) This creates an asynchronous brand, category, SKU report based on the given request. This request returns a token that you can use to download the report when it is ready. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ConversionProductReportCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/ConversionProductReport' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/ConversionProductReport' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - ad_accounts x-ratelimit-category: ads_analytics x-sandbox: disabled /ad_accounts/{ad_account_id}/sandbox: delete: operationId: sandbox/delete summary: Delete ads data for ad account in API Sandbox description: |- Delete an ad account and all the ads data associated with that account. A string message is returned indicating the status of the delete operation. Note: This endpoint is only allowed in the Pinterest API Sandbox (https://api-sandbox.pinterest.com/v5). Go to /docs/developer-tools/sandbox/ for more information. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: string '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - ad_accounts x-ratelimit-category: ads_write x-sandbox: enabled /ad_accounts/{ad_account_id}/schedules: get: operationId: schedules/list summary: Get Schedules description: Get schedules for a specific advertiser parameters: - $ref: '#/components/parameters/ScheduleParentKey' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/SchedulesFilters.schedule_statuses' - $ref: '#/components/parameters/SchedulesFilters.schedule_type' - $ref: '#/components/parameters/SchedulesFilters.entity_ids' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/Schedule' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - schedules x-ratelimit-category: ads_read x-sandbox: disabled post: operationId: schedules/create summary: Create schedules description: Batch create schedules parameters: - $ref: '#/components/parameters/ScheduleParentKey' requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/ScheduleCreate' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: type: object required: - data properties: data: description: Created/updated resource on success or error details on failure oneOf: - $ref: '#/components/schemas/Schedule' - type: object required: - id - schedule_id - exceptions properties: id: type: string maxLength: 18 pattern: ^\d+$ schedule_id: description: Schedule ID. type: string pattern: ^\d+$ exceptions: $ref: '#/components/schemas/Pinterest.Lib.Error' '201': description: Resource create operation completed successfully. content: application/json: schema: type: array items: $ref: '#/components/schemas/Schedule' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - schedules x-ratelimit-category: ads_write x-sandbox: disabled patch: operationId: schedules/update summary: Update schedules description: Update one or more schedules parameters: - $ref: '#/components/parameters/ScheduleParentKey' requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/ScheduleBatchUpdate' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: type: object required: - data properties: data: description: Created/updated resource on success or error details on failure oneOf: - $ref: '#/components/schemas/Schedule' - type: object required: - id - schedule_id - exceptions properties: id: type: string maxLength: 18 pattern: ^\d+$ schedule_id: description: Schedule ID. type: string pattern: ^\d+$ exceptions: $ref: '#/components/schemas/Pinterest.Lib.Error' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - schedules x-ratelimit-category: ads_write x-sandbox: disabled /ad_accounts/{ad_account_id}/ssio/accounts: get: operationId: ssio_accounts/get summary: Get Salesforce account details including bill-to information. description: |2- Get Salesforce account details including bill-to information to be used in insertion orders process for `ad_account_id`. - The token's `user_account` must either be the owner of the specified ad account, or have one of the necessary roles granted via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Finance, Campaign. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/SSIOAccount' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - billing x-ratelimit-category: ads_read x-sandbox: enabled /ad_accounts/{ad_account_id}/ssio/insertion_orders: post: operationId: ssio_insertion_order/create summary: Create insertion order through SSIO. description: |2- Create insertion order through SSIO for `ad_account_id`. - The token's `user_account` must either be the owner of the specified ad account, or have one of the necessary roles granted via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Finance, Campaign. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SSIOInsertionOrderCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/SSIOInsertionOrder' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/SSIOInsertionOrder' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - billing x-ratelimit-category: ads_write x-sandbox: enabled patch: operationId: ssio_insertion_order/edit summary: Edit insertion order through SSIO. description: |2- Edit insertion order through SSIO for `ad_account_id`. - The token's `user_account` must either be the owner of the specified ad account, or have one of the necessary roles granted via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Finance, Campaign. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SSIOInsertionOrderUpdate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/SSIOInsertionOrder' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - billing x-ratelimit-category: ads_write x-sandbox: enabled /ad_accounts/{ad_account_id}/ssio/insertion_orders/status: get: operationId: ssio_insertion_orders_status/get_by_ad_account summary: Get insertion order status by ad account id. description: |2- Get insertion order status for `ad_account_id`. - The token's `user_account` must either be the owner of the specified ad account, or have one of the necessary roles granted via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Finance, Campaign. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/SSIOInsertionOrderStatus' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - billing x-ratelimit-category: ads_read x-sandbox: enabled /ad_accounts/{ad_account_id}/ssio/insertion_orders/{pin_order_id}/status: get: operationId: ssio_insertion_orders_status/get_by_pin_order_id summary: Get insertion order status by pin order id. description: |2- Get insertion order status for `pin_order_id`. - The token's `user_account` must either be the owner of the specified ad account, or have one of the necessary roles granted via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Finance, Campaign. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/path_pin_order_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/SSIOInsertionOrderStatusResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - billing x-ratelimit-category: ads_read x-sandbox: enabled /ad_accounts/{ad_account_id}/ssio/order_lines: get: operationId: ssio_order_lines/get_by_ad_account summary: Get Salesforce order lines by ad account id. description: |2- Get Salesforce order lines for account id `ad_account_id`. - The token's `user_account` must either be the owner of the specified ad account, or have one of the necessary roles granted via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Finance, Campaign. parameters: - $ref: '#/components/parameters/query_pin_order_id' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/SSIOOrderLine' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - billing x-ratelimit-category: ads_read x-sandbox: enabled /ad_accounts/{ad_account_id}/targeting_analytics: get: operationId: ad_account_targeting_analytics/get summary: Get targeting analytics for an ad account description: |- Get targeting analytics for an ad account. For the requested account and metrics, the response will include the requested metric information (e.g. SPEND_IN_DOLLAR) for the requested target type (e.g. "age_bucket") for applicable values (e.g. "45-49").

* The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts): Admin, Analyst, Campaign Manager. * If granularity is not HOUR, you can pull data from up to 90 days before the current date in UTC time, with a maximum time range of 90 days. * If granularity is HOUR, you can pull data from up to 8 days before the current date in UTC time, with a maximum time range of 3 days. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_ad_account_targeting_types' - $ref: '#/components/parameters/query_columns' - $ref: '#/components/parameters/query_granularity' - $ref: '#/components/parameters/query_conversion_attribution_click_window_days' - $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days' - $ref: '#/components/parameters/query_conversion_attribution_view_window_days' - $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time' - $ref: '#/components/parameters/query_attribution_types' - $ref: '#/components/parameters/query_reporting_timezone' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/MetricsResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - ad_accounts x-ratelimit-category: ads_analytics x-sandbox: enabled /ad_accounts/{ad_account_id}/targeting_templates: get: operationId: targeting_template/list summary: List targeting templates description: Get a list of the targeting templates in the specified `ad_account_id` parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/TargetingTemplatesListParams.include_sizing' - $ref: '#/components/parameters/TargetingTemplatesListParams.search_query' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/TargetingTemplate' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - targeting_template x-ratelimit-category: ads_read x-sandbox: disabled post: operationId: targeting_template/create summary: Create targeting templates description: |- Targeting templates allow advertisers to save a set of targeting details including audience lists, keywords & interest, demographics, and placements to use more than once during the campaign creation process. Templates can be used to build out basic targeting criteria that you plan to use across campaigns and to reuse performance targeting from prior campaigns for new campaigns. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TargetingTemplateCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/TargetingTemplate' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/TargetingTemplate' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - targeting_template x-ratelimit-category: ads_write x-sandbox: disabled patch: operationId: targeting_template/update summary: Update targeting templates description: Update the targeting template given advertiser ID and targeting template ID parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/TargetingTemplateUpdateRequestReadOrUpdate' responses: '200': description: The request has succeeded. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - targeting_template x-ratelimit-category: ads_write x-sandbox: enabled /ad_accounts/{ad_account_id}/templates: get: operationId: templates/list summary: List templates description: Gets all Templates associated with an ad account ID. parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/Pinterest.Lib.OrderingParams' - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/AccountTemplate' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - ad_accounts x-ratelimit-category: ads_read x-sandbox: enabled /ad_accounts/{ad_account_id}/templates/{template_id}/reports: post: operationId: analytics/create_template_report summary: Create async request for an analytics report using a template description: |2- This takes a template ID and an optional custom timeframe and constructs an asynchronous report based on the template. It returns a token that you can use to download the report when it is ready. parameters: - $ref: '#/components/parameters/TemplateBasedReportKey.id' - $ref: '#/components/parameters/TemplateBasedReportKey.template_id' - $ref: '#/components/parameters/query_start_date_async' - $ref: '#/components/parameters/query_end_date_async' - $ref: '#/components/parameters/query_granularity_async' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/TemplateBasedReport' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/TemplateBasedReport' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - ad_accounts x-ratelimit-category: ads_analytics x-sandbox: disabled /ad_accounts/{ad_account_id}/terms_of_service: get: operationId: terms_of_service/get summary: Get terms of service description: Get the text of the terms of service and see whether the advertiser has accepted the terms of service. parameters: - $ref: '#/components/parameters/Pinterest.Lib.AdAccountId' - $ref: '#/components/parameters/terms_of_service_query_params.include_html' - $ref: '#/components/parameters/terms_of_service_query_params.tos_type' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/TermsOfService' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - terms_of_service x-ratelimit-category: ads_read x-sandbox: enabled /advanced_auction/items/get: post: operationId: advanced_auction_items_get/post summary: Get item bid options (POST) description: |- Get the bid options for a batch of retail catalog items. The catalog must be owned by the "operation user_account". [See detailed documentation here.](/docs/api-features/shopping-overview/#Update%20items%20in%20batch) By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: `Owner`, `Admin`. This endpoint is not available to all users. parameters: - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdvancedAuctionItemsGetRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdvancedAuctionItems' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '500': description: The server encountered an unexpected condition that prevented it from fulfilling the request. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - catalogs:read tags: - advanced_auction x-ratelimit-category: advanced_auction_read x-sandbox: enabled /advanced_auction/items/submit: post: operationId: advanced_auction_items_submit/post summary: Operate on item level bid options description: |- This endpoint supports multiple operations on a set of one or more bid options (bid price and bid adjustments for targeting categories) for retail catalog items. These advanced auction settings are applied in campaigns using objective_type `CATALOG_SALES` and ad groups using bid_strategy_type `MAX_BID`. The catalog must be owned by the "operation user_account". [See detailed documentation here.](/docs/api-features/modify-items-in-batch/) By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: `Owner`, `Admin`. This endpoint is not available to all users. parameters: - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AdvancedAuctionItemsSubmitRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AdvancedAuctionProcessedItems' '206': description: Successful content: application/json: schema: $ref: '#/components/schemas/AdvancedAuctionProcessedItems' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '500': description: The server encountered an unexpected condition that prevented it from fulfilling the request. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write - catalogs:read tags: - advanced_auction x-ratelimit-category: advanced_auction_write x-sandbox: enabled /boards: post: operationId: boards/create summary: Create board description: |- Create a board owned by the "operation user_account". Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". * By default, the "operation user_account" is the token user_account. parameters: - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BoardCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Board' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/Board' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - boards:write - client_credentials: - boards:read - boards:write tags: - boards x-ratelimit-category: org_write x-sandbox: enabled get: operationId: boards/list summary: List boards description: |- Get a list of the boards owned by the "operation user_account" + group boards where this account is a collaborator Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". Optional: Specify a privacy type (public, protected, or secret) to indicate which boards to return. * If no privacy is specified, all boards that can be returned (based on the scopes of the token and ad_account role if applicable) will be returned. parameters: - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/query_board_privacy' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/Board' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - client_credentials: - boards:read tags: - boards x-ratelimit-category: org_read x-sandbox: enabled /boards/{board_id}: get: operationId: boards/get summary: Get board description: |- Get a board owned by the operation user_account - or a group board that has been shared with this account. * Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". * By default, the "operation user_account" is the token user_account. parameters: - $ref: '#/components/parameters/BoardKey' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Board' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - client_credentials: - boards:read tags: - boards x-ratelimit-category: org_read x-sandbox: enabled delete: operationId: boards/delete summary: Delete board description: |- Delete a board owned by the "operation user_account". * Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". * By default, the "operation user_account" is the token user_account. parameters: - $ref: '#/components/parameters/BoardKey' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Board' '204': description: Resource deleted successfully. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - boards:write tags: - boards x-ratelimit-category: org_write x-sandbox: enabled patch: operationId: boards/update summary: Update board description: |- Update a board owned by the "operating user_account". * Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". * By default, the "operation user_account" is the token user_account. parameters: - $ref: '#/components/parameters/BoardWithUpdatePrivacyKey' - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BoardWithUpdatePrivacyUpdate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/BoardWithUpdatePrivacy' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - boards:write - client_credentials: - boards:read - boards:write tags: - boards x-ratelimit-category: org_write x-sandbox: enabled /boards/{board_id}/pins: get: operationId: boards/list_pins summary: List Pins on board description: |- Get a list of the Pins on a board owned by the "operation user_account" - or on a group board that has been shared with this account. - Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". - By default, the "operation user_account" is the token user_account. parameters: - $ref: '#/components/parameters/path_board_id' - $ref: '#/components/parameters/query_creative_types' - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/query_pin_metrics' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/PinRead' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - pins:read - client_credentials: - boards:read - pins:read tags: - boards x-ratelimit-category: org_read x-sandbox: enabled /boards/{board_id}/sections: get: operationId: board_sections/list summary: List board sections description: |- Get a list of all board sections from a board owned by the "operation user_account" - or a group board that has been shared with this account. Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". - By default, the "operation user_account" is the token user_account. parameters: - $ref: '#/components/parameters/path_board_id' - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/BoardSection' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - client_credentials: - boards:read tags: - boards x-ratelimit-category: org_read x-sandbox: enabled post: operationId: board_sections/create summary: Create board section description: |- Create a board section on a board owned by the "operation user_account" - or on a group board that has been shared with this account. Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". - By default, the "operation user_account" is the token user_account. parameters: - $ref: '#/components/parameters/path_board_id' - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BoardSectionCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/BoardSection' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/BoardSection' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - boards:write tags: - boards x-ratelimit-category: org_write x-sandbox: enabled /boards/{board_id}/sections/{section_id}: delete: operationId: board_sections/delete summary: Delete board section description: |- Delete a board section on a board owned by the "operation user_account" - or on a group board that has been shared with this account. Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". - By default, the "operation user_account" is the token user_account. parameters: - $ref: '#/components/parameters/path_board_id' - $ref: '#/components/parameters/path_board_section_id' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/BoardSection' '204': description: Resource deleted successfully. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - boards:write tags: - boards x-ratelimit-category: org_write x-sandbox: enabled patch: operationId: board_sections/update summary: Update board section description: |- Update a board section on a board owned by the "operation user_account" - or on a group board that has been shared with this account. Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". - By default, the "operation user_account" is the token user_account. parameters: - $ref: '#/components/parameters/path_board_id' - $ref: '#/components/parameters/path_board_section_id' - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BoardSectionUpdateWithRequiredBody' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/BoardSection' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - boards:write tags: - boards x-ratelimit-category: org_write x-sandbox: enabled /boards/{board_id}/sections/{section_id}/pins: get: operationId: board_sections/list_pins summary: List Pins on board section description: |- Get a list of the Pins on a board section of a board owned by the "operation user_account" - or on a group board that has been shared with this account. Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". - By default, the "operation user_account" is the token user_account. parameters: - $ref: '#/components/parameters/path_board_id' - $ref: '#/components/parameters/path_board_section_id' - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/PinRead' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - pins:read - client_credentials: - boards:read - pins:read tags: - boards x-ratelimit-category: org_read x-sandbox: enabled /business_access/business_hierarchy/{business_hierarchy_id}/brand_accounts: post: operationId: brand_accounts/create summary: Create a Brand Account description: Create a Brand Account that will be a child business of a business hierarchy. Request must contain name, username, and country. parameters: - $ref: '#/components/parameters/path_business_hierarchy_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BrandAccountCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/BrandAccount' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/BrandAccount' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read - biz_access:write tags: - business_access_relationships x-ratelimit-category: ads_write x-sandbox: disabled /business_access/business_hierarchy/{business_hierarchy_id}/brand_accounts/{brand_account_id}: patch: operationId: brand_accounts/update summary: Update a Brand Account description: Update an existing Brand Account parameters: - $ref: '#/components/parameters/BrandAccountKey' - $ref: '#/components/parameters/path_business_hierarchy_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BrandAccountUpdate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/BrandAccount' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '409': description: The request could not be processed because of a conflict in the current state of the resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read - biz_access:write tags: - business_access_relationships x-ratelimit-category: ads_write x-sandbox: disabled /businesses/employers: get: operationId: get/business_employers summary: List business employers for user description: Get all of the viewing user's business employers. parameters: - $ref: '#/components/parameters/query_assets_summary_default_true' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/UserBusinessRoleBinding' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read tags: - business_access_relationships x-ratelimit-category: ads_read x-sandbox: enabled /businesses/invites: patch: operationId: respond_business_access_invites summary: Accept or decline an invite/request description: Accept or decline invites or requests. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AuthRespondInvitesBody' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/RespondToInvitesResponseArray' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read - biz_access:write tags: - business_access_invite x-ratelimit-category: ads_write x-sandbox: enabled /businesses/{business_id}/asset_groups: post: operationId: asset_group/create summary: Create a new asset group. description: |- Create a new asset group with the specified parameters. - An [asset group](https://help.pinterest.com/en/business/article/asset-groups) is a custom group of assets based on how you would like to manage your accounts. parameters: - $ref: '#/components/parameters/path_business_user' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssetGroupInputCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AssetGroupInput' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/AssetGroupInput' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read - biz_access:write tags: - business_access_assets x-ratelimit-category: ads_write x-sandbox: disabled patch: operationId: asset_group/update summary: Update asset groups. description: Update a batch of asset groups with the specified parameters. parameters: - $ref: '#/components/parameters/path_business_user' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssetGroupModificationReadOrUpdate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AssetGroupModification' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read - biz_access:write tags: - business_access_assets x-ratelimit-category: ads_write x-sandbox: disabled delete: operationId: asset_group/delete summary: Delete asset groups. description: Delete a batch of asset groups. parameters: - $ref: '#/components/parameters/path_business_user' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AssetGroupDeletionDelete' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AssetGroupDeletion' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read - biz_access:write tags: - business_access_assets x-ratelimit-category: ads_write x-sandbox: disabled /businesses/{business_id}/assets: get: operationId: business_assets/get summary: List business assets description: Get all the assets the requesting business has access to. This includes assets the business owns and assets the business has access to through partnerships. parameters: - $ref: '#/components/parameters/path_business_user' - $ref: '#/components/parameters/query_permissions_with_owner' - $ref: '#/components/parameters/query_child_asset_id' - $ref: '#/components/parameters/query_asset_group_id' - $ref: '#/components/parameters/query_resource_type' - $ref: '#/components/parameters/query_business_access_start_index' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/BusinessAssets' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read tags: - business_access_assets x-ratelimit-category: ads_read x-sandbox: disabled /businesses/{business_id}/assets/{asset_id}/members: get: operationId: business_asset_members/get summary: Get members with access to asset description: Get all the members the requesting business has granted access to on the given asset. parameters: - $ref: '#/components/parameters/path_business_user' - $ref: '#/components/parameters/path_asset_id' - $ref: '#/components/parameters/query_business_access_start_index' - $ref: '#/components/parameters/query_fetch_system_users' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/UserSingleAssetBinding' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read tags: - business_access_assets x-ratelimit-category: ads_read x-sandbox: disabled /businesses/{business_id}/assets/{asset_id}/partners: get: operationId: business_asset_partners/get summary: Get partners with access to asset description: |- Get all the partners the requesting business has granted access to on the given asset. Note: If the asset has been shared with you, an empty array will be returned. This is because an asset shared with you cannot be shared with a different partner. parameters: - $ref: '#/components/parameters/path_business_user' - $ref: '#/components/parameters/path_asset_id' - $ref: '#/components/parameters/query_business_access_start_index' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/UserSingleAssetBinding' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read tags: - business_access_assets x-ratelimit-category: ads_read x-sandbox: disabled /businesses/{business_id}/audiences: get: operationId: shared_audiences_for_business/list summary: List received audiences for a business description: Get a list of received audiences for the given business. parameters: - $ref: '#/components/parameters/path_business_user' - $ref: '#/components/parameters/query_order' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/Audience' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read tags: - audience_sharing x-ratelimit-category: ads_read x-sandbox: disabled /businesses/{business_id}/audiences/ad_accounts/shared: patch: operationId: update_business_to_ad_account_shared_audience summary: Update audience sharing from a business to ad accounts description: |- From a business, share a specific audience with other ad account(s), or revoke access to a previously shared audience. - If the business is the owner of the audience, it can share with any ad account within the same business hierarchy. - If the business is the recipient of the audience, it can share with any of its owned ad accounts. This endpoint is not available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/). parameters: - $ref: '#/components/parameters/path_business_user' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BusinessToAdAccountSharedAudienceUpdateWithRequiredBody' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/BusinessToAdAccountSharedAudience' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:write tags: - audience_sharing x-ratelimit-category: ads_write x-sandbox: disabled /businesses/{business_id}/audiences/businesses/shared: patch: operationId: update_business_to_business_shared_audience summary: Update audience sharing between businesses description: |- From a business, share a specific audience with another business account, or revoke access to a previously shared audience. Only the audience owner can share the audience with other businesses, and the recipient business must be within the same business hierarchy. This endpoint is not available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/). parameters: - $ref: '#/components/parameters/path_business_user' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BusinessToBusinessSharedAudienceUpdateWithRequiredBody' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/BusinessToBusinessSharedAudience' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:write tags: - audience_sharing x-ratelimit-category: ads_write x-sandbox: disabled /businesses/{business_id}/audiences/shared/accounts: get: operationId: business_account_audiences_shared_accounts/list summary: List accounts with access to an audience owned by a business description: List all ad accounts and/or businesses that have access to a specific audience. The audience must either be owned by an ad account in the requesting business, or it must have been shared with the requesting business. If the requesting business is not the owner of the audience, only ad accounts owned by the requesting business will be returned. parameters: - $ref: '#/components/parameters/path_business_user' - $ref: '#/components/parameters/query_audience_id' - $ref: '#/components/parameters/query_account_type' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/SharedAudienceAccount' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read tags: - audience_sharing x-ratelimit-category: ads_read x-sandbox: disabled /businesses/{business_id}/invites: get: operationId: get/invites summary: Get invites/requests description: Get the membership/partnership invites and/or requests for the authorized user. parameters: - $ref: '#/components/parameters/path_non_system_business_user' - $ref: '#/components/parameters/query_is_member' - $ref: '#/components/parameters/query_invite_status' - $ref: '#/components/parameters/query_invite_type' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/InviteResponse' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read tags: - business_access_invite x-ratelimit-category: ads_read x-sandbox: disabled post: operationId: create_membership_or_partnership_invites summary: Create invites or requests description: |- Create batch invites or requests. Can create batch invites or requests as described below. - Invite members to join the business. This would required specifying the following: - invite_type="MEMBER_INVITE" - business_role="EMPLOYEE" OR business_role="BIZ_ADMIN" (To learn more about business roles, visit https://help.pinterest.com/en/business/article/profile-permissions-in-business-access.) - members - Invite partners to access your business assets. This would require specifying the following: - invite_type="PARTNER_INVITE" - business_role="PARTNER" - partners - Request to be a partner so you can access their assets. This would require specifying the following: - invite_type="PARTNER_REQUEST" - business_role="PARTNER" - partners parameters: - $ref: '#/components/parameters/path_non_system_business_user' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateMembershipOrPartnershipInvitesBody' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CreateInvitesResultsResponseArray' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/CreateInvitesResultsResponseArray' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:write tags: - business_access_invite x-ratelimit-category: ads_write x-sandbox: disabled delete: operationId: cancel_invites_or_requests summary: Cancel invites/requests description: Cancel membership/partnership invites and/or requests. parameters: - $ref: '#/components/parameters/path_non_system_business_user' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CancelInvitesRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CancelInvitesResponse' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:write tags: - business_access_invite x-ratelimit-category: ads_write x-sandbox: disabled /businesses/{business_id}/invites/assets/access: post: operationId: create_asset_invites summary: Update invite/request with an asset permission description: |- Assign asset permissions information to an existing invite/request. Can be used to: - Request access to a partner's asset. Note: This is only for when no existing partnership exists. If an existing partnership exists, use "Create a request to access an existing partner's assets" to request access to your partner's assets. - invite_type="PARTNER_REQUEST" - Invite a partner to access your business assets. Note: This is only for when there is no existing partnership. If there is an existing partnership, use "Assign/Update partner asset permissions" to assign a partner access to new assets. - invite_type="PARTNER_INVITE" - Invite a member to access your business assets. Note: This is only for when there is no existing membership. If there is an existing membership, use "Assign/Update member asset permissions" to assign a member access to new assets. - invite_type="MEMBER_INVITE" To learn more about permission levels, visit https://help.pinterest.com/en/business/article/business-manager-overview. parameters: - $ref: '#/components/parameters/path_business_user' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAssetInvitesRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/UpdateInvitesResultsResponseArray' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/UpdateInvitesResultsResponseArray' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read - biz_access:write tags: - business_access_invite x-ratelimit-category: ads_write x-sandbox: disabled /businesses/{business_id}/members: get: operationId: get/business_members summary: Get business members description: Get all members of the specified business. The return response will include the member's business_role and assets they have access to if assets_summary=TRUE parameters: - $ref: '#/components/parameters/path_business_user' - $ref: '#/components/parameters/query_fetch_system_users' - $ref: '#/components/parameters/query_assets_summary' - $ref: '#/components/parameters/query_member_business_roles' - $ref: '#/components/parameters/query_member_ids' - $ref: '#/components/parameters/query_business_access_start_index' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/UserBusinessRoleBinding' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read tags: - business_access_relationships x-ratelimit-category: ads_read x-sandbox: disabled delete: operationId: delete_business_membership summary: Terminate business memberships description: Terminate memberships between the specified members and your business. parameters: - $ref: '#/components/parameters/path_business_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeleteBusinessMembershipBody' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: deleted_members: type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read - biz_access:write tags: - business_access_relationships x-ratelimit-category: ads_write x-sandbox: enabled patch: operationId: update/business_memberships summary: Update member's business role description: Update a member's business role within the business. parameters: - $ref: '#/components/parameters/path_business_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateBusinessMembershipsBody' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/UpdateBusinessMembershipsResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:write tags: - business_access_relationships x-ratelimit-category: ads_write x-sandbox: disabled /businesses/{business_id}/members/assets/access: patch: operationId: business_members_asset_access/update summary: Assign/Update member asset permissions description: |- Grant multiple members access to assets and/or update multiple member's exisiting permissions to an asset. Note: Not all listed permissions are applicable to each asset type. For example, PROFILE_PUBLISHER would not be applicable to an asset of type AD_ACCOUNT. The permission level PROFILE_PUBLISHER is only available to an asset of the type PROFILE. parameters: - $ref: '#/components/parameters/path_business_user' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateMemberAssetAccessBody' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/UpdateMemberAssetsResultsResponseArray' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:write tags: - business_access_assets x-ratelimit-category: ads_write x-sandbox: disabled delete: operationId: business_members_asset_access/delete summary: Delete member access to asset description: Terminate multiple members' access to an asset. parameters: - $ref: '#/components/parameters/path_business_user' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/BusinessMembersAssetAccessDeleteBody' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/DeleteMemberAccessResultsResponseArray' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:write tags: - business_access_assets x-ratelimit-category: ads_write x-sandbox: disabled /businesses/{business_id}/members/{member_id}/assets: get: operationId: business_member_assets/get summary: Get assets assigned to a member description: |- Get assets on which you assigned asset permissions to the given member. Can be used to: - get all assets, regardless of asset type or - get assets of one asset type by using the asset_type query. The return response will include the permissions the member has to that asset and the asset type. parameters: - $ref: '#/components/parameters/path_business_user' - $ref: '#/components/parameters/path_business_member_user' - $ref: '#/components/parameters/query_resource_type_with_conversion_tag' - $ref: '#/components/parameters/query_business_access_start_index' - $ref: '#/components/parameters/query_asset_sort_by' - $ref: '#/components/parameters/query_asset_sort_ascending' - $ref: '#/components/parameters/query_asset_search_by' - $ref: '#/components/parameters/query_asset_search_value' - $ref: '#/components/parameters/query_asset_permission_type' - $ref: '#/components/parameters/query_ad_account_statuses_filter' - $ref: '#/components/parameters/query_active_bookmark_params.bookmark' - $ref: '#/components/parameters/query_active_bookmark_params.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/BusinessMemberAssetsGetResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read tags: - business_access_assets x-ratelimit-category: ads_read x-sandbox: disabled /businesses/{business_id}/partners: get: operationId: get/business_partners summary: Get business partners description: |- Get all partners of the specified business. If the assets_summary=TRUE and: - partner_type=INTERNAL, the business assets returned are your business assets the partner has access to. - partner_type=EXTERNAL, the business assets returned are your partner's business assets the partner has granted you access to. parameters: - $ref: '#/components/parameters/path_business_user' - $ref: '#/components/parameters/query_assets_summary' - $ref: '#/components/parameters/query_partner_type' - $ref: '#/components/parameters/query_partner_ids' - $ref: '#/components/parameters/query_business_access_start_index' - $ref: '#/components/parameters/query_sort_ascending' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/UserBusinessRoleBinding' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read tags: - business_access_relationships x-ratelimit-category: ads_read x-sandbox: disabled delete: operationId: delete_business_partners summary: Terminate business partnerships description: |- Terminate partnerships between the specified partners and your business. Note: You may only batch terminate partners of the same partner type. parameters: - $ref: '#/components/parameters/path_business_user' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeleteBusinessPartnersDelete' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/DeleteBusinessPartners' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:write tags: - business_access_relationships x-ratelimit-category: ads_write x-sandbox: disabled /businesses/{business_id}/partners/assets: patch: operationId: update_partner_asset_access_handler_impl summary: Assign/Update partner asset permissions description: |- Grant multiple partners access to assets and/or update multiple partner's exisiting permissions to an asset. If your partner already had permissions on the asset, they will be overriden with the new permissions you assign to them. To learn more about permission levels, visit https://help.pinterest.com/en/business/article/business-manager-overview Note: Not all listed permissions are applicable to each asset type. For example, PROFILE_PUBLISHER would not be applicable to an asset of type AD_ACCOUNT. The permission level PROFILE_PUBLISHER is only available to an asset of the type PROFILE. parameters: - $ref: '#/components/parameters/path_business_user' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdatePartnerAssetAccessBody' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/UpdatePartnerAssetsResultsResponseArray' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:write tags: - business_access_assets x-ratelimit-category: ads_write x-sandbox: disabled delete: operationId: delete_partner_asset_access_handler_impl summary: Delete partner access to asset description: |- Terminate multiple partners' access to an asset. If - partner_type=INTERNAL: You will terminate a partner's asset access to your business assets. - partner_type=EXTERNAL: You will terminate your own access to your partner's business assets. parameters: - $ref: '#/components/parameters/path_business_user' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/DeletePartnerAssetAccessBody' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/DeletePartnerAssetAccessResultsResponseArray' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:write tags: - business_access_assets x-ratelimit-category: ads_write x-sandbox: disabled /businesses/{business_id}/partners/{partner_id}/assets: get: operationId: business_partner_asset_access/get summary: Get assets assigned to a partner or assets assigned by a partner description: |- Can be used to get the business assets your partner has granted you access to or the business assets you have granted your partner access to. If you specify: - partner_type=INTERNAL, you will retrieve your business assets that the partner has access to. - partner_type=EXTERNAL, you will retrieve the partner's business assets that the partner has granted you access to. parameters: - $ref: '#/components/parameters/path_business_user' - $ref: '#/components/parameters/path_partner' - $ref: '#/components/parameters/query_business_partner_type_default' - $ref: '#/components/parameters/query_resource_type_internal' - $ref: '#/components/parameters/query_business_access_start_index' - $ref: '#/components/parameters/query_asset_sort_by' - $ref: '#/components/parameters/query_asset_sort_ascending' - $ref: '#/components/parameters/query_asset_search_by' - $ref: '#/components/parameters/query_asset_search_value' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/BaseBusinessAssets' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read tags: - business_access_assets x-ratelimit-category: ads_read x-sandbox: disabled /businesses/{business_id}/requests/assets/access: post: operationId: asset_access_requests/create summary: Create a request to access an existing partner's assets. description: Create a request to access an existing partner's assets with the specified permissions. The request will be sent to the partner for approval. The assets that can be requested are ad accounts and profiles. parameters: - $ref: '#/components/parameters/path_business_user' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateAssetAccessRequestBody' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CreateAssetAccessRequestResponse' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/CreateAssetAccessRequestResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read - biz_access:write tags: - business_access_invite x-ratelimit-category: ads_write x-sandbox: disabled /businesses/{business_id}/system_users/{system_user_id}: patch: operationId: system_user/update summary: Update a system user information. description: Update a system user information such as name. parameters: - $ref: '#/components/parameters/path_business_user' - $ref: '#/components/parameters/path_system_user_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SystemUserUpdateWithRequiredBody' responses: '200': description: The request has succeeded. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - biz_access:read - biz_access:write tags: - business_access_relationships x-ratelimit-category: ads_write x-sandbox: disabled /catalogs: get: operationId: catalogs/list summary: List catalogs description: |- Fetch catalogs owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an ad_account_id (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/Catalog' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read tags: - catalogs x-ratelimit-category: catalogs_read x-sandbox: enabled post: operationId: catalogs/create summary: Create catalog description: |- Create a new catalog owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an ad_account_id (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) Note: Access to the Product and Creative Assets catalog type is restricted to a specific group of users. If you require access, please reach out to your partner manager. parameters: - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CatalogCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Catalog' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/Catalog' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:write tags: - catalogs x-ratelimit-category: catalogs_write x-sandbox: enabled /catalogs/available_filter_values: get: operationId: catalogs/available_filter_values summary: List available filter values description: |- Get the available filter attributes and values associated with a given feed or catalog owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. - `country`, `language`, and `feed_id` are only used in retail catalogs. - Note: It is not guaranteed that all available filter values will be returned. Instead this endpoint will return values from a sample of up to 1000 items. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/query_catalogs_catalog_id_required' - $ref: '#/components/parameters/query_catalogs_feed_id' - $ref: '#/components/parameters/query_catalogs_country' - $ref: '#/components/parameters/query_catalogs_language' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CatalogsAvailableFilterValues' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read tags: - catalogs x-ratelimit-category: catalogs_read x-sandbox: enabled /catalogs/feeds: get: operationId: feeds/list summary: List feeds description: |- Fetch feeds owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. For Retail partners, refer to [Before you get started with Catalogs](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs). For Hotel partners, refer to [Pinterest API for shopping](/docs/api-features/shopping-overview/). parameters: - $ref: '#/components/parameters/query_catalogs_catalog_id' - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/CatalogsFeed' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read - client_credentials: - catalogs:read tags: - catalog_feeds x-ratelimit-category: catalogs_read x-sandbox: enabled post: operationId: feeds/create summary: Create feed description: |- Create a new feed owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. Please, be aware that "default_country" and "default_locale" are not required in the spec for forward compatibility but for now the API will not accept requests without those fields. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. For Retail partners, refer to [Before you get started with Catalogs](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs). For Hotel partners, refer to [Pinterest API for shopping](/docs/api-features/shopping-overview/). Note: Access to the Creative Assets catalog type is restricted to a specific group of users. If you require access, please reach out to your partner manager. parameters: - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CatalogsFeedCreateRequestSchema' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CatalogsFeed' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/CatalogsFeed' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read - catalogs:write - client_credentials: - catalogs:read - catalogs:write tags: - catalog_feeds x-ratelimit-category: catalogs_write x-sandbox: enabled /catalogs/feeds/{feed_id}: get: operationId: feeds/get summary: Get feed description: |- Get a single feed owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. For Retail partners, refer to [Before you get started with Catalogs](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs). For Hotel partners, refer to [Pinterest API for shopping](/docs/api-features/shopping-overview/). parameters: - $ref: '#/components/parameters/path_catalogs_feed_id' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CatalogsFeed' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read - client_credentials: - catalogs:read tags: - catalog_feeds x-ratelimit-category: catalogs_read x-sandbox: enabled patch: operationId: feeds/update summary: Update feed description: |- Update a feed owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. For Retail partners, refer to [Before you get started with Catalogs](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs). For Hotel partners, refer to [Pinterest API for shopping](/docs/api-features/shopping-overview/). Note: Access to the Creative Assets catalog type is restricted to a specific group of users. If you require access, please reach out to your partner manager. parameters: - $ref: '#/components/parameters/path_catalogs_feed_id' - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CatalogsFeedUpdateRequestSchema' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CatalogsFeed' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read - catalogs:write - client_credentials: - catalogs:read - catalogs:write tags: - catalog_feeds x-ratelimit-category: catalogs_write x-sandbox: enabled delete: operationId: feeds/delete summary: Delete feed description: |- Delete a feed owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. For Retail partners, refer to [Before you get started with Catalogs](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs). For Hotel partners, refer to [Pinterest API for shopping](/docs/api-features/shopping-overview/). parameters: - $ref: '#/components/parameters/path_catalogs_feed_id' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CatalogsFeed' '204': description: Resource deleted successfully. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read - catalogs:write - client_credentials: - catalogs:read - catalogs:write tags: - catalog_feeds x-ratelimit-category: catalogs_write x-sandbox: enabled /catalogs/feeds/{feed_id}/ingest: post: operationId: feeds/ingest summary: Ingest feed items description: |- Ingest items for a given feed owned by the "operation user_account". Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) Note: This endpoint is restricted to a specific group of users. If you require access, please reach out to your partner manager. parameters: - $ref: '#/components/parameters/path_catalogs_feed_id' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CatalogsFeedIngestion' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:write tags: - catalog_feeds x-ratelimit-category: catalogs_write x-sandbox: enabled /catalogs/feeds/{feed_id}/processing_results: get: operationId: feed_processing_results/list summary: List feed processing results description: |- Fetch a feed processing results owned by the "operation user_account". Please note that for now the bookmark parameter is not functional and only the first page will be available until it is implemented in some release in the near future. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/path_catalogs_feed_id' - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/CatalogsFeedProcessingResult' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read tags: - catalog_feeds x-ratelimit-category: catalogs_read x-sandbox: enabled /catalogs/items: post: operationId: items/post summary: Get catalogs items (POST) description: |- Get the items of the catalog owned by the "operation user_account". [See detailed documentation here.](/docs/api-features/shopping-overview/#Update%20items%20in%20batch) - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. Note: Access to the Creative Assets catalog type is restricted to a specific group of users. If you require access, please reach out to your partner manager. parameters: - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CatalogsItemsRequest' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/ItemResponse' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read tags: - catalog_items x-ratelimit-category: catalogs_read x-sandbox: enabled /catalogs/items/batch: post: operationId: items_batch/post summary: Operate on item batch description: |- This endpoint supports multiple operations on a set of one or more catalog items owned by the "operation user_account". [See detailed documentation here.](/docs/work-with-catalogs/modify-items-in-batch/) - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. Note: - Access to the Creative Assets catalog type is restricted to a specific group of users. If you require access, please reach out to your partner manager. - The item UPSERT operation is restricted to users without a feed data source. If you plan to migrate item ingestion from feeds to the API, please reach out to your partner manager or via the Help Center to get assistance. parameters: - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CatalogsItemsBatchPostRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CatalogsItemsBatch' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read - catalogs:write - client_credentials: - catalogs:read - catalogs:write tags: - catalog_items x-ratelimit-category: catalogs_write x-sandbox: enabled /catalogs/items/batch/{batch_id}: get: operationId: items_batch/get summary: Get item batch status description: |- Get a single catalogs items batch owned by the "operating user_account". [See detailed documentation here.](/docs/api-features/shopping-overview/#Update%20items%20in%20batch) - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. parameters: - $ref: '#/components/parameters/path_catalogs_items_batch_id' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CatalogsItemsBatch' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read - client_credentials: - catalogs:read tags: - catalog_items x-ratelimit-category: catalogs_read x-sandbox: enabled /catalogs/processing_results/{processing_result_id}/item_issues: get: operationId: items_issues/list summary: List item issues description: |- List item validation issues for a given feed processing result owned by the "operation user_account". Up to 20 random samples of affected items are returned for each error and warning code. Please note that for now query parameters 'item_numbers' and 'item_validation_issue' cannot be used simultaneously until it is implemented in some release in the future. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. Note: To get a list of all affected items instead of sampled issues, please refer to [Build catalogs report](/docs/api/v5/#operation/reports/create) and [Get catalogs report](/docs/api/v5/#operation/reports/get) endpoints. Moreover, they support multiple types of catalogs. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/path_catalogs_processing_result_id' - $ref: '#/components/parameters/query_catalogs_item_numbers' - $ref: '#/components/parameters/query_catalogs_item_validation_issue' - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/CatalogsItemValidationIssues' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read tags: - catalog_feeds x-ratelimit-category: catalogs_read x-sandbox: enabled /catalogs/product_groups: get: operationId: catalogs_product_groups/list summary: List product groups description: |- Get a list of product groups for a given Catalogs Feed Id owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/query_catalogs_product_group_ids' - $ref: '#/components/parameters/query_catalogs_feed_id' - $ref: '#/components/parameters/query_catalogs_catalog_id' - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/CatalogsVerticalProductGroup' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read tags: - catalog_product_groups x-ratelimit-category: catalogs_read x-sandbox: enabled post: operationId: catalogs_product_groups/create summary: Create product group description: |- Create product group to use in Catalogs owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. "Catalog-based product groups" can include items from all data sources (feeds and API) and are available to both non-retail catalogs with any data sources and retail catalogs with API-created items. If your catalog only contains retail items created via feeds, you should use the "retail feed-based" option. [Learn more](/docs/api-features/shopping-overview/) Note: Access to the Creative Assets catalog type is restricted to a specific group of users. If you require access, please reach out to your partner manager. parameters: - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CatalogsProductGroupsCreateRequestSchema' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CatalogsVerticalProductGroup' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/CatalogsVerticalProductGroup' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:write tags: - catalog_product_groups x-ratelimit-category: catalogs_write x-sandbox: enabled /catalogs/product_groups/multiple: delete: operationId: catalogs_product_groups/delete_many summary: Delete product groups description: |- Delete product groups owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/query_catalogs_product_group_ids_required' - $ref: '#/components/parameters/query_ad_account_id' responses: '204': description: Resource deleted successfully. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:write tags: - catalog_product_groups x-ratelimit-category: catalogs_write x-sandbox: enabled post: operationId: catalogs_product_groups/create_many summary: Create product groups description: |- Create product group to use in Catalogs owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) Note: Access to the Creative Assets catalog type is restricted to a specific group of users. If you require access, please reach out to your partner manager. parameters: - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CatalogsProductGroupsCreateManyRequestSchema' responses: '201': description: The request has succeeded and a new resource has been created as a result. content: application/json: schema: type: array items: $ref: '#/components/schemas/CatalogsProductGroupsCreateManyResponse201Items' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:write tags: - catalog_product_groups x-ratelimit-category: catalogs_write x-sandbox: enabled /catalogs/product_groups/{product_group_id}: get: operationId: catalogs_product_groups/get summary: Get product group description: |- Get a single product group for a given Catalogs Product Group Id owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/path_product_group_id' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CatalogsVerticalProductGroup' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read tags: - catalog_product_groups x-ratelimit-category: catalogs_read x-sandbox: enabled patch: operationId: catalogs_product_groups/update summary: Update single product group description: |- Update product group owned by the "operation user_account" to use in Catalogs. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. "Catalog-based product groups" can include items from all data sources (feeds and API) and are available to both non-retail catalogs with any data sources and retail catalogs with API-created items. If your catalog only contains retail items created via feeds, you should use the "retail feed-based" option. [Learn more](/docs/api-features/shopping-overview/) Note: Access to the Creative Assets catalog type is restricted to a specific group of users. If you require access, please reach out to your partner manager. parameters: - $ref: '#/components/parameters/path_product_group_id' - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CatalogsProductGroupsUpdateRequestSchema' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CatalogsVerticalProductGroup' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:write tags: - catalog_product_groups x-ratelimit-category: catalogs_write x-sandbox: enabled delete: operationId: catalogs_product_groups/delete summary: Delete product group description: |- Delete a product group owned by the "operation user_account" from being in use in Catalogs. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/path_product_group_id' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CatalogsVerticalProductGroup' '204': description: Resource deleted successfully. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:write tags: - catalog_product_groups x-ratelimit-category: catalogs_write x-sandbox: enabled /catalogs/product_groups/{product_group_id}/product_counts: get: operationId: catalogs_product_groups/product_counts_get summary: Get product counts description: |- Get a product counts for a given Catalogs Product Group owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/path_product_group_id' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CatalogsProductGroupProductCountsVertical' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read tags: - catalog_product_groups x-ratelimit-category: catalogs_read x-sandbox: enabled /catalogs/product_groups/{product_group_id}/products: get: operationId: catalogs_product_group_pins/list summary: List products by product group description: |- Get a list of product pins for a given Catalogs Product Group Id owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/path_product_group_id' - $ref: '#/components/parameters/query_pin_metrics' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/CatalogsProduct' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - catalogs:read - pins:read - client_credentials: - boards:read - catalogs:read - pins:read tags: - catalog_product_groups x-ratelimit-category: catalogs_read x-sandbox: enabled /catalogs/products/get_by_product_group_filters: post: operationId: products_by_product_group_filter/list summary: List products by filter description: |- List products Pins owned by the "operation user_account" that meet the criteria specified in the Catalogs Product Group Filter given in the request. - This endpoint has been implemented in POST to allow for complex filters. This specific POST endpoint is designed to be idempotent. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. Note: This endpoint only supports RETAIL catalog at the moment. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/query_pin_metrics' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CatalogsListProductsByFilterRequest' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/CatalogsProduct' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - catalogs:read - pins:read tags: - catalog_product_groups x-ratelimit-category: catalogs_read x-sandbox: enabled /catalogs/reports: get: operationId: reports/get summary: Get catalogs report description: |- This returns a URL to a report given a token returned from [Build catalogs report](/docs/api/v5/#operation/reports/create). You can use the URL to download the report. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. parameters: - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/query_token_required' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CatalogsReport' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read tags: - catalog_reports x-ratelimit-category: catalogs_read x-sandbox: disabled post: operationId: reports/create summary: Build catalogs report description: |- Async request to create a report of the catalog owned by the "operation user_account". This endpoint generates a report upon receiving the first approved request of the day. Any following requests with identical parameters will yield the same report even if data has changed. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. Note: The All Items report is limited to 25 million items per catalog. parameters: - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CatalogsReportParameters' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/CatalogsCreateReportResponse' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/CatalogsCreateReportResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read tags: - catalog_reports x-ratelimit-category: catalogs_read x-sandbox: disabled /catalogs/reports/stats: get: operationId: reports/stats summary: List report stats description: |- List aggregated numbers of issues for a catalog owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. parameters: - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/query_catalogs_report_stats_parameters' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/CatalogsReportStats' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read tags: - catalog_reports x-ratelimit-category: catalogs_read x-sandbox: disabled /catalogs/{catalog_id}/local_inventory_items/batch: post: operationId: catalogs_local_inventory_items_batch/operate summary: Operate on local inventory item batch description: |- Managing local inventory information in batches supporting CREATE, UPDATE, UPSERT, DELETE operations. Up to 1000 items per request to match catalogs/items. - Must provide both item_id and store_code to identify a local inventory item. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an ad_account_id (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/CatalogId' - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LocalInventoryItemsBatchCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/SupplementalItemsBatchResponse' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/LocalInventoryItemsBatch' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:write tags: - catalog_supplemental x-ratelimit-category: catalogs_write x-sandbox: disabled /catalogs/{catalog_id}/local_inventory_items/query: post: operationId: catalogs_local_inventory_items/post summary: Get local inventory items (POST) description: |- Get local inventory items for a catalog owned by the "operation user_account". - Must provide an array of {item_id, store_code} pairs in item filters to identify local inventory items. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an ad_account_id (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/CatalogId' - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/LocalInventoryItemsGetCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/LocalInventoryItemsGet' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/LocalInventoryItemsGet' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read tags: - catalog_supplemental x-ratelimit-category: catalogs_read x-sandbox: disabled /catalogs/{catalog_id}/local_stores: get: operationId: catalogs_local_stores/list summary: List local stores description: |- Fetch local stores for a catalog owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. - Supports optional filtering by store codes. Optional: Business Access: Specify an ad_account_id (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/CatalogId' - $ref: '#/components/parameters/query_local_store_ids' - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/LocalStore' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read tags: - catalog_supplemental x-ratelimit-category: catalogs_read x-sandbox: disabled post: operationId: catalogs_local_stores/create summary: Create local stores description: |- Create a local store for a catalog owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. - Supports optional filtering by store codes. Optional: Business Access: Specify an ad_account_id (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/CatalogId' - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/LocalStoreCreate' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: type: object required: - data properties: data: description: Created/updated resource on success or error details on failure oneOf: - $ref: '#/components/schemas/LocalStore' - type: object required: - id - exceptions properties: id: description: The ID of the local store. type: string example: '1234567890' pattern: ^\d+$ exceptions: $ref: '#/components/schemas/Pinterest.Lib.Error' '201': description: Resource create operation completed successfully. content: application/json: schema: type: array items: $ref: '#/components/schemas/LocalStore' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:write tags: - catalog_supplemental x-ratelimit-category: catalogs_write x-sandbox: disabled patch: operationId: catalogs_local_stores/update summary: Update local stores description: |2- Update a local store for a catalog owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. - Supports optional filtering by store codes. Optional: Business Access: Specify an ad_account_id (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/CatalogId' - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: type: array items: $ref: '#/components/schemas/LocalStoreBatchUpdate' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: type: object required: - data properties: data: description: Created/updated resource on success or error details on failure oneOf: - $ref: '#/components/schemas/LocalStore' - type: object required: - id - exceptions properties: id: description: The ID of the local store. type: string example: '1234567890' pattern: ^\d+$ exceptions: $ref: '#/components/schemas/Pinterest.Lib.Error' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:write tags: - catalog_supplemental x-ratelimit-category: catalogs_write x-sandbox: disabled delete: operationId: catalogs_local_stores/delete summary: Delete local stores description: |2- Delete multiple local stores for a catalog owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. - Supports optional filtering by store codes. Optional: Business Access: Specify an ad_account_id (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/CatalogId' - $ref: '#/components/parameters/query_local_store_ids_required' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: type: object required: - id - status properties: id: description: The ID of the local store. type: string example: '1234567890' pattern: ^\d+$ status: oneOf: - $ref: '#/components/schemas/Pinterest.Lib.Status204' - $ref: '#/components/schemas/Pinterest.Lib.Error' '204': description: Resource deleted successfully. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:write tags: - catalog_supplemental x-ratelimit-category: catalogs_write x-sandbox: disabled /catalogs/{catalog_id}/supplemental_items/batch/{batch_id}: get: operationId: catalogs_supplemental_items_batch/get summary: Get supplemental items batch status description: |- Fetch the status and results of a supplemental items batch operation. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an ad_account_id (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: Owner, Admin, Catalogs Manager. [Learn more](/docs/api-features/shopping-overview/) parameters: - $ref: '#/components/parameters/CatalogId' - $ref: '#/components/parameters/ItemsBatchId' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/SupplementalItemsBatchResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - catalogs:read tags: - catalog_supplemental x-ratelimit-category: catalogs_read x-sandbox: disabled /integrations: get: operationId: integrations/get_list summary: Get integration metadata list description: |- Get integration metadata list. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager. parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/IntegrationRecord' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - integrations x-ratelimit-category: ads_read x-sandbox: disabled /integrations/commerce: post: operationId: integrations_commerce/post summary: Create commerce integration description: "Create commerce integration metadata to link an external business ID with a Pinterest merchant & ad account. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager." requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IntegrationMetadataCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/IntegrationMetadata' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/IntegrationMetadata' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - integrations x-ratelimit-category: ads_write x-sandbox: disabled /integrations/commerce/{external_business_id}: get: operationId: integrations_commerce/get summary: Get commerce integration description: "Get commerce integration metadata associated with the given external business ID. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager." parameters: - $ref: '#/components/parameters/path_external_business_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/IntegrationMetadata' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - integrations x-ratelimit-category: ads_read x-sandbox: disabled patch: operationId: integrations_commerce/patch summary: Update commerce integration description: "Update commerce integration metadata for the given external business ID. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager." parameters: - $ref: '#/components/parameters/path_external_business_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IntegrationMetadataUpdate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/IntegrationMetadata' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - integrations x-ratelimit-category: ads_write x-sandbox: disabled delete: operationId: integrations_commerce/del summary: Delete commerce integration description: "Delete commerce integration metadata for the given external business ID. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager." parameters: - $ref: '#/components/parameters/path_external_business_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/IntegrationMetadata' '204': description: Resource deleted successfully. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - integrations x-ratelimit-category: ads_write x-sandbox: disabled /integrations/logs: post: operationId: integrations_logs/post summary: Receives batched logs from integration applications. description: |- This endpoint receives batched logs from integration applications on partner platforms. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/IntegrationLogsRequestCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/IntegrationLogsSuccessResponse' '400': description: The server could not understand the request due to invalid syntax. content: application/json: schema: $ref: '#/components/schemas/IntegrationLogsInvalidLogResponse' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - integrations x-ratelimit-category: ads_write x-sandbox: enabled /integrations/{id}: get: operationId: integrations/get_by_id summary: Get integration metadata description: |- Get integration metadata by ID. Note: If you're interested in joining the beta, please reach out to your Pinterest account manager. parameters: - $ref: '#/components/parameters/IntegrationRecordKey' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/IntegrationRecord' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - integrations x-ratelimit-category: ads_read x-sandbox: disabled /media: get: operationId: media/list summary: List media uploads description: |- List media uploads filtered by given parameters. **[Learn more](/docs/api-features/creating-boards-and-pins/#creating-video-pins)** about video Pin creation. parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/Media' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - pins:read tags: - media x-ratelimit-category: org_read x-sandbox: enabled post: operationId: media/create summary: Register media upload description: |- Register your intent to upload media. The response includes all of the information needed to upload the media to Pinterest. To upload the media, make an HTTP POST request (using `curl`, for example) to `upload_url` using the `Content-Type` header value. Send the media file's contents as the request's `file` parameter and also include all of the parameters from `upload_parameters`. **[Learn more](/docs/api-features/creating-boards-and-pins/#creating-video-pins)** about video Pin creation. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/MediaUploadCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/MediaUpload' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/MediaUpload' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - pins:read - pins:write tags: - media x-ratelimit-category: org_write x-sandbox: enabled /media/{media_id}: get: operationId: media/get summary: Get media upload details description: |- Get details for a registered media upload, including its current status. **[Learn more](/docs/api-features/creating-boards-and-pins/#creating-video-pins)** about video Pin creation. parameters: - $ref: '#/components/parameters/MediaKey' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Media' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - pins:read tags: - media x-ratelimit-category: org_read x-sandbox: enabled /notifications: post: operationId: notification/post summary: Receive notifications from external partners. description: Used by third-party partners to send notifications to Pinterest. These notifications could be specific for your use-case or generic notification that are accepted by Pinterests' systems. This API is gated and you need to request access to this feature. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/NotificationPostRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/NotificationResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:read - client_credentials: - user_accounts:read tags: - notification x-ratelimit-category: ads_read x-sandbox: enabled /oauth/conversion_token: post: operationId: oauth/conversion_token summary: Generate OAuth access token for conversion API description: Generate a new and long-lived OAuth access token dedicated for sending conversions using a valid access token. responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/ConversionAccessToken' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:write tags: - oauth x-ratelimit-category: org_write x-sandbox: enabled /oauth/token: post: operationId: oauth/token summary: Generate OAuth access token description: | Generate a new OAuth access token using an authorization code; or refresh an existing one using a continuous refresh token. Follow the complete steps for [requesting and refreshing tokens](/docs/getting-started/set-up-authentication-and-authorization/). **Note:** If your app was created **before September 25, 2025**, make sure to set the `continuous_refresh` parameter to `true` to use the continuous refresh token (60-day expiration, refreshable indefinitely). Pinterest no longer supports the legacy refresh token (365-day expiration, hard limit). Disregard this note if your app was activated on or after September 25, 2025. You are automatically using the continuous refresh token. Use [Token Debugger](/docs/developer-tools/token-debugger/) to validate and inspect your access token. requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/OauthAccessTokenCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/OauthAccessToken' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/OauthAccessToken' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - basic: [] tags: - oauth x-ratelimit-category: org_read x-sandbox: enabled /oauth/token/revoke: post: operationId: token/revoke summary: Revoke a token description: Revokes an access or refresh token. Only tokens issued for system users are currently supported. Revoked tokens become immediately invalid and unusable. requestBody: required: true content: application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/TokenRevocationRequestCreate' responses: '200': description: The request has succeeded. '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - basic: [] tags: - oauth x-ratelimit-category: org_write x-sandbox: enabled /pins: post: operationId: pins/create summary: Create Pin description: |2- Create a Pin on a board or board section owned by the "operation user_account". Note: If the current "operation user_account" (defined by the access token) has access to another user's Ad Accounts via Pinterest Business Access, you can modify your request to make use of the current operation_user_account's permissions to those Ad Accounts by including the ad_account_id in the path parameters for the request (e.g. .../?ad_account_id=12345&...). - This function is intended solely for publishing new content created by the user. If you are interested in saving content created by others to your Pinterest boards, sometimes called 'curated content', please use our [Save button](/docs/web-features/add-ons-overview/) instead. For more tips on creating fresh content for Pinterest, review our [Content App Solutions Guide](/docs/api-features/content-overview/). **[Learn more](/docs/api-features/creating-boards-and-pins/#creating-video-pins)** about video Pin creation. **[Learn more](/docs/api-features/creating-boards-and-pins/#creating-image-pins)** about image Pin creation. parameters: - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PinCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Pin' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/Pin' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - boards:write - pins:read - pins:write - client_credentials: - boards:read - boards:write - pins:read - pins:write tags: - pins x-ratelimit-category: org_write x-sandbox: enabled get: operationId: pins/list summary: List Pins description: |2- Get a list of the Pins owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. - All Pins owned by the "operation user_account" are included, regardless of who owns the board they are on. Optional: Business Access: Specify an `ad_account_id` to use the owner of that ad_account as the "operation user_account". Disclaimer: There are known performance issues when filtering by field `creative_type` and including protected pins. If your request is timing out in this scenario, we encourage you to use [GET List Pins on Board](/docs/api/v5/#operation/boards/list_pins). parameters: - $ref: '#/components/parameters/query_pin_filter' - $ref: '#/components/parameters/query_pin_metrics' - $ref: '#/components/parameters/query_include_protected_pins' - $ref: '#/components/parameters/query_pin_type' - $ref: '#/components/parameters/query_creative_types' - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/query_domain' - $ref: '#/components/parameters/query_domains' - $ref: '#/components/parameters/query_include_product_tag_obj' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/Pin' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - pins:read - client_credentials: - boards:read - pins:read tags: - pins x-ratelimit-category: org_read x-sandbox: enabled /pins/analytics: get: operationId: multi_pins/analytics summary: Get multiple Pin analytics description: |- **This endpoint is currently in beta and not available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/).** Get analytics for multiple pins owned by the "operation user_account" - or on a group board that has been shared with this account. - The maximum number of pins supported in a single request is 100. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: - For Pins on public or protected boards: Admin, Analyst. - For Pins on secret boards: Admin. If Pin was created before `2023-03-20` lifetime metrics will only be available for Video and Idea Pin formats. Lifetime metrics are available for all Pin formats since then. parameters: - $ref: '#/components/parameters/query_required_pin_ids' - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_app_types' - $ref: '#/components/parameters/query_multi_pins_analytics_metric_types' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: type: object additionalProperties: $ref: '#/components/schemas/PinAnalyticsResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - pins:read - client_credentials: - boards:read - pins:read tags: - pins x-ratelimit-category: org_analytics x-sandbox: disabled /pins/{pin_id}: get: operationId: pins/get summary: Get Pin description: |2- Get a Pin owned by the "operation user_account" - or on a group board that has been shared with this account. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: - For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager. - For Pins on secret boards: Owner, Admin. parameters: - $ref: '#/components/parameters/PinKey' - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/query_pin_metrics' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Pin' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - pins:read - client_credentials: - boards:read - pins:read tags: - pins x-ratelimit-category: org_read x-sandbox: enabled patch: operationId: pins/update summary: Update Pin description: |- Update a pin owned by the "operating user_account". - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: - For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager. - For Pins on secret boards: Owner, Admin. **This endpoint is currently in beta and not available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/).** parameters: - $ref: '#/components/parameters/PinKey' - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PinUpdate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Pin' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - boards:write - pins:read - pins:write - client_credentials: - boards:read - boards:write - pins:read - pins:write tags: - pins x-ratelimit-category: org_write x-sandbox: enabled delete: operationId: pins/delete summary: Delete Pin description: |2- Delete a Pins owned by the "operation user_account" - or on a group board that has been shared with this account. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: - For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager. - For Pins on secret boards: Owner, Admin. parameters: - $ref: '#/components/parameters/PinKey' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Pin' '204': description: Resource deleted successfully. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - boards:write - pins:read - pins:write - client_credentials: - boards:read - boards:write - pins:read - pins:write tags: - pins x-ratelimit-category: org_write x-sandbox: enabled /pins/{pin_id}/analytics: get: operationId: pins/analytics summary: Get Pin analytics description: |- Get analytics for a Pin owned by the "operation user_account" - or on a group board that has been shared with this account. - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: - For Pins on public or protected boards: Admin, Analyst. - For Pins on secret boards: Admin. If Pin was created before `2023-03-20` lifetime metrics will only be available for Video and Idea Pin formats. Lifetime metrics are available for all Pin formats since then. parameters: - $ref: '#/components/parameters/path_pin_id' - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_app_types' - $ref: '#/components/parameters/query_pin_analytics_metric_types' - $ref: '#/components/parameters/query_split_field_pins' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/PinAnalyticsResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - pins:read - client_credentials: - boards:read - pins:read tags: - pins x-ratelimit-category: org_analytics x-sandbox: disabled /pins/{pin_id}/product_tags: post: operationId: product_tags/bulk_add summary: Add product tags to pin description: |- Add product tags to a pin. Product tags allow you to tag product pins onto a hero pin. - Maximum 24 product tags can be added in a single request. - Duplicate pin_ids in the request will result in an error. - If any product tag fails eligibility check, the entire request fails (all-or-nothing). - If a product tag is already tagged on the pin, it is treated as a no-op success. parameters: - $ref: '#/components/parameters/ProductTagsHeroPinId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProductTagsBulkAddRequest' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/ProductTagsResponse' '400': description: The request contains ineligible product tags. content: application/json: schema: $ref: '#/components/schemas/ProductTagsError' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - boards:write - pins:read - pins:write tags: - product_tags x-ratelimit-category: org_write x-sandbox: disabled get: operationId: product_tags/list summary: Get product tags for pin description: |- Retrieve all product tags for a pin. - Returns an empty array if the pin has no product tags. parameters: - $ref: '#/components/parameters/ProductTagsHeroPinId' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/ProductTagsResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - pins:read tags: - product_tags x-ratelimit-category: org_read x-sandbox: disabled /pins/{pin_id}/product_tags/bulk-delete: post: operationId: product_tags/bulk_delete summary: Delete product tags from pin description: |- Delete product tags from a pin. - If a product tag is not found on the pin, it is treated as a no-op success. parameters: - $ref: '#/components/parameters/ProductTagsHeroPinId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ProductTagsBulkDeleteRequest' responses: '204': description: Resource deleted successfully. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - boards:write - pins:read - pins:write tags: - product_tags x-ratelimit-category: org_write x-sandbox: disabled /pins/{pin_id}/save: post: operationId: pins/save summary: Save Pin description: |- Save a Pin on a board or board section owned by the "operation user_account". - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an `ad_account_id` (obtained via [List ad accounts](/docs/api/v5/#operation/ad_accounts/list)) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following [Business Access](https://help.pinterest.com/en/business/article/share-and-manage-access-to-your-ad-accounts) roles on the ad_account: - For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager. - For Pins on secret boards: Owner, Admin. - Any Pin type can be saved: image Pin, video Pin, Idea Pin, product Pin, etc. - Any public Pin can be saved given a pin ID. parameters: - $ref: '#/components/parameters/path_pin_id' - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/PinsSaveRequestCreate' responses: '201': description: The request has succeeded and a new resource has been created as a result. content: application/json: schema: $ref: '#/components/schemas/Pin' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - boards:write - pins:read - pins:write tags: - pins x-codeSamples: - label: Python SDK lang: python source: | # Follow this link for initial setup: https://github.com/pinterest/pinterest-python-sdk#getting-started from pinterest.organic.pins import Pin # Pin information can be fetched from profile page or from create/list pin method here: # /docs/api/v5/#operation/pins/list PIN_ID="" # Board information can be fetched from profile page or from list board method here: # /docs/api/v5/#operation/boards/list NEW_BOARD_ID="" pin_save = Pin(pin_id=PIN_ID) pin_save.save(board_id=NEW_BOARD_ID) print("Pin Id: %s, Board Id:%s" %(pin_save.id, pin_save.board_id)) - label: curl lang: cURL source: | # Pin and Board information can be fetched from profile page or from create/list pin method here: # /docs/api/v5/#operation/pins/list # /docs/api/v5/#operation/boards/list curl --request DELETE 'https://api.pinterest.com/v5/pins//save' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "board_id": }' - label: curl (Sandbox) lang: cURL source: | # Pin and Board information can be fetched from profile page or from create/list pin method here: # /docs/api/v5/#operation/pins/list # /docs/api/v5/#operation/boards/list curl --request DELETE 'https://api-sandbox.pinterest.com/v5/pins//save' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data-raw '{ "board_id": }' x-ratelimit-category: org_write x-sandbox: enabled /resources/ad_account_countries: get: operationId: ad_account_countries/get summary: Get ad accounts countries description: Get Ad Accounts countries responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/AdAccountsCountry' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - resources x-ratelimit-category: ads_read x-sandbox: enabled /resources/delivery_metrics: get: operationId: delivery_metrics/get summary: Get available metrics' definitions description: |- Get the definitions for ads and organic metrics available across both synchronous and asynchronous report endpoints. The `display_name` attribute will match how the metric is named in our native tools like Ads Manager. See [Organic Analytics](/docs/api-features/analytics-overview/) and [Ads Analytics](/docs/api-features/ads-reporting/) for more information. parameters: - $ref: '#/components/parameters/query_report_type' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: items: type: array items: $ref: '#/components/schemas/DeliveryMetricsResponseItemsItems' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - pins:read - user_accounts:read - client_credentials: - ads:read - pins:read - user_accounts:read tags: - resources x-ratelimit-category: ads_read x-sandbox: enabled /resources/lead_form_questions: get: operationId: lead_form_questions/get summary: Get lead form questions description: |- Get a list of all lead form question type names. Some questions might not be used. **This endpoint is currently in beta and not available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/).** responses: '200': description: The request has succeeded. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - resources x-ratelimit-category: ads_read x-sandbox: enabled /resources/metrics_ready_state: get: operationId: metrics_ready_state/get summary: Get metrics ready state description: Learn whether conversion or non-conversion metrics are finalized and ready to query. parameters: - $ref: '#/components/parameters/query_metrics_ready_state_date' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/BookClosed' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - resources x-ratelimit-category: ads_analytics x-sandbox: enabled /resources/targeting/interests/{interest_id}: get: operationId: interest_targeting_options/get summary: Get interest details description: |- Get details of a specific interest given interest ID. Click [here](https://docs.google.com/spreadsheets/d/1HxL-0Z3p2fgxis9YBP2HWC3tvPrs1hAuHDRtH-NJTIM/edit#gid=118370875) for a spreadsheet listing interests and their IDs. parameters: - $ref: '#/components/parameters/path_interest_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/SingleInterestTargetingOption' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - resources x-ratelimit-category: ads_read x-sandbox: enabled /resources/targeting/{targeting_type}: get: operationId: targeting_options/get summary: Get targeting options description: |2- You can use targeting values in ads placement to define your intended audience. Targeting metrics are organized around targeting specifications. For more information on ads targeting, see [Audience targeting](https://help.pinterest.com/en/business/article/audience-targeting). **Sample return:** ``` [{"36313": "Australia: Moreton Bay - North", "124735": "Canada: North Battleford", "36109": "Australia: Murray", "36108": "Australia: Mid North Coast", "36101": "Australia: Capital Region", "811": "U.S.: Reno", "36103": "Australia: Central West", "36102": "Australia: Central Coast", "36105": "Australia: Far West and Orana", "36104": "Australia: Coffs Harbour - Grafton", "36107": "Australia: Illawarra", "36106": "Australia: Hunter Valley Exc Newcastle", "554017": "New Zealand: Wanganui", "554016": "New Zealand: Marlborough", "554015": "New Zealand: Gisborne", "554014": "New Zealand: Tararua", "554013": "New Zealand: Invercargill", "GR": "Greece", "554011": "New Zealand: Whangarei", "554010": "New Zealand: Far North", "717": "U.S.: Quincy-Hannibal-Keokuk", "716": "U.S.: Baton Rouge",...}] ``` parameters: - $ref: '#/components/parameters/path_targeting_type' - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/query_client_id' - $ref: '#/components/parameters/query_oauth_signature' - $ref: '#/components/parameters/query_timestamp' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: $ref: '#/components/schemas/TargetingOption' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read - client_credentials: - ads:read tags: - resources x-ratelimit-category: ads_read x-sandbox: enabled /search/boards: get: operationId: search_user_boards/get summary: Search user's boards description: |- Search for boards for the "operation user_account". This includes boards of all board types. - By default, the "operation user_account" is the token user_account. If using Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". See [Understanding Business Access](/docs/getting-started/using-business-access/) for more information. parameters: - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/query_query' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/Board' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - boards:read_secret - client_credentials: - boards:read - boards:read_secret tags: - search x-ratelimit-category: org_read x-sandbox: disabled /search/partner/pins: get: operationId: search_partner_pins summary: Search pins by a given search term description: |- **This endpoint is currently in beta and not available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/).** Get the top 10 Pins by a given search term. parameters: - $ref: '#/components/parameters/query_term' - $ref: '#/components/parameters/query_country_code' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/query_locale' - $ref: '#/components/parameters/query_result_limit' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/SummaryPin' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - pins:read tags: - search x-codeSamples: - label: curl lang: cURL source: | curl --location --request GET 'https://api.pinterest.com/v5/search/partner/pins' \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' x-ratelimit-category: org_read x-sandbox: disabled /search/pins: get: operationId: search_user_pins/list summary: Search user's Pins description: |- Search for pins for the "operation user_account". - By default, the "operation user_account" is the token user_account. If using Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". See [Understanding Business Access](/docs/getting-started/using-business-access/) for more information. parameters: - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/query_required_search_query' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/Pin' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - boards:read - boards:read_secret - pins:read - pins:read_secret tags: - search x-ratelimit-category: org_read x-sandbox: disabled /terms/related: get: operationId: terms_related/list summary: List related terms description: |- Get a list of terms logically related to each input term. Example: the term 'workout' would list related terms like 'one song workout', 'yoga workout', 'workout motivation', etc. parameters: - $ref: '#/components/parameters/query_list_input_terms' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/RelatedTerms' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - terms x-ratelimit-category: ads_read x-sandbox: enabled /terms/suggested: get: operationId: terms_suggested/list summary: List suggested terms description: |- Get popular search terms that begin with your input term. Example: 'sport' would return popular terms like 'sports bar' and 'sportswear', but not 'motor sports' since the phrase does not begin with the given term. parameters: - $ref: '#/components/parameters/query_input_term' - $ref: '#/components/parameters/query_term_limit' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/TermsSuggestedResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - ads:read tags: - terms x-ratelimit-category: ads_read x-sandbox: enabled /trends/editorial_articles: get: operationId: trends_editorial_articles/list summary: Returns editorial articles for a given region description: ' Get a list of published editorial articles. Translations of the editorials will be provided if available; otherwise, the default language will be English.' parameters: - $ref: '#/components/parameters/query_product_category_detail_region' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: $ref: '#/components/schemas/TrendsEditorial' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:read tags: - trends x-ratelimit-category: trends_read x-sandbox: disabled /trends/keywords/{region}/top/{trend_type}: get: operationId: trending_keywords/list summary: List trending keywords description: |- Get the top trending search keywords among the Pinterest user audience. Trending keywords can be used to inform ad targeting, budget strategy, and creative decisions about which products and Pins will resonate with your audience. Geographic, demographic and interest-based filters are available to narrow down to the top trends among a specific audience. Multiple trend types are supported that can be used to identify newly-popular, evergreen or seasonal keywords. For an interactive way to explore this data, please visit [trends.pinterest.com](https://trends.pinterest.com). parameters: - $ref: '#/components/parameters/path_trend_region' - $ref: '#/components/parameters/path_trend_type' - $ref: '#/components/parameters/query_interest_list' - $ref: '#/components/parameters/query_gender_list' - $ref: '#/components/parameters/query_age_bucket_list' - $ref: '#/components/parameters/query_keyword_include_list' - $ref: '#/components/parameters/query_normalize_against_group' - $ref: '#/components/parameters/query_trending_keyword_limit' - $ref: '#/components/parameters/query_include_demographics' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/TrendingKeywordsResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:read tags: - keywords x-ratelimit-category: trends_read x-sandbox: enabled /trends/product_categories/details: get: operationId: trends_product_categories_details/list summary: Get product category details description: ' Enables advertisers to retrieve demographic information, related pins, and trend lines for specified product categories' parameters: - $ref: '#/components/parameters/ProductCategoryIds' - $ref: '#/components/parameters/query_product_category_detail_region' - $ref: '#/components/parameters/query_product_category_lookback_window' - $ref: '#/components/parameters/query_product_category_engagement_type' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: $ref: '#/components/schemas/ProductCategoryDetails' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:read - client_credentials: - user_accounts:read tags: - trends x-ratelimit-category: trends_read x-sandbox: disabled /trends/product_categories/trending: get: operationId: trends_product_categories_trending/list summary: Get a list of growing Shopping Product Categories description: ' Get a list of growing Shopping Product Categories in ranked order allowing filtering by engagement type, vertical, age, and gender.' parameters: - $ref: '#/components/parameters/query_product_category_detail_region' - $ref: '#/components/parameters/query_vertical_product_category' - $ref: '#/components/parameters/query_age_trends_buckets' - $ref: '#/components/parameters/query_gender_buckets' - $ref: '#/components/parameters/query_product_category_engagement_type' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: $ref: '#/components/schemas/TrendingProductCategory' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:read - client_credentials: - user_accounts:read tags: - trends x-ratelimit-category: trends_read x-sandbox: disabled /trends/topics/featured: get: operationId: trends_featured_topics/list summary: Get featured topics description: ' Enables advertisers to pull top five trending topics by interest and market, at full parity with the Pinterest Trends UI.' parameters: - $ref: '#/components/parameters/query_interest' - $ref: '#/components/parameters/query_product_category_detail_region' responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: $ref: '#/components/schemas/FeaturedTrend' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:read - client_credentials: - user_accounts:read tags: - trends x-ratelimit-category: trends_read x-sandbox: disabled /user_account: get: operationId: user_account/get summary: Get user account description: |- Get account information for the "operation user_account" - By default, the "operation user_account" is the token user_account. [Understanding Business Access]: https://developers.pinterest.com/docs/getting-started/using-business-access/ "Understanding Business Access" If using Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". See [Understanding Business Access] for more information. parameters: - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/Account' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:read - client_credentials: - user_accounts:read tags: - user_account x-ratelimit-category: org_read x-sandbox: enabled /user_account/analytics: get: operationId: user_account/analytics summary: Get user account analytics description: |- Get analytics for the "operation user_account" - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". parameters: - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_from_claimed_content' - $ref: '#/components/parameters/query_pin_format' - $ref: '#/components/parameters/query_app_types' - $ref: '#/components/parameters/query_content_type' - $ref: '#/components/parameters/query_source' - $ref: '#/components/parameters/query_metric_types' - $ref: '#/components/parameters/query_split_field_user_account' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/AnalyticsResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:read tags: - user_account x-ratelimit-category: org_analytics x-sandbox: disabled /user_account/analytics/top_pins: get: operationId: user_account/analytics/top_pins summary: Get user account top pins analytics description: |- Gets analytics data about a user's top pins (limited to the top 50). - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". parameters: - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_sort_by' - $ref: '#/components/parameters/query_from_claimed_content' - $ref: '#/components/parameters/query_pin_format' - $ref: '#/components/parameters/query_app_types' - $ref: '#/components/parameters/query_content_type' - $ref: '#/components/parameters/query_source' - $ref: '#/components/parameters/query_metric_types' - $ref: '#/components/parameters/query_num_of_pins' - $ref: '#/components/parameters/query_created_in_last_n_days' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/TopPinsAnalyticsResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - pins:read - user_accounts:read - client_credentials: - pins:read - user_accounts:read tags: - user_account x-ratelimit-category: org_analytics x-sandbox: disabled /user_account/analytics/top_video_pins: get: operationId: user_account/analytics/top_video_pins summary: Get user account top video pins analytics description: |- Gets analytics data about a user's top video pins (limited to the top 50). - By default, the "operation user_account" is the token user_account. Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account". parameters: - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_video_pin_sort_by' - $ref: '#/components/parameters/query_from_claimed_content' - $ref: '#/components/parameters/query_pin_format' - $ref: '#/components/parameters/query_app_types' - $ref: '#/components/parameters/query_content_type' - $ref: '#/components/parameters/query_source' - $ref: '#/components/parameters/query_video_pin_metric_types' - $ref: '#/components/parameters/query_num_of_pins' - $ref: '#/components/parameters/query_created_in_last_n_days' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/TopVideoPinsAnalyticsResponse' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - pins:read - user_accounts:read - client_credentials: - pins:read - user_accounts:read tags: - user_account x-ratelimit-category: org_analytics x-sandbox: disabled /user_account/businesses: get: operationId: linked_business_accounts/get summary: List linked businesses description: Get a list of your linked business accounts. responses: '200': description: The request has succeeded. content: application/json: schema: type: array items: $ref: '#/components/schemas/LinkedBusiness' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:read - client_credentials: - user_accounts:read tags: - user_account x-ratelimit-category: org_read x-sandbox: enabled /user_account/followers: get: operationId: followers/list summary: List followers description: Get a list of your followers. parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/FollowUser' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:read - client_credentials: - user_accounts:read tags: - user_account x-ratelimit-category: ads_read x-sandbox: enabled /user_account/following: get: operationId: user_following/get summary: List following description: Get a list of who a certain user follows. parameters: - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/query_explicit_following' - $ref: '#/components/parameters/query_user_following_feed_type' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/FollowUser' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:read - client_credentials: - user_accounts:read tags: - user_account x-ratelimit-category: org_read x-sandbox: disabled /user_account/following/boards: get: operationId: boards_user_follows/list summary: List following boards description: Get a list of the boards a user follows. The request returns a board summary object array. parameters: - $ref: '#/components/parameters/query_ad_account_id' - $ref: '#/components/parameters/query_explicit_following' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/Board' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:read - client_credentials: - user_accounts:read tags: - user_account x-ratelimit-category: org_read x-sandbox: enabled /user_account/following/{username}: post: operationId: follow_user/update summary: Follow user description: |- **This endpoint is currently in beta and not available to all apps. [Learn more](/docs/getting-started/using-beta-and-restricted-features/).** Use this request, as a signed-in user, to follow another user. parameters: - $ref: '#/components/parameters/path_username' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/FollowUserCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/FollowUser' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/FollowUser' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:write tags: - user_account x-ratelimit-category: org_write x-sandbox: enabled /user_account/websites: get: operationId: user_websites/get summary: Get user websites description: Get user websites, claimed or not parameters: - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/UserWebsite' required: - items '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:read tags: - user_account x-ratelimit-category: org_read x-sandbox: disabled post: operationId: verify_website/update summary: Verify website description: Verify a website as a signed-in user. parameters: - $ref: '#/components/parameters/query_ad_account_id' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UserWebsiteCreate' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/UserWebsite' '201': description: Resource create operation completed successfully. content: application/json: schema: $ref: '#/components/schemas/UserWebsite' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:write tags: - user_account x-ratelimit-category: org_write x-sandbox: disabled delete: operationId: unverify_website/delete summary: Unverify website description: Unverify a website verified by the signed-in user. parameters: - $ref: '#/components/parameters/query_website' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/UserWebsite' '204': description: Resource deleted successfully. '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:write tags: - user_account x-ratelimit-category: org_write x-sandbox: disabled /user_account/websites/verification: get: operationId: website_verification/get summary: Get user verification code for website claiming description: Get verification code for user to install on the website to claim it. parameters: - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: The request has succeeded. content: application/json: schema: $ref: '#/components/schemas/UserWebsiteVerification' '400': description: The request could not be understood by the server due to unexpected data. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Authentication is required and has either failed or not been provided. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '403': description: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The requested resource could not be found on this server. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '429': description: The user has sent too many requests in a given amount of time and is being rate limited. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: An unexpected error response. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:read - client_credentials: - user_accounts:read tags: - user_account x-ratelimit-category: org_read x-sandbox: disabled /users/{username}/interests/follow: get: operationId: user_account/followed_interests summary: List following interests description: Get a list of a user's following interests in one place. parameters: - $ref: '#/components/parameters/path_username' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.bookmark' - $ref: '#/components/parameters/Pinterest.Lib.BookmarkParams.page_size' responses: '200': description: The request has succeeded. content: application/json: schema: type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/Interest' required: - items '400': description: The server could not understand the request due to invalid syntax. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '401': description: Access is unauthorized. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' '404': description: The server cannot find the requested resource. content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Pinterest.Lib.Error' security: - pinterest_oauth2: - user_accounts:read - client_credentials: - user_accounts:read tags: - user_account x-ratelimit-category: org_read x-sandbox: enabled components: parameters: AdAccountKey: name: ad_account_id in: path required: true schema: type: string maxLength: 18 pattern: ^\d+$ AdAccountsAudienceKey: name: audience_id in: path required: true description: Audience ID. schema: type: string pattern: ^\d+$ AdAccountsGetAdditionalParams: name: include_shared_accounts in: query required: false description: Include shared ad accounts schema: type: boolean default: true AdGroupKey: name: ad_group_id in: path required: true description: Ad group ID. schema: type: string maxLength: 18 pattern: ^\d+$ AdKey: name: ad_id in: path required: true description: The ID of this ad. schema: type: string maxLength: 18 pattern: ^\d+$ AdvertiserDefinedEventsDeleteQuery: name: event_names in: query required: true description: List of event names to delete schema: type: array items: type: string explode: false aggregate_report_rows: name: aggregate_report_rows in: query required: false description: Determines if report rows should be aggregated across all requested entities. This feature is currently in BETA and is not available to all users. schema: type: boolean default: false audience_insights_query_params: name: audience_insight_type in: query required: true description: Type of audience insights. schema: $ref: '#/components/schemas/AudienceInsightType' explode: false AudienceGetAdditionalParams.exclude_nca: name: exclude_nca in: query required: false description: When true, excludes audiences derived from new customer acquisition (expanded matching) customer lists from the result. Defaults to false (include all). schema: type: boolean default: false AudienceGetAdditionalParams.ownership_type: name: ownership_type in: query required: false schema: default: OWNED $ref: '#/components/schemas/AudienceOwnershipType' BoardKey: name: board_id in: path required: true schema: type: string pattern: ^\d+$ BoardWithUpdatePrivacyKey: name: board_id in: path required: true schema: type: string pattern: ^\d+$ BrandAccountKey: name: brand_account_id in: path required: true schema: type: string BulkRequestStatusParameters.bulk_request_id: name: bulk_request_id in: path required: true description: Bulk request ID that is from one of the entities bulk endpoints schema: type: string BulkRequestStatusParameters.include_details: name: include_details in: query required: false description: If set to True then attach the errors/details to all the requests schema: type: boolean default: false CampaignKey: name: campaign_id in: path required: true description: Campaign ID, must be associated with the ad account ID provided in the path. schema: type: string maxLength: 18 pattern: ^\d+$ CatalogId: name: catalog_id in: path required: true description: Unique identifier of a catalog. schema: type: string maxLength: 19 pattern: ^\d+$ CatalogKey: name: catalog_id in: path required: true description: ID of the catalog entity. schema: type: string pattern: ^\d+$ CatalogsFieldsKey: name: catalog_id in: path required: true description: Unique identifier of a catalog. schema: type: string maxLength: 19 pattern: ^\d+$ CatalogsSupplementalFeedKey: name: feed_id in: path required: true description: Supplemental feed id generated by Pinterest. schema: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' ChangeHistoryParameters.end_time: name: end_time in: query required: true description: A Unix timestamp representing the end of the inclusive range over which Change History schema: type: integer ChangeHistoryParameters.entity_id: name: entity_id in: query required: true description: Id of the entity for which Change History will be fetched schema: type: string ChangeHistoryParameters.entity_ids: name: entity_ids in: query required: false description: An optional list of ids of the entities (with multiple entity types allowed) for which change history will be fetched schema: type: array items: type: string ChangeHistoryParameters.field_filters: name: field_filters in: query required: false description: An optional list of fields to filter on schema: type: array items: type: string ChangeHistoryParameters.start_time: name: start_time in: query required: true description: A Unix timestamp representing the start of the inclusive range over which Change History schema: type: integer ChangeHistoryParameters.user_id_filter: name: user_id_filter in: query required: false description: An optional id ensuring only data changes initiated by this specified user will be returned schema: type: integer ConversionDeletionRequestKey: name: request_id in: path required: true description: Unique identifier of the conversion deletion request schema: type: string maxLength: 18 pattern: ^\d+$ customer_segments_include_sizing: name: include_sizing in: query required: false description: Include audience sizing in result or not schema: type: boolean default: false customer_segments_search_query: name: search_query in: query required: false description: Search query. Can contain pin description keywords or comma-separated pin IDs. schema: type: string CustomerListKey.customer_list_id: name: customer_list_id in: path required: true description: Customer list ID. schema: type: string maxLength: 18 pattern: ^\d+$ CustomerListKey.id: name: ad_account_id in: path required: true schema: type: string maxLength: 18 pattern: ^\d+$ CustomerListParentKey: name: ad_account_id in: path required: true schema: type: string maxLength: 18 pattern: ^\d+$ CustomerListUploadKey.customer_list_id: name: customer_list_id in: path required: true description: Customer list ID. schema: type: string maxLength: 18 pattern: ^\d+$ CustomerListUploadKey.customer_list_upload_id: name: customer_list_upload_id in: path required: true description: Customer List Upload ID. schema: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' maxLength: 18 CustomerListUploadKey.id: name: ad_account_id in: path required: true schema: type: string maxLength: 18 pattern: ^\d+$ CustomerListUploadParentKey.customer_list_id: name: customer_list_id in: path required: true description: Customer list ID. schema: type: string maxLength: 18 pattern: ^\d+$ CustomerListUploadParentKey.id: name: ad_account_id in: path required: true schema: type: string maxLength: 18 pattern: ^\d+$ DealDiscountKey: name: discount_id in: path required: true description: Deal discount ID. schema: type: string pattern: ^\d+$ EventQualityScoreListParams.ingestion_source: name: ingestion_source in: query required: false description: Ingestion source of event. schema: $ref: '#/components/schemas/IngestionSourceOptions' EventQualityScoreListParams.lookback_period: name: lookback_period in: query required: true description: Lookback window (number of days). schema: $ref: '#/components/schemas/LookbackPeriodOptions' EventQualityScoreListParams.source_platform: name: source_platform in: query required: false description: Source platform of event. schema: $ref: '#/components/schemas/SourcePlatformOptions' EventsCreateQueryParams: name: test in: query required: false description: |- Include query param ?test=true to mark the request as a test request. The events will not be recorded but the API will still return the same response messages. Use this mode to verify your requests are working and your events are constructed correctly. Warning: If you use this query parameter, be certain that it is off (set to false or deleted) before sending a legitimate (non-testing) request. schema: type: boolean GoalUpsertKey: name: ad_account_id in: path required: true schema: type: string maxLength: 18 pattern: ^\d+$ IntegrationRecordKey: name: id in: path required: true description: Integration record ID. schema: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' ItemsBatchId: name: batch_id in: path required: true description: Unique identifier of an items batch operation. schema: type: string pattern: ^\d+$ LabeledEntitiesKey.id: name: ad_account_id in: path required: true schema: type: string maxLength: 18 pattern: ^\d+$ LabeledEntitiesKey.label_id: name: label_id in: path required: true description: Label ID. schema: type: string LeadFormKey: name: lead_form_id in: path required: true description: The ID of this lead form schema: type: string pattern: ^\d+$ LeadFormTestKey.id: name: ad_account_id in: path required: true schema: type: string maxLength: 18 pattern: ^\d+$ LeadFormTestKey.lead_form_id: name: lead_form_id in: path required: true description: Unique identifier of a lead form. schema: type: string pattern: ^\d+$ LeadZapierWebhookKey: name: hook_id in: path required: true description: Unique identifier of a zapier webhook. schema: type: string pattern: ^\d+$ MediaKey: name: media_id in: path required: true description: |- Unique identifier for this media upload. Used to track status and for attaching during Pin creation. schema: type: string pattern: ^\d+$ MMMReportKey: name: ad_account_id in: path required: true schema: type: string maxLength: 18 pattern: ^\d+$ OrderLineKey: name: order_line_id in: path required: true description: Order line ID. schema: type: string pattern: ^\d+$ path_ad_group_id: name: ad_group_id in: path required: true description: Ad group ID. schema: type: string maxLength: 18 pattern: ^\d+$ path_ad_id: name: ad_id in: path required: true description: Unique identifier of an ad. schema: type: string maxLength: 18 pattern: ^\d+$ path_aggregated_pin_data: name: aggregated_pin_data in: path required: true description: Id of aggregated pin data schema: type: string pattern: ^\d+$ path_asset_id: name: asset_id in: path required: true description: Unique identifier of a business asset. schema: type: string maxLength: 20 minLength: 1 pattern: ^\d+$ path_billing_invoice_id: name: billing_invoice_id in: path required: true description: Unique identifier of a billing invoice. schema: type: string maxLength: 18 pattern: ^\d+$ path_board_id: name: board_id in: path required: true description: Unique identifier of a board. schema: type: string pattern: ^\d+$ path_board_section_id: name: section_id in: path required: true description: Unique identifier of a board section. schema: type: string pattern: ^\d+$ path_business_hierarchy_id: name: business_hierarchy_id in: path required: true description: business hierarchy node id schema: type: string maxLength: 20 minLength: 1 pattern: ^\d+$ path_business_id: name: business_id in: path required: true description: Business id schema: type: string maxLength: 20 minLength: 1 pattern: ^\d+$ path_business_member_user: name: member_id in: path required: true description: The member id to fetch assets for. schema: type: string maxLength: 20 minLength: 1 pattern: ^\d+$ path_business_user: name: business_id in: path required: true description: Unique identifier of the requesting business. schema: type: string maxLength: 20 minLength: 1 pattern: ^\d+$ path_catalogs_feed_id: name: feed_id in: path required: true description: Unique identifier of a feed. schema: type: string pattern: ^\d+$ path_catalogs_items_batch_id: name: batch_id in: path required: true description: Id of a catalogs items batch to fetch schema: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' pattern: ^\d+$ path_catalogs_processing_result_id: name: processing_result_id in: path required: true description: Unique identifier of a feed processing result. It can be acquired from the "id" field of the "items" array within the response of the [List processing results for a given feed](/docs/api/v5/#operation/feed_processing_results/list). schema: type: string pattern: ^\d+$ path_conversion_tag_id: name: conversion_tag_id in: path required: true description: Id of the conversion tag. schema: type: string maxLength: 18 pattern: ^\d+$ path_external_business_id: name: external_business_id in: path required: true description: External business ID for the integration. schema: type: string path_interest_id: name: interest_id in: path required: true description: Unique identifier of an interest. schema: type: string maxLength: 18 pattern: ^\d+$ path_leads_export_id: name: leads_export_id in: path required: true description: lead_export_id token returned from the create a lead export endpoint schema: type: string pattern: ^\d+$ path_non_system_business_user: name: business_id in: path required: true description: Unique identifier of the requesting business. schema: type: string minLength: 1 pattern: ^\d+$ path_partner: name: partner_id in: path required: true description: The partner id to be bound to the Business schema: type: string maxLength: 20 minLength: 1 pattern: ^\d+$ path_pin_id: name: pin_id in: path required: true description: Unique identifier of a Pin. schema: type: string path_pin_order_id: name: pin_order_id in: path required: true description: The pin order id associated with the ssio insertion order schema: type: string path_product_group_id: name: product_group_id in: path required: true description: Unique identifier of a product group schema: type: string pattern: ^\d+$ path_product_group_promotion_id: name: product_group_promotion_id in: path required: true description: Unique identifier of a product group promotion schema: type: string maxLength: 18 pattern: ^\d+$ path_system_user_id: name: system_user_id in: path required: true description: Unique identifier of a system user. schema: type: string maxLength: 20 minLength: 1 pattern: ^\d+$ path_targeting_type: name: targeting_type in: path required: true description: Public targeting type schema: $ref: '#/components/schemas/PublicTargetingType' path_trend_region: name: region in: path required: true description: |2- The geographic region of interest. Only top trends within the specified region will be returned. The `region` parameter is formatted as ISO 3166-2 country codes delimited by `+`, corresponding to the following geographic areas: - `US` - United States - `CA` - Canada - `DE` - Germany - `FR` - France - `ES` - Spain - `IT` - Italy - `DE+AT+CH` - Germanic countries - `GB+IE` - Great Britain & Ireland - `IT+ES+PT+GR+MT` - Southern Europe - `PL+RO+HU+SK+CZ` - Eastern Europe - `SE+DK+FI+NO` - Nordic countries - `NL+BE+LU` - Benelux - `AR` - Argentina - `BR` - Brazil - `CO` - Colombia - `MX` - Mexico - `MX+AR+CO+CL` - Hispanic LatAm - `AU+NZ` - Australasia schema: $ref: '#/components/schemas/TrendsSupportedRegion' path_trend_type: name: trend_type in: path required: true description: |2- The methodology used to rank how trendy a keyword is. - `growing` trends have high upward growth in search volume over the last quarter - `monthly` trends have high search volume in the last month - `yearly` trends have high search volume in the last year - `seasonal` trends have high upward growth in search volume over the last month and exhibit a seasonal recurring pattern (typically annual) schema: $ref: '#/components/schemas/TrendType' path_username: name: username in: path required: true description: A valid username schema: type: string pattern: (?!^\d+$)^.+$ PinKey: name: pin_id in: path required: true schema: type: string pattern: ^\d+$ Pinterest.Lib.AdAccountId: name: ad_account_id in: path required: true description: Unique identifier of an ad account. schema: type: string maxLength: 18 pattern: ^\d+$ Pinterest.Lib.BookmarkParams.bookmark: name: bookmark in: query required: false description: Cursor used to fetch the next page of items schema: type: string Pinterest.Lib.BookmarkParams.page_size: name: page_size in: query required: false description: |- Maximum number of items to include in a single page. See documentation on [Pagination](/docs/reference/pagination/) for more information. schema: type: integer default: 25 maximum: 250 minimum: 1 Pinterest.Lib.OrderingParams: name: order in: query required: false description: |- The order in which to sort the items returned: "ASCENDING" or "DESCENDING" by ID. Note that higher-value IDs are associated with more-recently added items. schema: default: ASCENDING $ref: '#/components/schemas/Pinterest.Lib.PaginationOrder' PlanKey: name: plan_id in: path required: true description: Plan ID. schema: type: string maxLength: 18 pattern: ^\d+$ product_group_promotions_list_query.entity_statuses: name: entity_statuses in: query required: false description: Entity status schema: type: array items: $ref: '#/components/schemas/EntityStatus' default: - ACTIVE - PAUSED product_group_promotions_list_query.product_group_promotion_ids: name: product_group_promotion_ids in: query required: false description: List of Product group promotion Ids. schema: type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' maxItems: 250 minItems: 1 ProductCategoryIds: name: product_categories in: query required: true description: List of product categories schema: type: array items: $ref: '#/components/schemas/ProductCategoryEnum' maxItems: 20 minItems: 1 ProductTagsHeroPinId: name: pin_id in: path required: true description: Unique identifier of the hero pin that will receive product tags. schema: type: string pattern: ^\d+$ PromotionKey: name: promotion_id in: path required: true description: Promotion ID schema: type: string maxLength: 18 pattern: ^\d+$ query_account_type: name: account_type in: query required: true description: Filter accounts by account type. schema: default: AD_ACCOUNT $ref: '#/components/schemas/AudienceAccountType' query_active_bookmark_params.bookmark: name: bookmark in: query required: false description: Cursor used to fetch the next page of items schema: type: string query_active_bookmark_params.page_size: name: page_size in: query required: false description: |- Maximum number of items to include in a single page. See documentation on [Pagination](/docs/reference/pagination/) for more information. schema: type: integer default: 25 maximum: 250 minimum: 1 query_ad_account_id: name: ad_account_id in: query required: false description: Unique identifier of an ad account. schema: type: string maxLength: 18 pattern: ^\d+$ query_ad_account_statuses_filter: name: ad_account_statuses in: query required: false description: A list of ad account statuses to filter the assets by. Only used when asset_type is AD_ACCOUNT. schema: type: array items: $ref: '#/components/schemas/NonDraftEntityStatus' query_ad_account_targeting_types: name: targeting_types in: query required: true description: Targeting type breakdowns for the report. The reporting per targeting type is independent from each other. ["AGE_BUCKET_AND_GENDER"] is in BETA and not yet available to all users. schema: type: array items: $ref: '#/components/schemas/AdsAnalyticsAccountTargetingType' maxItems: 15 minItems: 1 explode: false query_ad_group_id: name: ad_group_id in: query required: false description: Ad group Id. schema: type: string maxLength: 18 pattern: ^\d+$ query_ad_group_ids: name: ad_group_ids in: query required: false description: List of Ad group Ids to retrieve keywords from. This feature is currently in BETA and is not available to all users. schema: type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' maxItems: 250 minItems: 1 query_ad_group_ids_required: name: ad_group_ids in: query required: true description: List of Ad group Ids to use to filter the results. schema: type: array items: $ref: '#/components/schemas/AdGroupIdType' maxItems: 250 minItems: 1 query_ad_group_targeting_types: name: targeting_types in: query required: true description: Targeting type breakdowns for the report. The reporting per targeting type is independent from each other. ["AGE_BUCKET_AND_GENDER", "CREATIVE_ENHANCEMENTS"] are in BETA and not yet available to all users. schema: type: array items: $ref: '#/components/schemas/AdsAnalyticsAdGroupTargetingType' maxItems: 14 minItems: 1 explode: false query_ad_ids: name: ad_ids in: query required: false description: List of Ad Ids to use to filter the results. schema: type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' maxItems: 250 minItems: 1 query_ad_ids_required: name: ad_ids in: query required: true description: List of Ad Ids to use to filter the results. schema: type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' maxItems: 250 minItems: 1 query_ad_targeting_types: name: targeting_types in: query required: true description: Targeting type breakdowns for the report. The reporting per targeting type is independent from each other. ["AGE_BUCKET_AND_GENDER"] is in BETA and not yet available to all users. schema: type: array items: $ref: '#/components/schemas/AdsAnalyticsAdTargetingType' maxItems: 14 minItems: 1 explode: false query_age_bucket_list: name: ages in: query required: false description: |- If set, filters the results to trends among users in the specified age range(s). If unset, trends among all age groups will be returned. schema: type: array items: $ref: '#/components/schemas/TrendsAgeBucket' query_age_trends_buckets: name: ages in: query required: false description: Age to filter by. If not provided, the results will be filtered by all ages. schema: type: array items: $ref: '#/components/schemas/AgeTrendsBucket' query_app_types: name: app_types in: query required: false description: Apps or devices to get data for, default is all. schema: type: string default: ALL enum: - ALL - MOBILE - TABLET - WEB query_asset_group_id: name: asset_group_id in: query required: false description: An asset group unique identifier. Used to fetch assets contained within the specified asset group. schema: type: string maxLength: 20 minLength: 1 pattern: ^\d+$ query_asset_permission_type: name: asset_permission_type in: query required: false description: The type of asset permission to filter by schema: $ref: '#/components/schemas/AssetPermissionType' query_asset_search_by: name: search_by in: query required: false description: The field to search member assets by schema: $ref: '#/components/schemas/AssetSearchBy' query_asset_search_value: name: search_value in: query required: false description: The value to search for schema: type: string query_asset_sort_ascending: name: sort_ascending in: query required: false description: Sort assets in ascending order schema: type: boolean default: true query_asset_sort_by: name: sort_by in: query required: false description: The field to sort member assets by schema: $ref: '#/components/schemas/AssetSortBy' query_assets_summary: name: assets_summary in: query required: false description: |- Include assets summary in the response if this is true. The assets summary returns a dictionary representing a summary of the assets for the business user ID, with information like the ad accounts and profiles the user has permissions for and what those permissions are schema: type: boolean default: false query_assets_summary_default_true: name: assets_summary in: query required: false description: |- Include assets summary in the response if this is true. Defaults to true. The assets summary returns a dictionary representing a summary of the assets for the business user ID, with information like the ad accounts and profiles the user has permissions for and what those permissions are schema: type: boolean default: true query_attribution_types: name: attribution_types in: query required: false description: List of types of attribution for the conversion report schema: type: array items: $ref: '#/components/schemas/ConversionReportAttributionType' maxItems: 2 explode: false query_audience_id: name: audience_id in: query required: true description: Unique identifier of the audience to use to filter the results. schema: type: string maxLength: 18 pattern: ^\d+$ query_billing_document_type: name: document_type in: query required: false description: Document type of billing invoices to filter by schema: $ref: '#/components/schemas/BillingInvoiceDocumentType' query_billing_end_due_date: name: end_due_date in: query required: false description: 'Ending point for due dates when searching for invoices. Format: YYYY-MM-DD' schema: type: string format: date query_billing_invoice_status: name: status in: query required: false description: Status of billing invoices to filter by schema: $ref: '#/components/schemas/BillingInvoiceStatus' query_billing_profiles_is_active: name: is_active in: query required: true description: Return active billing profiles, if false return all billing profiles. schema: type: boolean query_billing_start_due_date: name: start_due_date in: query required: false description: 'Starting point for due dates when searching for invoices. Format: YYYY-MM-DD' schema: type: string format: date query_board_privacy: name: privacy in: query required: false description: The privacy level of the board schema: $ref: '#/components/schemas/BoardPrivacyFilter' query_business_access_start_index: name: start_index in: query required: false description: An index to start fetching the results from. Only the results starting from this index will be returned. schema: type: integer default: 0 minimum: 0 query_business_partner_type_default: name: partner_type in: query required: false description: |- Specifies whether to fetch internal or external (shared) partners. If partner_type=INTERNAL, the asset being queried is for accesses the partner has to your business assets. If partner_type=EXTERNAL, the asset being queried is for the accesses you have to the partner's business asset. schema: type: string default: INTERNAL enum: - INTERNAL - EXTERNAL query_campaign_id: name: campaign_id in: query required: false description: Campaign Id to use to filter the results. schema: type: string maxLength: 18 pattern: ^\d+$ query_campaign_id_required: name: campaign_id in: query required: true description: Campaign Id to use to filter the results. schema: type: string maxLength: 18 pattern: ^\d+$ query_campaign_ids: name: campaign_ids in: query required: false description: List of Campaign Ids to use to filter the results. schema: type: array items: $ref: '#/components/schemas/CampaignIdType' maxItems: 250 minItems: 1 query_campaign_ids_required: name: campaign_ids in: query required: true description: List of Campaign Ids to use to filter the results. schema: type: array items: $ref: '#/components/schemas/CampaignIdRequiredType' maxItems: 250 minItems: 1 query_campaign_targeting_types: name: targeting_types in: query required: true description: Targeting type breakdowns for the report. The reporting per targeting type is independent from each other. ["AGE_BUCKET_AND_GENDER"] is in BETA and not yet available to all users. schema: type: array items: $ref: '#/components/schemas/AdsAnalyticsCampaignTargetingType' maxItems: 14 minItems: 1 explode: false query_catalogs_catalog_id: name: catalog_id in: query required: false description: Filter entities for a given catalog_id. If not given, all catalogs are considered. schema: type: string pattern: ^\d+$ query_catalogs_catalog_id_required: name: catalog_id in: query required: true description: Filter entities for a given catalog_id. schema: type: string pattern: ^\d+$ query_catalogs_country: name: country in: query required: false description: Country for the Catalogs Items schema: $ref: '#/components/schemas/Country' query_catalogs_feed_id: name: feed_id in: query required: false description: Filter entities for a given feed_id. If not given, all feeds are considered. schema: type: string pattern: ^\d+$ explode: false query_catalogs_item_numbers: name: item_numbers in: query required: false description: Item number based on order of appearance in the Catalogs Feed. For example, '0' refers to first item found in a feed that was downloaded from a 'location' specified during feed creation. schema: type: array items: type: integer query_catalogs_item_validation_issue: name: item_validation_issue in: query required: false description: Filter item validation issues that have a given type of item validation issue. schema: $ref: '#/components/schemas/CatalogsItemValidationIssue' query_catalogs_language: name: language in: query required: false description: Language for the Catalogs Items schema: $ref: '#/components/schemas/CatalogsLocale' query_catalogs_product_group_ids: name: id in: query required: false description: Comma-separated list of product group ids schema: type: array items: type: integer maxItems: 1000 minItems: 1 explode: false query_catalogs_product_group_ids_required: name: id in: query required: true description: Comma-separated list of product group ids schema: type: array items: type: integer maxItems: 1000 minItems: 1 explode: false query_catalogs_report_stats_parameters: name: parameters in: query required: true description: Contains the parameters for report identification. schema: $ref: '#/components/schemas/CatalogsReportStatsParameters' query_child_asset_id: name: child_asset_id in: query required: false description: A child asset unique identifier. Used to fetch asset groups that contain the asset id as a child. schema: type: string maxLength: 20 minLength: 1 pattern: ^\d+$ query_client_id: name: client_id in: query required: false description: Client ID schema: type: string maxLength: 18 pattern: ^\d+$ query_columns: name: columns in: query required: true description: |- Columns to retrieve, encoded as a comma-separated string. **NOTE**: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD, ($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency. For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound). If a column has no value, it may not be returned. schema: type: array items: $ref: '#/components/schemas/ReportingColumnSync' explode: false query_comment_feed_type: name: feed_type in: query required: false description: Comment feed type. schema: type: string default: recent enum: - ranked - recent query_content_type: name: content_type in: query required: false description: Filter to paid or organic data. Default is all. schema: type: string default: ALL enum: - ALL - PAID - ORGANIC query_conversion_attribution_click_window_days: name: click_window_days in: query required: false description: Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days. schema: type: number default: 30 enum: - 0 - 1 - 7 - 14 - 30 - 60 query_conversion_attribution_click_window_daysOptimal: name: click_window_days in: query required: false description: Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days. schema: default: 30 $ref: '#/components/schemas/ConversionAttributionWindowDays' query_conversion_attribution_conversion_report_time: name: conversion_report_time in: query required: false description: 'The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event.' schema: type: string default: TIME_OF_AD_ACTION enum: - TIME_OF_AD_ACTION - TIME_OF_CONVERSION query_conversion_attribution_engagement_window_days: name: engagement_window_days in: query required: false description: Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days. **Note:** This parameter no longer returns new data. However, you can still access historic data through **Sept 30, 2027**. schema: type: number default: 30 enum: - 0 - 1 - 7 - 14 - 30 - 60 query_conversion_attribution_engagement_window_daysOptimal: name: engagement_window_days in: query required: false description: Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days. **Note:** This parameter no longer returns new data. However, you can still access historic data through **Sept 30, 2027**. schema: default: 30 $ref: '#/components/schemas/ConversionAttributionWindowDays' query_conversion_attribution_view_window_days: name: view_window_days in: query required: false description: Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `1` day. schema: type: number default: 1 enum: - 0 - 1 - 7 - 14 - 30 - 60 query_conversion_attribution_view_window_daysOptimal: name: view_window_days in: query required: false description: Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `1` day. schema: default: 1 $ref: '#/components/schemas/ConversionAttributionWindowDays' query_conversion_report_time: name: conversion_report_time in: query required: false description: 'The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event.' schema: default: TIME_OF_AD_ACTION $ref: '#/components/schemas/ConversionReportTimeType' query_country_code: name: country_code in: query required: true description: Two letter country code (ISO 3166-1 alpha-2) schema: type: string query_created_in_last_n_days: name: created_in_last_n_days in: query required: false description: Get metrics for pins created in the last "n" days. schema: type: number enum: - 30 query_creative_types: name: creative_types in: query required: false description: Pin creative types filter. **Note:** SHOP_THE_PIN has been deprecated. Please use COLLECTION instead. schema: type: array items: $ref: '#/components/schemas/CreativeType' query_domain: name: domain in: query required: false description: Only return pins with links that match the exact domain. Domain should not include 'www.' prefix. For example, 'pinterest.com' is a valid domain, but 'www.pinterest.com' is not (will not match any pins). schema: type: string query_domains: name: domains in: query required: false description: |- Only return pins with links whose domain matches any value in the list. Values are joined comma-separated on the wire (e.g. `?domains=instagram.com,jcpenney.com`). schema: type: array items: type: string maxItems: 100 minItems: 1 query_end_date: name: end_date in: query required: true description: 'Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date.' schema: type: string format: date query_end_date_async: name: end_date in: query required: false description: 'Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 2.5 years past start date.' schema: type: string format: date query_entity_statuses: name: entity_statuses in: query required: false description: Entity status schema: type: array items: $ref: '#/components/schemas/EntityStatus' default: - ACTIVE - PAUSED query_exclude_nca: name: exclude_nca in: query required: false description: When true, excludes customer lists uploaded for new customer acquisition (expanded matching) from the result. Defaults to false (include all). schema: type: boolean default: false query_explicit_following: name: explicit_following in: query required: false description: |- Whether or not to include implicit user follows, which means followees with board follows. When explicit_following is True, it means we only want explicit user follows. schema: type: boolean default: false query_fetch_system_users: name: fetch_system_users in: query required: false description: Fetches system users if True. Fetches regular user employees if False. schema: type: boolean default: false query_filter_deleted: name: filter_deleted in: query required: false description: Filter by deleted status schema: type: boolean default: false query_from_claimed_content: name: from_claimed_content in: query required: false description: Filter on Pins that match your claimed domain. schema: type: string default: BOTH enum: - OTHER - CLAIMED - BOTH query_gender_buckets: name: genders in: query required: false description: Gender to filter by, If not provided, the results will be filtered by all genders. schema: type: array items: $ref: '#/components/schemas/GenderBucket' query_gender_list: name: genders in: query required: false description: |- If set, filters the results to trends among users who identify with the specified gender(s). If unset, trends among all genders will be returned. The `unknown` group includes users with unspecified or customized gender profile settings. schema: type: array items: $ref: '#/components/schemas/TrendsGenderFilter' query_granularity: name: granularity in: query required: true description: |2- TOTAL - metrics are aggregated over the specified date range. DAY - metrics are broken down daily. HOUR - metrics are broken down hourly. WEEK - metrics are broken down weekly. MONTH - metrics are broken down monthly schema: $ref: '#/components/schemas/Granularity' query_granularity_async: name: granularity in: query required: false description: |2- TOTAL - metrics are aggregated over the specified date range. DAY - metrics are broken down daily. HOUR - metrics are broken down hourly. WEEK - metrics are broken down weekly. MONTH - metrics are broken down monthly schema: $ref: '#/components/schemas/Granularity' query_include_demographics: name: include_demographics in: query required: false description: |- Including the age and gender distribution for each keyword. By default (`false`), the response will not include demographics data. schema: type: boolean default: false query_include_product_tag_obj: name: include_product_tag_obj in: query required: false description: Include product tag objects in the response with their associated links. schema: type: boolean query_include_protected_pins: name: include_protected_pins in: query required: false description: Whether to include protected pins in the results schema: type: boolean default: false query_input_term: name: term in: query required: true description: Input term. schema: type: string query_interest: name: interest in: query required: false description: Interest to filter by schema: $ref: '#/components/schemas/InterestsEnum' query_interest_list: name: interests in: query required: false description: |2- The list of supported interests is: - `animals` - Animals - `architecture` - Architecture - `art` - Art - `beauty` - Beauty - `childrens_fashion` - Children's Fashion - `design` - Design - `diy_and_crafts` - DIY & Crafts - `education` - Education - `electronics` - Electronics - `entertainment` - Entertainment - `event_planning` - Event Planning - `finance` - Finance - `food_and_drinks` - Food & Drink - `gardening` - Gardening - `health` - Health - `home_decor` - Home Decor - `mens_fashion` - Men's Fashion - `parenting` - Parenting - `quotes` - Quotes - `sport` - Sports - `travel` - Travel - `vehicles` - Vehicles - `wedding` - Wedding - `womens_fashion` - Women's Fashion schema: type: array items: $ref: '#/components/schemas/TrendsL1Interest' query_invite_status: name: invite_status in: query required: false description: A list of invite statuses to filter invites by. Only invites whose status is in the provided statuses will be returned. schema: type: array items: $ref: '#/components/schemas/InviteFilterStatus' minItems: 1 query_invite_type: name: invite_type in: query required: false description: Invite type to filter invites by. Only invites of the specified type will be returned. schema: $ref: '#/components/schemas/InviteType' query_is_member: name: is_member in: query required: false description: A boolean field to indicate whether the invite is to create a partnership or a membership. schema: type: boolean default: true query_keyword_include_list: name: include_keywords in: query required: false description: |- If set, filters the results to top trends which include at least one of the specified keywords. If unset, no keyword filtering logic is applied. schema: $ref: '#/components/schemas/KeywordList' query_keywords: name: keywords in: query required: true description: Comma-separated keywords schema: type: array items: type: string maxItems: 2000 minItems: 1 explode: false query_label_entity_statuses: name: entity_statuses in: query required: false description: Label entity status schema: type: array items: $ref: '#/components/schemas/QueryLabelEntityStatusesItems' default: - ACTIVE query_label_ids: name: label_ids in: query required: false description: List of Label Ids to use to filter the results. schema: type: array items: $ref: '#/components/schemas/QueryLabelIdsItems' maxItems: 250 minItems: 1 query_label_types: name: label_types in: query required: false description: Label type. schema: type: array items: $ref: '#/components/schemas/QueryLabelTypesItems' default: - BRAND - CUSTOM query_list_input_terms: name: terms in: query required: true description: List of input terms. schema: type: array items: type: string query_local_store_ids: name: ids in: query required: false description: List of local store IDs to filter by. schema: type: array items: $ref: '#/components/schemas/LocalStoreId' explode: false query_local_store_ids_required: name: ids in: query required: true description: List of local store IDs to filter by. schema: type: array items: $ref: '#/components/schemas/LocalStoreId' explode: false query_locale: name: locale in: query required: false description: Search locale. schema: type: string query_match_types: name: match_types in: query required: false description: Keyword [match type](/docs/api-features/targeting-overview/) schema: type: array items: $ref: '#/components/schemas/MatchType' maxItems: 5 minItems: 1 query_member_business_roles: name: business_roles in: query required: false description: A list of business roles to filter the members by. Only members whose roles are in the specified roles will be returned. schema: type: array items: $ref: '#/components/schemas/MemberBusinessRole' query_member_ids: name: member_ids in: query required: false description: A list of business members ids separated by comma. schema: type: string maxLength: 500 query_metric_types: name: metric_types in: query required: false description: Metric types to get data for, default is all. schema: type: array items: $ref: '#/components/schemas/QuerymetrictypesItems' explode: false query_metrics_ready_state_date: name: date in: query required: true description: 'Analytics reports request date (UTC). Format: YYYY-MM-DD' schema: type: string pattern: ^\d{4}-\d{2}-\d{2}$ query_multi_pins_analytics_metric_types: name: metric_types in: query required: true description: Pin metric types to get data for. schema: type: array items: $ref: '#/components/schemas/MultiPinsAnalyticsMetricTypesItem' explode: false query_normalize_against_group: name: normalize_against_group in: query required: false description: |2- Governs how the resulting time series data will be normalized to a [0-100] scale. By default (`false`), the data will be normalized independently for each keyword. The peak search volume observation in *each* keyword's time series will be represented by the value 100. This is ideal for analyzing when an individual keyword is expected to peak in interest. If set to `true`, the data will be normalized as a group. The peak search volume observation across *all* keywords in the response will be represented by the value 100, and all other values scaled accordingly. Use this option when you wish to compare relative search volume between multiple keywords. schema: type: boolean default: false query_num_of_pins: name: num_of_pins in: query required: false description: Number of pins to include, default is 10. Max is 50. schema: type: integer default: 10 maximum: 50 minimum: 1 query_oauth_signature: name: oauth_signature in: query required: false description: Oauth signature schema: type: string query_order: name: order in: query required: false description: 'The order in which to sort the items returned: "ASCENDING" or "DESCENDING" by ID. Note that higher-value IDs are associated with more-recently added items.' schema: $ref: '#/components/schemas/Order' query_partner_ids: name: partner_ids in: query required: false description: A list of business partner ids separated by commas used to filter the results. Only partners with the specified ids will be returned. schema: type: string maxLength: 500 query_partner_type: name: partner_type in: query required: false description: |- Specifies whether to fetch internal or external (shared) partners. If partner_type=INTERNAL, the asset being queried is for accesses the partner has to your business assets. If partner_type=EXTERNAL, the asset being queried is for the accesses you have to the partner's business asset. schema: $ref: '#/components/schemas/PartnerType' query_permissions_with_owner: name: permissions in: query required: false description: A list of asset permissions used to filter the assets. Only assets where the requesting business has at least one of the specified permissions will be returned. schema: type: array items: $ref: '#/components/schemas/PermissionsWithOwner' query_pin_analytics_metric_types: name: metric_types in: query required: true description: Pin metric types to get data for. VIDEO_MRC_VIEW are Video views, VIDEO_V50_WATCH_TIME is Total play time. If Pin was created before `2023-03-20`, Profile visits and Follows will only be available for Idea Pins. These metrics are available for all Pin formats since then. Keep in mind this cannot have ALL if split_field is set to any value other than `NO_SPLIT`. schema: type: array items: $ref: '#/components/schemas/QuerypinanalyticsmetrictypesItems' explode: false query_pin_filter: name: pin_filter in: query required: false description: The filter to apply to the pins schema: $ref: '#/components/schemas/PinFilter' query_pin_format: name: pin_format in: query required: false description: Pin formats to get data for, default is all. schema: type: string default: ALL enum: - ALL - ORGANIC_IMAGE - ORGANIC_PRODUCT - ORGANIC_VIDEO - ADS_STANDARD - ADS_PRODUCT - ADS_VIDEO - ADS_IDEA query_pin_metrics: name: pin_metrics in: query required: false description: |- Specify whether to return 90d and lifetime Pin metrics. Total comments and total reactions are only available with lifetime Pin metrics. If Pin was created before `2023-03-20` lifetime metrics will only be available for Video and Idea Pin formats. Lifetime metrics are available for all Pin formats since then. schema: type: boolean default: false query_pin_order_id: name: pin_order_id in: query required: false description: The pin order id associated with the SSIO insertion order schema: type: string query_pin_type: name: pin_type in: query required: false description: The type of pins to return, currently only enabled for private pins schema: $ref: '#/components/schemas/PinType' query_product_category_detail_region: name: region in: query required: true description: |2- The geographic region of interest. Only top product categories within the specified region will be returned. The `region` parameter is formatted as ISO 3166-2 country codes delimited by `+`. - `US` - United States - `GB+IE` - Great Britain & Ireland - `CA` - Canada schema: $ref: '#/components/schemas/ProductCategoryRegion' query_product_category_engagement_type: name: engagement_type in: query required: false description: |2- Type of engagement metric to analyze. - `ENGAGEMENT` - Overall engagement metric - `OUTBOUND_CLICK` - Number of outbound clicks - `SAVE` - Number of pin saves schema: default: ENGAGEMENT $ref: '#/components/schemas/ProductCategoriesEngagementType' query_product_category_lookback_window: name: lookback_window in: query required: false description: |2- Time period for historical data analysis in days. The lookback window defines how far back in time the API will analyze data to compute trend metrics. - `90` - Last 90 days (3 months) - `180` - Last 180 days (6 months) - `365` - Last 365 days (1 year) - `730` - Last 730 days (2 years) schema: default: 365 $ref: '#/components/schemas/ProductCategoryDetailLookbackWindow' query_product_group_ids_required: name: product_group_ids in: query required: true description: List of Product group Ids to use to filter the results. schema: type: array items: $ref: '#/components/schemas/ProductGroupIdType' maxItems: 250 minItems: 1 query_promotion_ids: name: promotion_ids in: query required: true description: List of Promotion IDs to use to filter the results. schema: type: array items: type: string maxItems: 50 minItems: 1 query_query: name: query in: query required: false description: |- Search query. Can contain pin description keywords or comma-separated pin IDs. schema: type: string query_report_token_required: name: token in: query required: true description: Token returned from the post request creation call schema: type: string query_report_type: name: report_type in: query required: false description: Report type. schema: $ref: '#/components/schemas/ReportType' query_reporting_timezone: name: reporting_timezone in: query required: false description: Specify the timezone to be applied for the reporting. This feature is currently in BETA and is not available to all users. schema: $ref: '#/components/schemas/ReportingTimeZone' query_required_pin_ids: name: pin_ids in: query required: true description: List of Pin IDs. schema: type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' maxItems: 100 minItems: 1 query_required_search_query: name: query in: query required: true description: Search query. Can contain pin description keywords or comma-separated pin IDs. schema: type: string query_resource_type: name: asset_type in: query required: false description: A resource type to filter the assets by. Only assets of the specified type will be returned. schema: type: string default: AD_ACCOUNT enum: - AD_ACCOUNT - PROFILE - ASSET_GROUP - CATALOG - CONSUMER query_resource_type_internal: name: asset_type in: query required: false description: A resource type to filter the assets by. Only assets of the specified type will be returned. schema: type: string default: AD_ACCOUNT enum: - AD_ACCOUNT - PROFILE - ASSET_GROUP - PINNER_LIST - CONVERSION_TAG - CATALOG - CONSUMER - CONVERSION_SEGMENT query_resource_type_with_conversion_tag: name: asset_type in: query required: false description: A resource type to filter the assets by. Only assets of the specified type will be returned. schema: type: string default: AD_ACCOUNT enum: - AD_ACCOUNT - PROFILE - ASSET_GROUP - CATALOG - CONSUMER - CONVERSION_TAG query_result_limit: name: limit in: query required: false description: Max search result size schema: type: integer default: 10 maximum: 50 minimum: 1 query_sort_ascending: name: sort_ascending in: query required: false description: Sort ascending. schema: type: boolean query_sort_billing_invoice: name: sort in: query required: false description: Field of which to sort billing invoices schema: $ref: '#/components/schemas/BillingInvoiceSortField' query_sort_by: name: sort_by in: query required: true description: Specify sorting order for metrics schema: $ref: '#/components/schemas/TopPinsSortBy' explode: false query_sort_columns: name: sort_columns in: query required: false description: Sort Columns. schema: type: array items: type: string maxItems: 2 minItems: 1 query_source: name: source in: query required: false description: Filter to activity from Pins created and saved by your, or activity created and saved by others from your claimed accounts schema: type: string default: ALL enum: - ALL - YOUR_PINS - OTHER_PINS query_split_field_pins: name: split_field in: query required: false description: How to split the data into groups. Not including this param means data won't be split. schema: type: string default: NO_SPLIT enum: - NO_SPLIT - APP_TYPE explode: false query_split_field_user_account: name: split_field in: query required: false description: How to split the data into groups. Not including this param means data won't be split. schema: type: string default: NO_SPLIT enum: - NO_SPLIT - APP_TYPE - OWNED_CONTENT - SOURCE - PIN_FORMAT explode: false query_start_date: name: start_date in: query required: true description: 'Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today.' schema: type: string format: date query_start_date_async: name: start_date in: query required: false description: 'Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 2.5 years back from today.' schema: type: string format: date query_string_pin_ids: name: pin_ids in: query required: false description: List of Pin IDs. schema: type: array items: type: string maxItems: 100 minItems: 1 query_term: name: term in: query required: true description: Search term to look up pins. schema: type: string query_term_limit: name: limit in: query required: false description: Max suggested terms to return. schema: type: integer default: 4 maximum: 10 minimum: 1 query_timestamp: name: timestamp in: query required: false description: Timestamp. schema: type: string pattern: \d+ query_token_required: name: token in: query required: true description: Token returned from the post request creation call schema: type: string query_translate_interests_to_names: name: translate_interests_to_names in: query required: false description: Return interests as text names (if value is true) rather than topic IDs. schema: type: boolean default: false query_trending_keyword_limit: name: limit in: query required: false description: |- The maximum number of trending keywords that will be returned. Keywords are returned in trend-ranked order, so a `limit` of 50 will return the top 50 trends. schema: type: integer default: 50 maximum: 50 minimum: 1 query_user_following_feed_type: name: feed_type in: query required: false description: |- Thrift param specifying what type of followees will be kept. Default to include all followees. schema: $ref: '#/components/schemas/UserFollowingFeedType' query_vertical_product_category: name: verticals in: query required: false description: List of verticals to filter by schema: type: array items: $ref: '#/components/schemas/VerticalProductCategory' query_video_pin_metric_types: name: metric_types in: query required: false description: Metric types to get video data for, default is all. schema: type: array items: $ref: '#/components/schemas/QueryvideopinmetrictypesItems' explode: false query_video_pin_sort_by: name: sort_by in: query required: true description: Specify sorting order for video metrics schema: $ref: '#/components/schemas/TopVideoPinsSortBy' explode: false query_website: name: website in: query required: true description: Website with path or domain only schema: type: string RmnBillingContractKey: name: contract_id in: path required: true description: The contract ID schema: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' maxLength: 18 ScheduleParentKey: name: ad_account_id in: path required: true schema: type: string maxLength: 18 pattern: ^\d+$ SchedulesFilters.entity_ids: name: entity_ids in: query required: true description: List of Entity IDs, must be associated with the Ad Accound ID provided in the path. schema: type: array items: $ref: '#/components/schemas/EntityId' minItems: 1 SchedulesFilters.schedule_statuses: name: schedule_statuses in: query required: false description: Filter schedules by status (one or more) schema: type: array items: $ref: '#/components/schemas/ScheduleStatus' SchedulesFilters.schedule_type: name: schedule_type in: query required: false description: Filter schedules by a type schema: $ref: '#/components/schemas/ScheduleType' SubscriptionIdPathParam: name: subscription_id in: path required: true description: Unique identifier of a subscription. schema: type: string pattern: ^\d+$ TargetingTemplatesListParams.include_sizing: name: include_sizing in: query required: false description: Include audience sizing in result or not schema: type: boolean default: false TargetingTemplatesListParams.search_query: name: search_query in: query required: false description: Search query. Can contain pin description keywords or comma-separated pin IDs. schema: type: string TemplateBasedReportKey.id: name: ad_account_id in: path required: true schema: type: string maxLength: 18 pattern: ^\d+$ TemplateBasedReportKey.template_id: name: template_id in: path required: true description: Unique identifier of a template. schema: type: string maxLength: 18 terms_of_service_query_params.include_html: name: include_html in: query required: false description: Return HTML in TOS text. schema: type: boolean default: false terms_of_service_query_params.tos_type: name: tos_type in: query required: false description: Request type. schema: type: string schemas: Account: description: User account model containing properties related to a user's account. type: object properties: about: description: Profile about description. type: string account_type: description: Type of account allOf: - $ref: '#/components/schemas/UserAccountType' board_count: description: |2- User account board count. **Note**: Board count on user account level may differ from counts found elsewhere due to attribution of collaborative Boards. type: integer example: 14 nullable: true readOnly: true business_name: type: string nullable: true follower_count: description: User account follower count. type: integer example: 10 nullable: true readOnly: true following_count: description: User account following count. type: integer example: 347 nullable: true readOnly: true id: description: User account ID. type: string example: '2783136121146311751' pattern: ^\d+$ monthly_views: description: User account monthly views. type: integer example: 163 nullable: true readOnly: true pin_count: description: User account pin count. This includes both created and saved pins. type: integer example: 339 nullable: true readOnly: true profile_image: type: string username: type: string website_url: type: string AccountTemplate: type: object properties: ad_account_id: description: ID of the Ad Account that owns the template type: string readOnly: true ad_account_ids: description: IDs of the Ad Accounts that have access to this template type: array items: type: string ade_columns: description: A list of ADE columns type: array items: $ref: '#/components/schemas/AdeColumn' example: - ADE_COST_PER_ACTION-download_picture attribution_type: description: Attribution type for Brand/Category/SKU reports example: ADVERTISER_LEVEL click_window_days: description: The length of the sliding window over which click conversions will be attributed type: number columns: description: A list of columns to be included in the report type: array items: $ref: '#/components/schemas/ReportingColumn' conversion_report_time_type: description: Conversion report time type allOf: - $ref: '#/components/schemas/ConversionReportTimeType' creation_source: description: The surface used to create this template allOf: - $ref: '#/components/schemas/CreationSource' custom_column_ids: description: A list of custom column IDs type: array items: type: string nullable: true display_metadata: description: Additional metadata about this reporting template type: string engagement_window_days: description: The length of the sliding window over which engagement conversions will be attributed type: number filters_json: description: |- A JSON representation of any filters to be applied before returning report data. Each filter object should contain all of the following fields:\ "field": The column name\ "operator": The operator. Allowed operators: ["=", "!=", "in", "not_in", "~", ">", "<", "contains_substring"]\ "value": A single value or a list of values type: string nullable: true granularity: $ref: '#/components/schemas/Granularity' id: description: Template ID type: string readOnly: true ingestion_sources: description: The filter on the conversion ingestion source method for conversion metrics type: array items: $ref: '#/components/schemas/IngestionSource' nullable: true is_default: description: A boolean representing if this is the default view that loads for this template type type: boolean example: false is_deleted: description: A boolean that indicates if the template has been deleted type: boolean nullable: true is_owned_by_user: description: A boolean value that indicates if the user owns the template type: boolean is_scheduled: description: A boolean value that indicates if this template has been used to create a scheduled report type: boolean name: description: Template Name type: string nullable: true report_end_relative_days_in_past: description: The number of days prior to the day the report will be delivered at which the report will end type: number report_format: $ref: '#/components/schemas/DataOutputFormat' report_level: $ref: '#/components/schemas/MetricsReportingLevel' report_start_relative_days_in_past: description: The number of days prior to the day the report will be delivered at which the report will start type: number reporting_time_zone: description: Timezone for reporting data allOf: - $ref: '#/components/schemas/ReportingTimeZone' sort_by: description: Unified metric sort configuration type: description: Type of the template type: string updated_time: description: Time of last update in seconds since Unix epoch type: number readOnly: true user_id: description: ID of the user who created the template type: string view_window_days: description: The length of the sliding window over which view conversions will be attributed type: number required: - id ActionType: description: Ad group billable event type. For update, only draft ad groups may update billable event. type: string example: CLICKTHROUGH enum: - CLICKTHROUGH - IMPRESSION - VIDEO_V_50_MRC Ad: type: object properties: ad_account_id: description: The ID of the advertiser that this ad belongs to. type: string pattern: ^\d+$ readOnly: true ad_group_id: description: ID of the ad group that contains the ad. type: string pattern: ^(AG)?\d+$ android_deep_link: description: Deep link URL for Android devices. type: string nullable: true campaign_id: description: ID of the ad campaign that contains this ad. type: string pattern: ^\d+$ readOnly: true carousel_android_deep_links: description: Comma-separated deep links for the carousel pin on Android. type: array items: type: string nullable: true carousel_destination_urls: description: Comma-separated destination URLs for the carousel pin to promote. type: array items: type: string nullable: true carousel_ios_deep_links: description: Comma-separated deep links for the carousel pin on iOS. type: array items: type: string nullable: true carting_platform_type: description: The vendor platform type of the carting/WTB ad. allOf: - $ref: '#/components/schemas/CartingPlatformType' readOnly: true carting_products: description: Array of carting/WTB products for the ad. type: array items: $ref: '#/components/schemas/CartingProduct' readOnly: true click_tracking_url: description: Tracking url for the ad clicks. type: string nullable: true collection_items_destination_url_template: description: Destination URL template for all items within a collections drawer. type: string nullable: true collections_header_type: allOf: - $ref: '#/components/schemas/AdCollectionsHeaderType' nullable: true created_time: description: Pin creation time. Unix timestamp in seconds. type: integer readOnly: true creative_type: $ref: '#/components/schemas/CreativeType' customizable_cta_type: $ref: '#/components/schemas/CustomizableCTAType' destination_url: description: Destination URL. type: string nullable: true disclosure_type: $ref: '#/components/schemas/DisclosureType' disclosure_url: description: URL for a page that provides disclosures about a pharmaceutical product, such as potential side effects. Make sure the URL takes the user directly to the disclosure content and the referenced site is secure. type: string nullable: true grid_click_type: $ref: '#/components/schemas/GridClickType' id: description: The ID of this ad. type: string maxLength: 18 pattern: ^\d+$ ios_deep_link: description: Deep link URL for iOS devices. type: string nullable: true is_carting: description: Is the ad a carting/WTB ad? type: boolean is_collage_accepted_terms: description: Whether the advertiser has accepted the terms and conditions for collage ad. type: boolean is_collage_single_destination: description: Whether the collage ad has a single destination url override. type: boolean is_pin_deleted: description: Is original pin deleted? type: boolean is_removable: description: Is pin repinnable? type: boolean lead_form_id: description: Lead form ID for lead ad generation. type: string nullable: true pattern: ^(AG)?\d+$ name: description: Name of the ad - 255 chars max. type: string nullable: true pin_id: description: Pin ID. This field may only be updated for draft ads. type: string pattern: ^\d+$ quiz_pin_data: description: Before creating a quiz ad, you must create an organic Pin using POST/Create Pin for each result in the quiz. Quiz ads cannot be saved by a Pinner. Quiz ad results can be saved. type: object allOf: - $ref: '#/components/schemas/QuizPinData' nullable: true rejected_reasons: description: Enum reason why the pin was rejected. Returned if `review_status` is "REJECTED". type: array items: $ref: '#/components/schemas/AdDisapprovalReasons' readOnly: true rejection_labels: description: Text reason why the pin was rejected. Returned if `review_status` is "REJECTED". type: array items: type: string readOnly: true review_status: description: Ad review status allOf: - $ref: '#/components/schemas/AdReviewStatus' readOnly: true status: $ref: '#/components/schemas/EntityStatus' summary_status: description: Ad summary status allOf: - $ref: '#/components/schemas/PinPromotionSummaryStatus' readOnly: true tracking_urls: $ref: '#/components/schemas/TrackingUrls' type: description: Always "ad". type: string readOnly: true updated_time: description: Last update time. Unix timestamp in seconds. type: integer readOnly: true view_tracking_url: description: Tracking URL for ad impressions. type: string nullable: true required: - id - ad_group_id - pin_id - creative_type - ad_account_id - campaign_id - rejected_reasons - rejection_labels - review_status - type - summary_status AdAccount: type: object properties: country: $ref: '#/components/schemas/Country' created_time: description: ' Creation time. Unix timestamp in seconds.' type: integer nullable: true readOnly: true currency: $ref: '#/components/schemas/Currency' id: type: string maxLength: 18 pattern: ^\d+$ name: description: Ad account name. type: string maxLength: 256 owner: description: Ad account owner allOf: - $ref: '#/components/schemas/AdAccountOwner' readOnly: true permissions: type: array items: $ref: '#/components/schemas/BusinessAccessRole' readOnly: true title: permissions time_zone: description: The time zone of the ad account, in IANA format (e.g., "America/Los_Angeles"). Adding your local time zone lets you view your campaigns and ad reporting in your preferred time zone. Future reports will be available in both your local time zone and default UTC time zone. Historical data takes 1-2 months to backfill. Your billing and order lines will remain in UTC. type: string example: America/Los_Angeles updated_time: type: integer nullable: true readOnly: true title: updated_time required: - id AdAccountAnalyticsItems: type: object properties: AD_ACCOUNT_ID: type: string pattern: ^\d+$ DATE: type: string format: date required: - AD_ACCOUNT_ID AdAccountCreate: description: Resource create operation model. type: object properties: country: $ref: '#/components/schemas/Country' currency: $ref: '#/components/schemas/Currency' name: description: Ad account name. type: string maxLength: 256 owner_user_id: description: Advertiser's owning user ID. type: string pattern: ^\d+$ time_zone: description: The time zone of the ad account, in IANA format (e.g., "America/Los_Angeles"). Adding your local time zone lets you view your campaigns and ad reporting in your preferred time zone. Future reports will be available in both your local time zone and default UTC time zone. Historical data takes 1-2 months to backfill. Your billing and order lines will remain in UTC. type: string example: America/Los_Angeles AdAccountEntityType: description: Specify the entity type to get summary information type: string example: CAMPAIGN enum: - ADVERTISER - CAMPAIGN - AD_GROUP - AD AdAccountOwner: type: object properties: id: description: The owning account's user ID. type: string username: description: Public username for the user account type: string AdAccountToAdAccountSharedAudience: type: object properties: audience_id: description: Unique identifier of an audience example: '2542621871096' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' permissions: description: Permissions granted to the recipients. type: array items: $ref: '#/components/schemas/Role' example: - RESOURCE_PINNER_LIST_READER - RESOURCE_PINNER_LIST_OWNER readOnly: true recipient_account_ids: description: Ad account IDs to share with or revoke from (request) / that received the audience (response). type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' required: - audience_id - recipient_account_ids title: AdAccountToAdAccountSharedAudience AdAccountToAdAccountSharedAudienceUpdateWithRequiredBody: description: Resource create or update operation model with required body fields (no OptionalProperties). type: object properties: audience_id: description: Unique identifier of an audience example: '2542621871096' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' operation_type: $ref: '#/components/schemas/OperationType' recipient_account_ids: description: Ad account IDs to share with or revoke from (request) / that received the audience (response). type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' required: - audience_id - operation_type - recipient_account_ids AdAccountToBusinessSharedAudience: type: object properties: audience_id: description: Unique identifier of an audience example: '2542621871096' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' permissions: description: Permissions granted to the recipients. type: array items: $ref: '#/components/schemas/Role' example: - RESOURCE_PINNER_LIST_READER - RESOURCE_PINNER_LIST_OWNER readOnly: true recipient_business_ids: description: Business IDs to share with or revoke from (request) / that received the audience (response). type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' required: - audience_id - recipient_business_ids title: AdAccountToBusinessSharedAudience AdAccountToBusinessSharedAudienceUpdateWithRequiredBody: description: Resource create or update operation model with required body fields (no OptionalProperties). type: object properties: audience_id: description: Unique identifier of an audience example: '2542621871096' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' operation_type: $ref: '#/components/schemas/OperationType' recipient_business_ids: description: Business IDs to share with or revoke from (request) / that received the audience (response). type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' required: - audience_id - operation_type - recipient_business_ids AdAccountsAudience: type: object properties: ad_account_id: description: Ad account ID. type: string pattern: ^\d+$ audience_type: description: '[Audience types](/docs/reference/glossary/#Audience Types): ACTALIKE, ENGAGEMENT, CUSTOMER_LIST and VISITOR' allOf: - $ref: '#/components/schemas/AudienceType' created_by_company_name: description: The company that created this audience. type: string nullable: true readOnly: true created_timestamp: description: Creation time. Unix timestamp in seconds. type: integer nullable: true readOnly: true description: description: Audience description. type: string nullable: true id: description: Audience ID. type: string pattern: ^\d+$ is_nca: description: Whether the audience derives from a new customer acquisition (expanded matching) customer list. Read-only. type: boolean readOnly: true name: description: Audience name. type: string rule: $ref: '#/components/schemas/AdAccountsAudienceRule' size: description: Audience size. type: integer nullable: true readOnly: true status: description: Audience status. READY, INITIALIZING, TOO_SMALL - Each audience list needs to have at least 100 people with Pinterest accounts before you can start using it. allOf: - $ref: '#/components/schemas/AudienceStatus' readOnly: true type: description: Always "audience". type: string readOnly: true updated_timestamp: description: Last update time. Unix timestamp in seconds. type: integer nullable: true readOnly: true required: - id AdAccountsAudienceCreate: description: Resource create operation model. type: object properties: ad_account_id: description: Ad account ID. type: string pattern: ^\d+$ audience_type: description: '[Audience types](/docs/reference/glossary/#Audience Types): ACTALIKE, ENGAGEMENT, CUSTOMER_LIST and VISITOR' allOf: - $ref: '#/components/schemas/AudienceType' description: description: Audience description. type: string nullable: true name: description: Audience name. type: string rule: $ref: '#/components/schemas/AdAccountsAudienceRule' AdAccountsAudienceRule: description: |- JSON object defining targeted audience users. Example rule formats per audience type: CUSTOMER_LIST: { "customer_list_id": ""} ACTALIKE: { "seed_id": [""], "country": "US", "percentage": "10" } (Valid countries include: "US", "CA", and "GB". Percentage should be 1-10. The targeted audience should be this % size across Pinterest.) VISITOR: { "visitor_source_id": [""], "retention_days": "180", "event_source": {"=": ["web", "mobile"]}, "ingestion_source": {"=": ["tag"]}} (Retention days should be 1-540. Retention applies to specific customers.) ENGAGEMENT: {"engagement_domain": ["www.example.com"], "engager_type": 1} Learn more about [engagement audiences](/docs/work-with-targets-and-audiences/create-audiences/#engagement-audience). type: object properties: ad_account_id: description: Ad account ID. type: string pattern: ^\d+$ ad_id: description: Ad ID for engagement audience filter. type: array items: type: string campaign_id: description: Campaign ID for engagement audience filter. type: array items: type: string country: description: 'Valid countries include: "US", "CA", and "GB".' type: string customer_list_id: description: Customer list ID. For CUSTOMER_LIST `audience_type`. type: string pattern: ^\d+$ engagement_domain: description: The audience account's verified domain. **Required** for ENGAGEMENT `audience_type`. type: array items: type: string engagement_type: description: Engagement type enum. Optional for ENGAGEMENT `audience_type`. Supported values are `click`, `save`, `closeup`, `comment` and `like`. All engagements are included if this field is not set. type: string engager_type: description: Optional for ENGAGEMENT. Engager type value should be 1-2. type: integer event: description: A Pinterest tag event. Optional for VISITOR `audience_type`. Possible values are `pagevisit`, `signup`, `checkout`, `viewcategory`, `search`, `addtocart`, `watchvideo`, `lead`, and `custom`. This field also accepts a partner-defined Pinterest tag event. type: string event_data: $ref: '#/components/schemas/EventData' event_source: description: "Optional for VISITOR. You can use it as a {'=': [value]}. Supported values are: web, mobile, offline" type: object ingestion_source: description: "Optional for VISITOR. You can use it as a {'=': [value]}. Supported values are: tag, mmp, file_upload, conversions_api" type: object objective_type: description: Objective for engagement audience filter. type: array items: $ref: '#/components/schemas/AudienceObjectiveType' percentage: description: Percentage should be 1-10. The targeted audience should be this % size across Pinterest. anyOf: - type: string - type: integer pin_id: description: 'IDs of engaged organic pins. Optional for ENGAGEMENT `audience_type`. For example, "pin_id:": ["34567"]' type: array items: type: string prefill: description: Optional for VISITOR `audience_type`. If `true`, the specified rule on existing engagement data is applied to pre-populate the audience. If `false`, the audience is empty at creation time. The default is `true`. type: boolean retention_days: description: Number of days a Pinterest user remains in the audience. Optional for ENGAGEMENT and VISITOR `audience_type`. Accepted range is 1-540. Defaults to 180 if not specified. type: integer seed_id: description: Audience ID(s). For ACTALIKE `audience_type`. anyOf: - type: array items: type: integer - type: array items: type: string url: description: |- Optional for ENGAGEMENT or VISITOR `audience_type`. For ENGAGEMENT, it is the engaged pin's URL. For VISITOR, you can use it as a string or a {operator: value} object for filtering visitors based on conversion tag event URLs. Supported operators are [ =, !=, contains, not_contains]. Example 1: "url": "http://www.myonlinestore123.com/view_item/shoe" Example 2: "url": {"contains": "/view_item/shoe"} type: array items: type: string visitor_source_id: description: The conversion tag ID, or the Pinterest tag ID, that you use on your website. For VISITOR `audience_type`. anyOf: - type: string - type: array items: type: string AdAccountsAudienceUpdate: description: Resource create or update operation model. type: object properties: ad_account_id: description: Ad account ID. type: string pattern: ^\d+$ audience_type: description: '[Audience types](/docs/reference/glossary/#Audience Types): ACTALIKE, ENGAGEMENT, CUSTOMER_LIST and VISITOR' allOf: - $ref: '#/components/schemas/AudienceType' description: description: Audience description. type: string nullable: true name: description: Audience name. type: string operation_type: description: Audience operation type (update or remove). Only valid in update request body. allOf: - $ref: '#/components/schemas/AudienceUpdateOperationType' rule: $ref: '#/components/schemas/AdAccountsAudienceRule' AdAccountsCountry: type: object properties: code: example: US allOf: - $ref: '#/components/schemas/Country' currency: description: Country currency. type: string example: Dollars index: description: Country index type: number example: 1 name: description: Country name type: string example: United States of America required: - code - currency - index - name AdAdsAnalyticsAsyncTargetingTypes: description: Reporting targeting type type: string enum: - KEYWORD - APPTYPE - GENDER - LOCATION - PLACEMENT - COUNTRY - TARGETED_INTEREST - PINNER_INTEREST - AUDIENCE_INCLUDE - GEO - AGE_BUCKET - REGION - MEDIA_TYPE - AGE_BUCKET_AND_GENDER - AUDIENCE_MULTIPLIER - CREATIVE_ENHANCEMENTS - LOCAL_ADS_STORE_CODE AdBatchCreateRequest: type: array items: $ref: '#/components/schemas/AdCreate' maxItems: 30 minItems: 1 AdBatchItem: type: object properties: data: $ref: '#/components/schemas/Ad' exceptions: $ref: '#/components/schemas/Pinterest.Lib.Error' AdBatchUpdate: type: object properties: ad_group_id: description: ID of the ad group that contains the ad. type: string pattern: ^(AG)?\d+$ android_deep_link: description: Deep link URL for Android devices. type: string nullable: true carousel_android_deep_links: description: Comma-separated deep links for the carousel pin on Android. type: array items: type: string nullable: true carousel_destination_urls: description: Comma-separated destination URLs for the carousel pin to promote. type: array items: type: string nullable: true carousel_ios_deep_links: description: Comma-separated deep links for the carousel pin on iOS. type: array items: type: string nullable: true click_tracking_url: description: Tracking url for the ad clicks. type: string nullable: true collection_items_destination_url_template: description: Destination URL template for all items within a collections drawer. type: string nullable: true collections_header_type: allOf: - $ref: '#/components/schemas/AdCollectionsHeaderType' nullable: true creative_type: $ref: '#/components/schemas/CreativeType' customizable_cta_type: $ref: '#/components/schemas/CustomizableCTAType' destination_url: description: Destination URL. type: string nullable: true disclosure_type: $ref: '#/components/schemas/DisclosureType' disclosure_url: description: URL for a page that provides disclosures about a pharmaceutical product, such as potential side effects. Make sure the URL takes the user directly to the disclosure content and the referenced site is secure. type: string nullable: true grid_click_type: $ref: '#/components/schemas/GridClickType' id: description: The ID of this ad. type: string maxLength: 18 pattern: ^\d+$ ios_deep_link: description: Deep link URL for iOS devices. type: string nullable: true is_carting: description: Is the ad a carting/WTB ad? type: boolean is_collage_accepted_terms: description: Whether the advertiser has accepted the terms and conditions for collage ad. type: boolean is_collage_single_destination: description: Whether the collage ad has a single destination url override. type: boolean is_pin_deleted: description: Is original pin deleted? type: boolean is_removable: description: Is pin repinnable? type: boolean lead_form_id: description: Lead form ID for lead ad generation. type: string nullable: true pattern: ^(AG)?\d+$ name: description: Name of the ad - 255 chars max. type: string nullable: true pin_id: description: Pin ID. This field may only be updated for draft ads. type: string pattern: ^\d+$ quiz_pin_data: description: Before creating a quiz ad, you must create an organic Pin using POST/Create Pin for each result in the quiz. Quiz ads cannot be saved by a Pinner. Quiz ad results can be saved. type: object allOf: - $ref: '#/components/schemas/QuizPinData' nullable: true status: $ref: '#/components/schemas/EntityStatus' tracking_urls: $ref: '#/components/schemas/TrackingUrls' view_tracking_url: description: Tracking URL for ad impressions. type: string nullable: true required: - id AdBatchUpdateRequest: type: array items: $ref: '#/components/schemas/AdBatchUpdate' maxItems: 30 minItems: 1 AdBatchWriteResponseModel: type: object properties: items: type: array items: $ref: '#/components/schemas/AdBatchItem' required: - items AdCollectionsHeaderType: description: Collections ad header type for ads type: string example: SHOP_THIS_COLLECTION enum: - SHOP_THIS_COLLECTION - EXPLORE_THIS_COLLECTION - NO_HEADER - null nullable: true AdCreate: description: Resource create operation model. type: object properties: ad_group_id: description: ID of the ad group that contains the ad. type: string pattern: ^(AG)?\d+$ android_deep_link: description: Deep link URL for Android devices. type: string nullable: true carousel_android_deep_links: description: Comma-separated deep links for the carousel pin on Android. type: array items: type: string nullable: true carousel_destination_urls: description: Comma-separated destination URLs for the carousel pin to promote. type: array items: type: string nullable: true carousel_ios_deep_links: description: Comma-separated deep links for the carousel pin on iOS. type: array items: type: string nullable: true click_tracking_url: description: Tracking url for the ad clicks. type: string nullable: true collection_items_destination_url_template: description: Destination URL template for all items within a collections drawer. type: string nullable: true collections_header_type: allOf: - $ref: '#/components/schemas/AdCollectionsHeaderType' nullable: true creative_type: $ref: '#/components/schemas/CreativeType' customizable_cta_type: $ref: '#/components/schemas/CustomizableCTAType' destination_url: description: Destination URL. type: string nullable: true disclosure_type: $ref: '#/components/schemas/DisclosureType' disclosure_url: description: URL for a page that provides disclosures about a pharmaceutical product, such as potential side effects. Make sure the URL takes the user directly to the disclosure content and the referenced site is secure. type: string nullable: true grid_click_type: $ref: '#/components/schemas/GridClickType' ios_deep_link: description: Deep link URL for iOS devices. type: string nullable: true is_carting: description: Is the ad a carting/WTB ad? type: boolean is_collage_accepted_terms: description: Whether the advertiser has accepted the terms and conditions for collage ad. type: boolean is_collage_single_destination: description: Whether the collage ad has a single destination url override. type: boolean is_pin_deleted: description: Is original pin deleted? type: boolean is_removable: description: Is pin repinnable? type: boolean lead_form_id: description: Lead form ID for lead ad generation. type: string nullable: true pattern: ^(AG)?\d+$ name: description: Name of the ad - 255 chars max. type: string nullable: true pin_id: description: Pin ID. This field may only be updated for draft ads. type: string pattern: ^\d+$ quiz_pin_data: description: Before creating a quiz ad, you must create an organic Pin using POST/Create Pin for each result in the quiz. Quiz ads cannot be saved by a Pinner. Quiz ad results can be saved. type: object allOf: - $ref: '#/components/schemas/QuizPinData' nullable: true status: $ref: '#/components/schemas/EntityStatus' tracking_urls: $ref: '#/components/schemas/TrackingUrls' view_tracking_url: description: Tracking URL for ad impressions. type: string nullable: true required: - ad_group_id - pin_id - creative_type AdCreateRequest: type: object properties: ad_group_id: description: ID of the ad group that contains the ad. type: string pattern: ^(AG)?\d+$ android_deep_link: description: Deep link URL for Android devices. type: string nullable: true carousel_android_deep_links: description: Comma-separated deep links for the carousel pin on Android. type: array items: type: string nullable: true carousel_destination_urls: description: Comma-separated destination URLs for the carousel pin to promote. type: array items: type: string nullable: true carousel_ios_deep_links: description: Comma-separated deep links for the carousel pin on iOS. type: array items: type: string nullable: true click_tracking_url: description: Tracking url for the ad clicks. type: string nullable: true creative_type: $ref: '#/components/schemas/CreativeType' customizable_cta_type: $ref: '#/components/schemas/CustomizableCTAType' destination_url: description: Destination URL. type: string nullable: true disclosure_type: $ref: '#/components/schemas/DisclosureType' disclosure_url: description: URL for a page that provides disclosures about a pharmaceutical product, such as potential side effects. Make sure the URL takes the user directly to the disclosure content and the referenced site is secure. type: string nullable: true grid_click_type: $ref: '#/components/schemas/GridClickType' ios_deep_link: description: Deep link URL for iOS devices. type: string nullable: true is_carting: description: Is the ad a carting/WTB ad? type: boolean is_pin_deleted: description: Is original pin deleted? type: boolean example: false is_removable: description: Is pin repinnable? type: boolean example: false lead_form_id: description: Lead form ID for lead ad generation. type: string nullable: true pattern: ^(AG)?\d+$ name: description: Name of the ad - 255 chars max. type: string nullable: true pin_id: description: Pin ID. type: string example: '394205773611545468' pattern: ^\d+$ quiz_pin_data: description: Before creating a quiz ad, you must create an organic Pin using POST/Create Pin for each result in the quiz. Quiz ads cannot be saved by a Pinner. Quiz ad results can be saved. type: object allOf: - $ref: '#/components/schemas/QuizPinData' nullable: true status: $ref: '#/components/schemas/EntityStatus' tracking_urls: type: object allOf: - $ref: '#/components/schemas/TrackingUrls' nullable: true view_tracking_url: description: Tracking URL for ad impressions. type: string nullable: true allOf: - type: object title: Request schema for creating ads required: - ad_group_id - creative_type - pin_id title: AdCreateRequest AdCreateRequestAllOf2: type: object title: Request schema for creating ads AdDisapprovalReasons: description: ad disapproval reasons type: string enum: - HASHTAGS - PROMOTIONS_AND_PRICES - TARGETING - LANDING_PAGE - CAPS_AND_SYMBOLS - SHOCKING - WEIGHT_LOSS - PROHIBITED_PRODUCT - AUTHENTICITY - NUDITY - CONFUSING_DESIGN - URGENCY - RATINGS - APP - ALCOHOL - CONTESTS - POLITICAL - OTHER - IMAGE - NAR - INCONSISTENT - CLICKBAIT - NO_DESCRIPTION - LOW_QUALITY - EXAGGERATED_CLAIMS - PINTEREST_BRAND - ALCOHOL_NO_SALE - LANDING_PAGE_SPEED - LANDING_PAGE_HARDWALL - LANDING_PAGE_BROKEN - LANDING_PAGE_QUALITY - OUT_OF_STOCK - IMAGE_LOW_QUALITY - IMAGE_BUSY - IMAGE_POORLY_EDITED - IMAGE_BEFORE_AFTER - UGC - FAKE_BUTTONS - WEAPONS - SENSITIVE - UNACCEPTABLE_BUSINESS - SUSPICIOUS_CLAIMS - PHARMA - SUSPICIOUS_SUPPLEMENTS - ILLEGAL_RECREATIONAL_DRUG - LOW_QUALITY_LANDING_PAGE - RESTRICTED_HEALTHCARE - INCONSISTENT_LANG_FR AdGroup: type: object properties: auto_targeting_enabled: description: Enable auto-targeting for ad group. Default value is True. Also known as ["Performance+ targeting"](https://help.pinterest.com/en/business/article/performance-plus-targeting). type: boolean nullable: true bid_multiplier: description: '[Open beta](https://help.pinterest.com/en/business/article/beta-features) Bid multiplier for ad group. This value is a double between 0.1 and 10.0. Enter 0 to remove the bid multiplier. - Not currently supported for [Performance+ campaigns](https://help.pinterest.com/en/business/article/performance-plus-campaigns).' type: number maximum: 10 minimum: 0 nullable: true budget_type: $ref: '#/components/schemas/BudgetType' pacing_delivery_type: $ref: '#/components/schemas/PacingDeliveryType' allOf: - $ref: '#/components/schemas/AdGroupBase' AdGroupAudienceSizing: type: object properties: audience_size_lower_bound: description: The lower confidence bound of the estimated potential audience size. "Potential audience size" estimates the number of people you may be able to reach per month with your campaign. It is based on historical advertising data and the targeting criteria you select. It does not guarantee results or take into account factors such as bid, budget, schedule, seasonality or product experiments. type: number readOnly: true audience_size_upper_bound: description: The upper confidence bound of the estimated potential audience size. "Potential audience size" estimates the number of people you may be able to reach per month with your campaign. It is based on historical advertising data and the targeting criteria you select. It does not guarantee results or take into account factors such as bid, budget, schedule, seasonality or product experiments. type: number readOnly: true AdGroupAudienceSizingCreate: description: Resource create operation model. type: object properties: auto_targeting_enabled: description: Enable auto-targeting for ad group. Default value is True. Also known as [Pinterest Performance+ targeting](https://help.pinterest.com/en/business/article/performance-plus-targeting). type: boolean default: true creative_types: description: Pin creative types filter. **Note:** SHOP_THE_PIN has been deprecated. Please use COLLECTION instead. type: array items: $ref: '#/components/schemas/AdGroupAudienceSizingCreativeTypes' nullable: true keywords: description: Array of keyword objects. If the keywords field is missing, all keywords will be targeted. type: array items: $ref: '#/components/schemas/AdGroupAudienceSizingKeyword' nullable: true placement_group: description: '[Placement group](/docs/redoc/#section/Placement-group).' default: ALL allOf: - $ref: '#/components/schemas/AdgroupPlacementGroupType' product_group_ids: description: Targeted product group IDs. **Note:** This can only be combined with shopping/catalog sales campaigns. For more information, [click here](https://help.pinterest.com/en/business/article/shopping-ads#section-14571). SHOPPING_RETARGETING must be included in targeting_spec object or this field will be ignored. type: array items: $ref: '#/components/schemas/AdGroupAudienceSizingProductGroupId' nullable: true targeting_spec: $ref: '#/components/schemas/TargetingSpecOptimal' AdGroupAudienceSizingCreativeTypes: type: string enum: - REGULAR - VIDEO - SHOPPING - CAROUSEL - MAX_VIDEO - SHOP_THE_PIN - COLLECTION - IDEA AdGroupAudienceSizingKeyword: type: object properties: match_type: $ref: '#/components/schemas/MatchType' value: description: Keyword value (120 chars max). type: string required: - match_type - value AdGroupAudienceSizingProductGroupId: type: string pattern: ^\d+$ AdGroupBase: type: object properties: ad_account_id: description: Advertiser ID. type: string pattern: ^\d+$ readOnly: true bid_in_micro_currency: description: 'Bid price in micro currency. This field is **REQUIRED** for the following campaign objective_type/billable_event combinations: AWARENESS/IMPRESSION, CONSIDERATION/CLICKTHROUGH, CATALOG_SALES/CLICKTHROUGH, VIDEO_VIEW/VIDEO_V_50_MRC.' type: integer nullable: true bid_strategy_type: $ref: '#/components/schemas/BidStrategyType' billable_event: $ref: '#/components/schemas/ActionType' budget_in_micro_currency: description: Budget in micro currency. This field is **REQUIRED** for non-CBO (campaign budget optimization) campaigns. A CBO campaign automatically generates ad group budgets from its campaign budget to maximize campaign outcome. A CBO campaign is limited to 70 or less ad groups. type: integer nullable: true campaign_id: description: Campaign ID of the ad group. type: string pattern: ^[C]?\d+$ conversion_learning_mode_type: description: oCPM learn mode allOf: - $ref: '#/components/schemas/ConversionLearningModeType' readOnly: true created_time: description: Ad group creation time. Unix timestamp in seconds. type: integer readOnly: true customer_segment_id: description: Customer segment ID applied to the ad group. We currently only support 1 customer segment per ad group. To use customer segments, do not set the `targeting_template_ids` field as well as the `AUDIENCE_INCLUDE` field of the `targeting_spec`. To clear the customer segment ID, set this field to '0'. allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' dca_assets: description: '[DCA] The Dynamic creative assets to use for DCA. Dynamic Creative Assembly (DCA) accepts basic creative assets of an ad (image, video, title, call to action, logo etc). Then it automatically generates optimized ad combinations based on these assets.' readOnly: true end_time: description: |- Timestamp in Unix format for scheduling when ads in the ad group stop appearing. If not specified, ads run indefinitely unless you update the ad group by changing their status to `paused`. Cannot occur after `end_time` for parent campaign (if specified). Learn about [scheduling ads](https://help.pinterest.com/en/business/article/ads-manager-schedule-ads). For certain organizations ([Closed beta](https://help.pinterest.com/en/business/article/beta-features)): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO. type: integer nullable: true ext_features: $ref: '#/components/schemas/AdgroupTrackingFeatures' feed_profile_id: description: Feed Profile ID associated to the adgroup. type: string id: description: Ad group ID. type: string maxLength: 18 pattern: ^\d+$ is_creative_optimization: description: Enable creative optimization for the ad group, default value is FALSE. When enabled, you allow Pinterest to automatically turn your product Pins into ads in different formats (collections and shopping) and deliver those ads to users at scale. type: boolean nullable: true is_local_inventory: description: Indicates whether the ad group should use the local inventory. type: boolean lifetime_frequency_cap: description: Set a limit to the number of times a promoted pin from this campaign can be impressed by a pinner within the past rolling 30 days. Only available for CPM (cost per mille (1000 impressions)) ad groups. A CPM ad group has an IMPRESSION [billable_event](https://help.pinterest.com/en/business/article/billable-events) value. This field **REQUIRES** the `end_time` field. type: integer local_inventory_radius_in_miles: description: The targeting radius of the local inventory ads in miles. type: number name: description: Ad group name. type: string optimization_goal_metadata: description: Optimization goals for objective-based performance campaigns. **REQUIRED** when campaign's `objective_type` is set to `"WEB_CONVERSION"`. type: object allOf: - $ref: '#/components/schemas/NullableOptimizationGoalMetadata' nullable: true performance_plus_campaign_settings: description: Pinterest Performance+ campaign settings. type: object allOf: - $ref: '#/components/schemas/PerformancePlusCampaignSettings' nullable: true placement_group: description: '[Placement group](https://help.pinterest.com/en/business/article/placement-groups).' allOf: - $ref: '#/components/schemas/PlacementGroupType' placement_traffic_type: description: A targeting option that enables advertisers to choose whether to run ads in fullscreen feed, two column feed, or both allOf: - $ref: '#/components/schemas/PlacementTrafficType' nullable: true promotion_application_level: description: Specify if the promotion is applied at ad group or item level example: ITEM allOf: - $ref: '#/components/schemas/PromotionApplicationLevel' nullable: true promotion_id: description: Promotion ID. To clear this field, set to null. type: string default: '0' nullable: true pattern: ^\d+$ promotion_ids: description: Promotion IDs list. To clear this field, set to an empty array []. type: array items: type: string start_time: description: "Timestamp in Unix format for scheduling when ads in the ad group start to appear. If not specified, ads appear during parent campaign's `start_time`. Cannot precede `start_time` for parent campaign (if specified). Learn about [scheduling ads](/docs/api-features/managing-ads/#step-2-create-an-ad-group). For certain organizations ([Closed beta](/docs/getting-started/using-beta-and-restricted-features/)): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO." type: integer nullable: true status: description: Ad group/entity status. allOf: - $ref: '#/components/schemas/EntityStatus' summary_status: allOf: - $ref: '#/components/schemas/SummaryStatus' readOnly: true targeting_spec: $ref: '#/components/schemas/TargetingSpecOptimal' targeting_template_ids: description: "Targeting template IDs applied to the ad group. We currently only support 1 targeting template per ad group. To use targeting templates, do not set any other targeting fields: targeting_spec, tracking_urls, auto_targeting_enabled, placement_group. To clear all targeting template IDs, set this field to ['0']." type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' maxItems: 1 nullable: true tracking_urls: $ref: '#/components/schemas/AdGroupTrackingURLs' type: description: Always "adgroup". type: string default: adgroup readOnly: true updated_time: description: Ad group last update time. Unix timestamp in seconds. type: integer readOnly: true required: - id - name - campaign_id - billable_event - created_time - updated_time - type - conversion_learning_mode_type - summary_status AdGroupBatchCreateRequest: type: array items: $ref: '#/components/schemas/AdGroupCreateCreate' maxItems: 30 minItems: 1 AdGroupBatchUpdateRequest: type: array items: $ref: '#/components/schemas/AdGroupUpdateBatchUpdate' maxItems: 30 minItems: 1 AdGroupCommonTargetingTemplateIdsItems: description: Targeting template ID. type: string pattern: ^\d+$ AdGroupCreate: type: object properties: auto_targeting_enabled: description: Enable auto-targeting for ad group. Default value is True. Also known as ["Performance+ targeting"](https://help.pinterest.com/en/business/article/performance-plus-targeting). type: boolean bid_multiplier: description: '[Open beta](https://help.pinterest.com/en/business/article/beta-features) Bid multiplier for ad group. This value is a double between 0.1 and 10.0. Enter 0 to remove the bid multiplier. - Not currently supported for [Performance+ campaigns](https://help.pinterest.com/en/business/article/performance-plus-campaigns).' type: number maximum: 10 minimum: 0 budget_type: default: DAILY allOf: - $ref: '#/components/schemas/BudgetType' pacing_delivery_type: default: STANDARD allOf: - $ref: '#/components/schemas/PacingDeliveryType' allOf: - $ref: '#/components/schemas/AdGroupBase' AdGroupCreateCreate: description: Resource create operation model. type: object properties: auto_targeting_enabled: description: Enable auto-targeting for ad group. Default value is True. Also known as ["Performance+ targeting"](https://help.pinterest.com/en/business/article/performance-plus-targeting). type: boolean bid_in_micro_currency: description: 'Bid price in micro currency. This field is **REQUIRED** for the following campaign objective_type/billable_event combinations: AWARENESS/IMPRESSION, CONSIDERATION/CLICKTHROUGH, CATALOG_SALES/CLICKTHROUGH, VIDEO_VIEW/VIDEO_V_50_MRC.' type: integer nullable: true bid_multiplier: description: '[Open beta](https://help.pinterest.com/en/business/article/beta-features) Bid multiplier for ad group. This value is a double between 0.1 and 10.0. Enter 0 to remove the bid multiplier. - Not currently supported for [Performance+ campaigns](https://help.pinterest.com/en/business/article/performance-plus-campaigns).' type: number maximum: 10 minimum: 0 bid_strategy_type: $ref: '#/components/schemas/BidStrategyType' billable_event: $ref: '#/components/schemas/ActionType' budget_in_micro_currency: description: Budget in micro currency. This field is **REQUIRED** for non-CBO (campaign budget optimization) campaigns. A CBO campaign automatically generates ad group budgets from its campaign budget to maximize campaign outcome. A CBO campaign is limited to 70 or less ad groups. type: integer nullable: true budget_type: default: DAILY allOf: - $ref: '#/components/schemas/BudgetType' campaign_id: description: Campaign ID of the ad group. type: string pattern: ^[C]?\d+$ customer_segment_id: description: Customer segment ID applied to the ad group. We currently only support 1 customer segment per ad group. To use customer segments, do not set the `targeting_template_ids` field as well as the `AUDIENCE_INCLUDE` field of the `targeting_spec`. To clear the customer segment ID, set this field to '0'. allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' end_time: description: |- Timestamp in Unix format for scheduling when ads in the ad group stop appearing. If not specified, ads run indefinitely unless you update the ad group by changing their status to `paused`. Cannot occur after `end_time` for parent campaign (if specified). Learn about [scheduling ads](https://help.pinterest.com/en/business/article/ads-manager-schedule-ads). For certain organizations ([Closed beta](https://help.pinterest.com/en/business/article/beta-features)): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO. type: integer nullable: true ext_features: $ref: '#/components/schemas/AdgroupTrackingFeatures' feed_profile_id: description: Feed Profile ID associated to the adgroup. type: string is_creative_optimization: description: Enable creative optimization for the ad group, default value is FALSE. When enabled, you allow Pinterest to automatically turn your product Pins into ads in different formats (collections and shopping) and deliver those ads to users at scale. type: boolean nullable: true is_local_inventory: description: Indicates whether the ad group should use the local inventory. type: boolean lifetime_frequency_cap: description: Set a limit to the number of times a promoted pin from this campaign can be impressed by a pinner within the past rolling 30 days. Only available for CPM (cost per mille (1000 impressions)) ad groups. A CPM ad group has an IMPRESSION [billable_event](https://help.pinterest.com/en/business/article/billable-events) value. This field **REQUIRES** the `end_time` field. type: integer local_inventory_radius_in_miles: description: The targeting radius of the local inventory ads in miles. type: number name: description: Ad group name. type: string optimization_goal_metadata: description: Optimization goals for objective-based performance campaigns. **REQUIRED** when campaign's `objective_type` is set to `"WEB_CONVERSION"`. type: object allOf: - $ref: '#/components/schemas/NullableOptimizationGoalMetadata' nullable: true pacing_delivery_type: default: STANDARD allOf: - $ref: '#/components/schemas/PacingDeliveryType' performance_plus_campaign_settings: description: Pinterest Performance+ campaign settings. type: object allOf: - $ref: '#/components/schemas/PerformancePlusCampaignSettings' nullable: true placement_group: description: '[Placement group](https://help.pinterest.com/en/business/article/placement-groups).' allOf: - $ref: '#/components/schemas/PlacementGroupType' placement_traffic_type: description: A targeting option that enables advertisers to choose whether to run ads in fullscreen feed, two column feed, or both allOf: - $ref: '#/components/schemas/PlacementTrafficType' nullable: true promotion_application_level: description: Specify if the promotion is applied at ad group or item level example: ITEM allOf: - $ref: '#/components/schemas/PromotionApplicationLevel' nullable: true promotion_id: description: Promotion ID. To clear this field, set to null. type: string default: '0' nullable: true pattern: ^\d+$ promotion_ids: description: Promotion IDs list. To clear this field, set to an empty array []. type: array items: type: string start_time: description: "Timestamp in Unix format for scheduling when ads in the ad group start to appear. If not specified, ads appear during parent campaign's `start_time`. Cannot precede `start_time` for parent campaign (if specified). Learn about [scheduling ads](/docs/api-features/managing-ads/#step-2-create-an-ad-group). For certain organizations ([Closed beta](/docs/getting-started/using-beta-and-restricted-features/)): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO." type: integer nullable: true status: description: Ad group/entity status. allOf: - $ref: '#/components/schemas/EntityStatus' targeting_spec: $ref: '#/components/schemas/TargetingSpecOptimal' targeting_template_ids: description: "Targeting template IDs applied to the ad group. We currently only support 1 targeting template per ad group. To use targeting templates, do not set any other targeting fields: targeting_spec, tracking_urls, auto_targeting_enabled, placement_group. To clear all targeting template IDs, set this field to ['0']." type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' maxItems: 1 nullable: true tracking_urls: $ref: '#/components/schemas/AdGroupTrackingURLs' required: - name - campaign_id - billable_event AdGroupCreateRequest: type: object properties: bid_in_micro_currency: description: 'Bid price in micro currency. This field is **REQUIRED** for the following campaign objective_type/billable_event combinations: AWARENESS/IMPRESSION, CONSIDERATION/CLICKTHROUGH, CATALOG_SALES/CLICKTHROUGH.' type: integer example: 5000000 nullable: true bid_strategy_type: $ref: '#/components/schemas/BidStrategyType' billable_event: $ref: '#/components/schemas/ActionType' budget_in_micro_currency: description: Budget in micro currency. This field is **REQUIRED** for non-CBO (campaign budget optimization) campaigns. A CBO campaign automatically generates ad group budgets from its campaign budget to maximize campaign outcome. A CBO campaign is limited to 70 or less ad groups. type: integer example: 5000000 nullable: true budget_type: $ref: '#/components/schemas/BudgetType' campaign_id: description: Campaign ID of the ad group. type: string example: '626736533506' pattern: ^[C]?\d+$ end_time: description: |- Timestamp in Unix format for scheduling when ads in the ad group stop appearing. If not specified, ads run indefinitely unless you update the ad group by changing their status to `paused`. Cannot occur after `end_time` for parent campaign (if specified). Learn about scheduling ads. For certain organizations (Closed beta): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO. type: integer example: 5705424000 nullable: true is_creative_optimization: description: Enable creative optimization for the ad group, default value is FALSE. When enabled, you allow Pinterest to automatically turn your product Pins into ads in different formats (collections and shopping) and deliver those ads to users at scale. type: boolean example: true nullable: true lifetime_frequency_cap: description: Set a limit to the number of times a promoted pin from this campaign can be impressed by a pinner within the past rolling 30 days. Only available for CPM (cost per mille (1000 impressions)) ad groups. A CPM ad group has an IMPRESSION billable_event value. This field **REQUIRES** the `end_time` field. type: integer example: 100 name: description: Ad group name. type: string example: 'Ad Group For Pin: 687195905986' optimization_goal_metadata: description: Optimization goals for objective-based performance campaigns. **REQUIRED** when campaign's `objective_type` is set to `"WEB_CONVERSION"`. type: object allOf: - $ref: '#/components/schemas/OptimizationGoalMetadata' nullable: true pacing_delivery_type: $ref: '#/components/schemas/PacingDeliveryType' placement_group: description: Placement group. allOf: - $ref: '#/components/schemas/PlacementGroupType' promotion_application_level: description: Specify if the promotion is applied at ad group or item level type: string example: ITEM enum: - NONE - ITEM - AD_GROUP - null nullable: true promotion_id: description: Promotion ID. To clear this field, set to null. type: string example: '7834020347906' default: '0' nullable: true pattern: ^\d+$ promotion_ids: description: Promotion IDs list. To clear this field, set to an empty array []. type: array items: type: string example: - '7834020347906' - '7834020347907' start_time: description: |- Timestamp in Unix format for scheduling when ads in the ad group start to appear. If not specified, ads appear during parent campaign's `start_time`. Cannot precede `start_time` for parent campaign (if specified). Learn about scheduling ads. For certain organizations (Closed beta): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO. type: integer example: 5686848000 nullable: true status: description: Ad group/entity status. allOf: - $ref: '#/components/schemas/EntityStatus' targeting_spec: $ref: '#/components/schemas/TargetingSpec' targeting_template_ids: description: "Targeting template IDs applied to the ad group. We currently only support 1 targeting template per ad group. To use targeting templates, do not set any other targeting fields: targeting_spec, tracking_urls, auto_targeting_enabled, placement_group. To clear all targeting template IDs, set this field to ['0']." type: array items: type: string pattern: ^\d+$ description: Targeting template ID. maxItems: 1 nullable: true tracking_urls: description: 'Third-party tracking URLs.
JSON object with the format: {"Tracking event enum":[URL string array],...}
For example: {"impression": ["URL1", "URL2"], "click": ["URL1", "URL2", "URL3"]}.
Up to three tracking URLs are supported for each event type. Tracking URLs set at the ad group or ad level can override those set at the campaign level. May be null. Pass in an empty object - EmptyObject - to remove tracking URLs.

For more information, see Third-party and dynamic tracking.' type: object allOf: - $ref: '#/components/schemas/TrackingUrls' nullable: true allOf: - type: object properties: auto_targeting_enabled: $ref: '#/components/schemas/AutoTargetingEnabled' bid_multiplier: description: |- Pinterest Performance+ campaigns. type: number maximum: 10 minimum: 0 budget_type: default: DAILY allOf: - $ref: '#/components/schemas/BudgetType' pacing_delivery_type: default: STANDARD allOf: - $ref: '#/components/schemas/PacingDeliveryType' required: - billable_event - campaign_id - name title: AdGroupCreateRequest AdGroupCreateRequestAllOf1: type: object properties: auto_targeting_enabled: $ref: '#/components/schemas/AutoTargetingEnabled' bid_multiplier: description: |- Pinterest Performance+ campaigns. type: number maximum: 10 minimum: 0 budget_type: default: DAILY allOf: - $ref: '#/components/schemas/BudgetType' pacing_delivery_type: default: STANDARD allOf: - $ref: '#/components/schemas/PacingDeliveryType' AdGroupDeliveryEstimates: description: Ad group configuration for delivery estimates. type: object properties: auto_targeting_enabled: type: boolean creative_types: description: Pin creative types filter. **Note:** SHOP_THE_PIN has been deprecated. Please use COLLECTION instead. type: array items: $ref: '#/components/schemas/AdGroupAudienceSizingCreativeTypes' keywords: description: Array of keyword objects. If the keywords field is missing, all keywords will be targeted. type: array items: $ref: '#/components/schemas/AdGroupDeliveryEstimatesKeywordsItems' nullable: true monthly_frequency_cap: description: Set a limit to the number of times a promoted pin from this campaign can be impressed by a pinner within the past rolling 30 days. Only available for CPM (cost per mille (1000 impressions)) ad groups. type: integer minimum: 0 optimization_goal_metadata: $ref: '#/components/schemas/OptimizationGoalMetadata' optimization_type: description: Optimization type for ad group delivery. Defaults to WEB_CONVERSION for WEB_CONVERSION/AWARENESS objectives, CLICKTHROUGH otherwise. allOf: - $ref: '#/components/schemas/OptimizationType' placement_group: $ref: '#/components/schemas/PlacementGroupType' product_group_ids: description: '[Targeted product group IDs](/docs/redoc/#section/AdGroup-Audience-Sizing) **Note:** This can only be combined with shopping/catalog sales campaigns.' type: array items: $ref: '#/components/schemas/DeliveryEstimatesProductGroupId' targeting_spec: $ref: '#/components/schemas/TargetingSpecOptimal' AdGroupDeliveryEstimatesKeywordsItems: type: object properties: match_type: allOf: - $ref: '#/components/schemas/NullalbleMatchType' nullable: true value: description: Keyword value (120 chars max). type: string required: - match_type - value AdGroupIdType: type: string maxLength: 18 pattern: ^\d+$ AdGroupSummaryStatus: description: Summary status for ad group type: string example: RUNNING enum: - RUNNING - PAUSED - NOT_STARTED - COMPLETED - ADVERTISER_DISABLED - ARCHIVED - DRAFT - DELETED_DRAFT AdGroupTrackingURLs: description: |2- Third-party tracking URLs. Up to three tracking URLs - with a max length of 2,000 - are supported for each event type. Tracking URLs set at the ad group or ad level can override those set at the campaign level. For more information, see [Third-party and dynamic tracking](https://help.pinterest.com/en/business/article/third-party-and-dynamic-tracking). type: object properties: audience_verification: type: array items: type: string buyable_button: type: array items: type: string click: type: array items: type: string engagement: type: array items: type: string impression: type: array items: type: string example: impression: - URL1 - URL2 click: - URL1 - URL2 engagement: - URL1 - URL2 buyable_button: - URL1 - URL2 audience_verification: - URL1 - URL2 nullable: true AdGroupUpdate: type: object properties: auto_targeting_enabled: description: Enable auto-targeting for ad group. Default value is True. Also known as ["Performance+ targeting"](https://help.pinterest.com/en/business/article/performance-plus-targeting). type: boolean nullable: true bid_multiplier: description: '[Open beta](https://help.pinterest.com/en/business/article/beta-features) Bid multiplier for ad group. This value is a double between 0.1 and 10.0. Enter 0 to remove the bid multiplier. - Not currently supported for [Performance+ campaigns](https://help.pinterest.com/en/business/article/performance-plus-campaigns).' type: number maximum: 10 minimum: 0 budget_type: $ref: '#/components/schemas/BudgetType' pacing_delivery_type: $ref: '#/components/schemas/PacingDeliveryType' allOf: - $ref: '#/components/schemas/AdGroupBase' AdGroupUpdateBatchUpdate: type: object properties: auto_targeting_enabled: description: Enable auto-targeting for ad group. Default value is True. Also known as ["Performance+ targeting"](https://help.pinterest.com/en/business/article/performance-plus-targeting). type: boolean nullable: true bid_in_micro_currency: description: 'Bid price in micro currency. This field is **REQUIRED** for the following campaign objective_type/billable_event combinations: AWARENESS/IMPRESSION, CONSIDERATION/CLICKTHROUGH, CATALOG_SALES/CLICKTHROUGH, VIDEO_VIEW/VIDEO_V_50_MRC.' type: integer nullable: true bid_multiplier: description: '[Open beta](https://help.pinterest.com/en/business/article/beta-features) Bid multiplier for ad group. This value is a double between 0.1 and 10.0. Enter 0 to remove the bid multiplier. - Not currently supported for [Performance+ campaigns](https://help.pinterest.com/en/business/article/performance-plus-campaigns).' type: number maximum: 10 minimum: 0 bid_strategy_type: $ref: '#/components/schemas/BidStrategyType' billable_event: $ref: '#/components/schemas/ActionType' budget_in_micro_currency: description: Budget in micro currency. This field is **REQUIRED** for non-CBO (campaign budget optimization) campaigns. A CBO campaign automatically generates ad group budgets from its campaign budget to maximize campaign outcome. A CBO campaign is limited to 70 or less ad groups. type: integer nullable: true budget_type: $ref: '#/components/schemas/BudgetType' campaign_id: description: Campaign ID of the ad group. type: string pattern: ^[C]?\d+$ customer_segment_id: description: Customer segment ID applied to the ad group. We currently only support 1 customer segment per ad group. To use customer segments, do not set the `targeting_template_ids` field as well as the `AUDIENCE_INCLUDE` field of the `targeting_spec`. To clear the customer segment ID, set this field to '0'. allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' end_time: description: |- Timestamp in Unix format for scheduling when ads in the ad group stop appearing. If not specified, ads run indefinitely unless you update the ad group by changing their status to `paused`. Cannot occur after `end_time` for parent campaign (if specified). Learn about [scheduling ads](https://help.pinterest.com/en/business/article/ads-manager-schedule-ads). For certain organizations ([Closed beta](https://help.pinterest.com/en/business/article/beta-features)): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO. type: integer nullable: true ext_features: $ref: '#/components/schemas/AdgroupTrackingFeatures' feed_profile_id: description: Feed Profile ID associated to the adgroup. type: string id: description: Ad group ID. type: string maxLength: 18 pattern: ^\d+$ is_creative_optimization: description: Enable creative optimization for the ad group, default value is FALSE. When enabled, you allow Pinterest to automatically turn your product Pins into ads in different formats (collections and shopping) and deliver those ads to users at scale. type: boolean nullable: true is_local_inventory: description: Indicates whether the ad group should use the local inventory. type: boolean lifetime_frequency_cap: description: Set a limit to the number of times a promoted pin from this campaign can be impressed by a pinner within the past rolling 30 days. Only available for CPM (cost per mille (1000 impressions)) ad groups. A CPM ad group has an IMPRESSION [billable_event](https://help.pinterest.com/en/business/article/billable-events) value. This field **REQUIRES** the `end_time` field. type: integer local_inventory_radius_in_miles: description: The targeting radius of the local inventory ads in miles. type: number name: description: Ad group name. type: string optimization_goal_metadata: description: Optimization goals for objective-based performance campaigns. **REQUIRED** when campaign's `objective_type` is set to `"WEB_CONVERSION"`. type: object allOf: - $ref: '#/components/schemas/NullableOptimizationGoalMetadata' nullable: true pacing_delivery_type: $ref: '#/components/schemas/PacingDeliveryType' performance_plus_campaign_settings: description: Pinterest Performance+ campaign settings. type: object allOf: - $ref: '#/components/schemas/PerformancePlusCampaignSettings' nullable: true placement_group: description: '[Placement group](https://help.pinterest.com/en/business/article/placement-groups).' allOf: - $ref: '#/components/schemas/PlacementGroupType' placement_traffic_type: description: A targeting option that enables advertisers to choose whether to run ads in fullscreen feed, two column feed, or both allOf: - $ref: '#/components/schemas/PlacementTrafficType' nullable: true promotion_application_level: description: Specify if the promotion is applied at ad group or item level example: ITEM allOf: - $ref: '#/components/schemas/PromotionApplicationLevel' nullable: true promotion_id: description: Promotion ID. To clear this field, set to null. type: string default: '0' nullable: true pattern: ^\d+$ promotion_ids: description: Promotion IDs list. To clear this field, set to an empty array []. type: array items: type: string start_time: description: "Timestamp in Unix format for scheduling when ads in the ad group start to appear. If not specified, ads appear during parent campaign's `start_time`. Cannot precede `start_time` for parent campaign (if specified). Learn about [scheduling ads](/docs/api-features/managing-ads/#step-2-create-an-ad-group). For certain organizations ([Closed beta](/docs/getting-started/using-beta-and-restricted-features/)): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO." type: integer nullable: true status: description: Ad group/entity status. allOf: - $ref: '#/components/schemas/EntityStatus' targeting_spec: $ref: '#/components/schemas/TargetingSpecOptimal' targeting_spec_operations: type: array items: $ref: '#/components/schemas/TargetingSpecOperations' targeting_template_ids: description: "Targeting template IDs applied to the ad group. We currently only support 1 targeting template per ad group. To use targeting templates, do not set any other targeting fields: targeting_spec, tracking_urls, auto_targeting_enabled, placement_group. To clear all targeting template IDs, set this field to ['0']." type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' maxItems: 1 nullable: true tracking_urls: $ref: '#/components/schemas/AdGroupTrackingURLs' required: - id AdGroupUpdateRequest: type: object properties: auto_targeting_enabled: description: Enable auto-targeting for ad group. Default value is True. Also known as "Pinterest Performance+ targeting". type: boolean example: true nullable: true bid_in_micro_currency: description: 'Bid price in micro currency. This field is **REQUIRED** for the following campaign objective_type/billable_event combinations: AWARENESS/IMPRESSION, CONSIDERATION/CLICKTHROUGH, CATALOG_SALES/CLICKTHROUGH.' type: integer example: 5000000 nullable: true bid_strategy_type: $ref: '#/components/schemas/BidStrategyType' billable_event: $ref: '#/components/schemas/ActionType' budget_in_micro_currency: description: Budget in micro currency. This field is **REQUIRED** for non-CBO (campaign budget optimization) campaigns. A CBO campaign automatically generates ad group budgets from its campaign budget to maximize campaign outcome. A CBO campaign is limited to 70 or less ad groups. type: integer example: 5000000 nullable: true budget_type: $ref: '#/components/schemas/BudgetType' campaign_id: description: Campaign ID of the ad group. type: string example: '626736533506' pattern: ^[C]?\d+$ end_time: description: |- Timestamp in Unix format for scheduling when ads in the ad group stop appearing. If not specified, ads run indefinitely unless you update the ad group by changing their status to `paused`. Cannot occur after `end_time` for parent campaign (if specified). Learn about scheduling ads. For certain organizations (Closed beta): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO. type: integer example: 5705424000 nullable: true is_creative_optimization: description: Enable creative optimization for the ad group, default value is FALSE. When enabled, you allow Pinterest to automatically turn your product Pins into ads in different formats (collections and shopping) and deliver those ads to users at scale. type: boolean example: true nullable: true lifetime_frequency_cap: description: Set a limit to the number of times a promoted pin from this campaign can be impressed by a pinner within the past rolling 30 days. Only available for CPM (cost per mille (1000 impressions)) ad groups. A CPM ad group has an IMPRESSION billable_event value. This field **REQUIRES** the `end_time` field. type: integer example: 100 name: description: Ad group name. type: string example: 'Ad Group For Pin: 687195905986' optimization_goal_metadata: description: Optimization goals for objective-based performance campaigns. **REQUIRED** when campaign's `objective_type` is set to `"WEB_CONVERSION"`. type: object allOf: - $ref: '#/components/schemas/OptimizationGoalMetadata' nullable: true pacing_delivery_type: $ref: '#/components/schemas/PacingDeliveryType' placement_group: description: Placement group. allOf: - $ref: '#/components/schemas/PlacementGroupType' promotion_application_level: description: Specify if the promotion is applied at ad group or item level type: string example: ITEM enum: - NONE - ITEM - AD_GROUP - null nullable: true promotion_id: description: Promotion ID. To clear this field, set to null. type: string example: '7834020347906' default: '0' nullable: true pattern: ^\d+$ promotion_ids: description: Promotion IDs list. To clear this field, set to an empty array []. type: array items: type: string example: - '7834020347906' - '7834020347907' start_time: description: |- Timestamp in Unix format for scheduling when ads in the ad group start to appear. If not specified, ads appear during parent campaign's `start_time`. Cannot precede `start_time` for parent campaign (if specified). Learn about scheduling ads. For certain organizations (Closed beta): Supported for campaigns with Campaign Budget Optimization (CBO). For all organizations: Supported for campaigns without CBO. type: integer example: 5686848000 nullable: true status: description: Ad group/entity status. allOf: - $ref: '#/components/schemas/EntityStatus' targeting_spec: $ref: '#/components/schemas/TargetingSpec' targeting_template_ids: description: "Targeting template IDs applied to the ad group. We currently only support 1 targeting template per ad group. To use targeting templates, do not set any other targeting fields: targeting_spec, tracking_urls, auto_targeting_enabled, placement_group. To clear all targeting template IDs, set this field to ['0']." type: array items: type: string pattern: ^\d+$ description: Targeting template ID. maxItems: 1 nullable: true tracking_urls: description: 'Third-party tracking URLs.
JSON object with the format: {"Tracking event enum":[URL string array],...}
For example: {"impression": ["URL1", "URL2"], "click": ["URL1", "URL2", "URL3"]}.
Up to three tracking URLs are supported for each event type. Tracking URLs set at the ad group or ad level can override those set at the campaign level. May be null. Pass in an empty object - EmptyObject - to remove tracking URLs.

For more information, see Third-party and dynamic tracking.' type: object allOf: - $ref: '#/components/schemas/TrackingUrls' nullable: true allOf: - type: object required: - id properties: bid_multiplier: description: |- Pinterest Performance+ campaigns. type: number maximum: 10 minimum: 0 id: description: Ad group ID. type: string pattern: ^\d+$ targeting_spec_operations: description: |-

Targeting spec operations define modifications to apply to the targeting spec.

NOTE: The targeting_spec and targeting_spec_operations cannot be sent at the same time.

The supported operations are:
Note the following:
type: array items: $ref: '#/components/schemas/TargetingSpecOperations' title: AdGroupUpdateRequest AdGroupUpdateRequestAllOf1: type: object properties: bid_multiplier: description: |- Pinterest Performance+ campaigns. type: number maximum: 10 minimum: 0 id: description: Ad group ID. type: string pattern: ^\d+$ targeting_spec_operations: description: |-
Targeting spec operations define modifications to apply to the targeting spec.

NOTE: The targeting_spec and targeting_spec_operations cannot be sent at the same time.

The supported operations are:
Note the following:
type: array items: $ref: '#/components/schemas/TargetingSpecOperations' required: - id AdGroupsAnalyticsMetrics: type: object properties: AD_GROUP_ID: description: The ID of the ad group that this metrics belongs to. Returned as long as aggregate_report_rows is not true. type: string pattern: ^\d+$ DATE: description: Current metrics date. Only returned when granularity is a time-based value (`DAY`, `HOUR`, `WEEK`, `MONTH`) type: string format: date AdPinAnalytics: type: object properties: DATE: description: Current metrics date. Only returned when granularity is a time-based value (`DAY`, `HOUR`, `WEEK`, `MONTH`) type: string format: date PIN_ID: description: The ID of the pin that the metric belongs to. type: string pattern: ^\d+$ example: DATE: 2021-04-01 PIN_ID: '217861700718936379' SPEND_IN_DOLLAR: 30 TOTAL_CLICKTHROUGH: 216 required: - PIN_ID AdPinPreviewCreativeType: type: string enum: - SHOPPING - COLLECTION - MAX_VIDEO - MAX_WIDTH_VIDEO_COLLECTION - MAX_WIDTH_REGULAR_COLLECTION AdPreviewRequest: oneOf: - $ref: '#/components/schemas/AdPreviewSourceImage' - $ref: '#/components/schemas/AdPreviewSourcePinId' - $ref: '#/components/schemas/AdPreviewShopping' AdPreviewShopping: description: Ad preview from a catalog product group (shopping). type: object properties: catalog_product_group_id: description: Catalog Product Group Id. type: string example: '123456789' pattern: ^\d+$ title: catalog_product_group_id creative_type: description: Ad format of the shopping ad preview. example: SHOPPING allOf: - $ref: '#/components/schemas/AdShoppingPreviewCreativeType' customizable_cta_type: description: Select a call to action (CTA) to display below your ad. CTA options for catalog sales campaigns are `SHOP_NOW`, `BOOK_NOW`, `ON_SALE`, `GET_DEAL`, `BUY_ONLINE_PICKUP_IN_STORE` allOf: - $ref: '#/components/schemas/CustomizableCTAType' hero_image_title: description: Title displayed below ad. type: string example: My Preview Image title: hero_image_title hero_image_url: description: Hero image URL. type: string example: https://somewebsite.com/someimage.jpg title: hero_image_url hero_pin_id: description: Pin id for the hero image. When creative type is COLLECTION, either hero_pin_id or (hero_image_url, hero_image_title) is required. type: string example: '987654321' pattern: ^\d+$ title: hero_pin_id image_tag: description: Multi image template tag. type: string example: Christmas Sale title: image_tag item_id: description: Item id for product to preview standard shopping ads, optional and only applicable when creative type is SHOPPING. type: string example: '111111111' title: item_id preferred_media_type: description: Preferred media type. example: IMAGE allOf: - $ref: '#/components/schemas/BasePreferredMediaType' show_promotion: description: Include promotion data in preview when available on catalog item. Defaults to false. type: boolean title: show_promotion video_tag: description: Multi video template tag, image_tag and video_tag are mutual exclusive. type: string example: Black Friday Sale title: video_tag example: catalog_product_group_id: '123456789' image_tag: Christmas Sale creative_type: COLLECTION hero_pin_id: '987654321' required: - catalog_product_group_id - creative_type title: AdPreviewShopping AdPreviewSourceImage: description: Ad preview source from an image URL. type: object properties: image_url: description: Image URL. type: string example: https://somewebsite.com/someimage.jpg title: image_url promotion_id: description: Promotion id for the ad to preview, optional and only applicable when creating ad preview for an existing promotion. type: string example: '7834020404549' pattern: ^\d+$ title: promotion_id title: description: Title displayed below ad. type: string example: My Preview Image title: title example: image_url: https://somewebsite.com/someimage.jpg title: My Preview Image required: - image_url - title title: AdPreviewCreateFromImage AdPreviewSourcePinId: description: Ad preview source from an existing Pin. type: object properties: creative_type: description: Creative type of the ad preview. example: MAX_WIDTH_VIDEO_COLLECTION allOf: - $ref: '#/components/schemas/AdPinPreviewCreativeType' title: creative_type pin_id: description: Pin ID. type: string example: '7389479023' title: pin_id example: pin_id: '7389479023' required: - pin_id title: AdPreviewCreateFromPin AdPreviewURLResponse: type: object properties: url: description: |- Preview URL, expires in 7 days. Can be used in an iframe. For example: https://ads.pinterest.com/ad-preview/74667c814dd2b19/ The preview object ID/key is the last param - 74667c814dd2b19 type: string example: https://ads.pinterest.com/ad-preview/58f1a0e9ab0bd0f99462a0e4c5dd7e8297888c8a36331e88f757abe8f0295d31/ title: url example: url: https://ads.pinterest.com/ad-preview/58f1a0e9ab0bd0f99462a0e4c5dd7e8297888c8a36331e88f757abe8f0295d31/ title: AdPreviewURLResponse AdReviewStatus: description: Ad review status type: string enum: - OTHER - PENDING - REJECTED - APPROVED AdShoppingPreviewCreativeType: type: string enum: - SHOPPING - COLLECTION - CAROUSEL - MAX_WIDTH_COLLECTION AdUpdateRequest: type: object properties: ad_group_id: description: ID of the ad group that contains the ad. type: string pattern: ^(AG)?\d+$ android_deep_link: description: Deep link URL for Android devices. type: string nullable: true carousel_android_deep_links: description: Comma-separated deep links for the carousel pin on Android. type: array items: type: string nullable: true carousel_destination_urls: description: Comma-separated destination URLs for the carousel pin to promote. type: array items: type: string nullable: true carousel_ios_deep_links: description: Comma-separated deep links for the carousel pin on iOS. type: array items: type: string nullable: true click_tracking_url: description: Tracking url for the ad clicks. type: string nullable: true creative_type: $ref: '#/components/schemas/CreativeType' customizable_cta_type: $ref: '#/components/schemas/CustomizableCTAType' destination_url: description: Destination URL. type: string nullable: true disclosure_type: $ref: '#/components/schemas/DisclosureType' disclosure_url: description: URL for a page that provides disclosures about a pharmaceutical product, such as potential side effects. Make sure the URL takes the user directly to the disclosure content and the referenced site is secure. type: string nullable: true grid_click_type: $ref: '#/components/schemas/GridClickType' ios_deep_link: description: Deep link URL for iOS devices. type: string nullable: true is_carting: description: Is the ad a carting/WTB ad? type: boolean is_pin_deleted: description: Is original pin deleted? type: boolean example: false is_removable: description: Is pin repinnable? type: boolean example: false lead_form_id: description: Lead form ID for lead ad generation. type: string nullable: true pattern: ^(AG)?\d+$ name: description: Name of the ad - 255 chars max. type: string nullable: true quiz_pin_data: description: Before creating a quiz ad, you must create an organic Pin using POST/Create Pin for each result in the quiz. Quiz ads cannot be saved by a Pinner. Quiz ad results can be saved. type: object allOf: - $ref: '#/components/schemas/QuizPinData' nullable: true status: $ref: '#/components/schemas/EntityStatus' tracking_urls: type: object allOf: - $ref: '#/components/schemas/TrackingUrls' nullable: true view_tracking_url: description: Tracking URL for ad impressions. type: string nullable: true allOf: - type: object required: - id properties: id: description: The ID of this ad. type: string pattern: ^\d+$ title: id pin_id: description: Pin ID. This field may only be updated for draft ads. type: string nullable: true pattern: ^\d+$ title: AdUpdateRequest title: AdUpdateRequest AdUpdateRequestAllOf1: type: object properties: id: description: The ID of this ad. type: string pattern: ^\d+$ title: id pin_id: description: Pin ID. This field may only be updated for draft ads. type: string nullable: true pattern: ^\d+$ required: - id title: AdUpdateRequest AdeColumn: description: ADE column identifier type: string example: ADE_COST_PER_ACTION-download_picture pattern: ^ADE_[A-Z_]+-[a-zA-Z0-9 _-]*$ AdeColumnType: description: Metrics for custom defined conversion event. type: string enum: - ADE_COST_PER_ACTION - ADE_ROAS - ADE_TOTAL_CONVERSIONS - ADE_TOTAL_VALUE_IN_MICRO_DOLLAR - ADE_AVERAGE_VALUE_IN_MICRO_DOLLAR - ADE_TOTAL_CLICK - ADE_TOTAL_CLICK_VALUE_IN_MICRO_DOLLAR - ADE_TOTAL_VIEW - ADE_TOTAL_VIEW_VALUE_IN_MICRO_DOLLAR - ADE_TOTAL_CONVERSION_RATE - ADE_WEB_COST_PER_ACTION - ADE_WEB_ROAS - ADE_TOTAL_WEB_CONVERSIONS - ADE_TOTAL_WEB_VALUE_IN_MICRO_DOLLAR - ADE_TOTAL_WEB_CLICK - ADE_TOTAL_WEB_CLICK_VALUE_IN_MICRO_DOLLAR - ADE_TOTAL_WEB_VIEW - ADE_TOTAL_WEB_VIEW_VALUE_IN_MICRO_DOLLAR - ADE_INAPP_COST_PER_ACTION - ADE_INAPP_ROAS - ADE_TOTAL_INAPP_CONVERSIONS - ADE_TOTAL_INAPP_VALUE_IN_MICRO_DOLLAR - ADE_TOTAL_INAPP_CLICK - ADE_TOTAL_INAPP_CLICK_VALUE_IN_MICRO_DOLLAR - ADE_TOTAL_INAPP_VIEW - ADE_TOTAL_INAPP_VIEW_VALUE_IN_MICRO_DOLLAR - ADE_OFFLINE_COST_PER_ACTION - ADE_OFFLINE_ROAS - ADE_TOTAL_OFFLINE_CONVERSIONS - ADE_TOTAL_OFFLINE_VALUE_IN_MICRO_DOLLAR - ADE_TOTAL_OFFLINE_CLICK - ADE_TOTAL_OFFLINE_CLICK_VALUE_IN_MICRO_DOLLAR - ADE_TOTAL_OFFLINE_VIEW - ADE_TOTAL_OFFLINE_VIEW_VALUE_IN_MICRO_DOLLAR - ADE_TOTAL_CONVERSION_PRODUCT_QUANTITY - ADE_TOTAL_CONVERSION_PRODUCT_VALUE - ADE_TOTAL_CONVERSION_PRODUCT_VALUE_IN_MICRO_UNITS - ADE_TOTAL_CONVERSION_PRODUCT_VALUE_IN_USD - ADE_TOTAL_CONVERSION_PRODUCT_VALUE_IN_MICRO_USD - ADE_TOTAL_WEB_CONVERSION_PRODUCT_QUANTITY - ADE_TOTAL_WEB_CONVERSION_PRODUCT_VALUE - ADE_TOTAL_WEB_CONVERSION_PRODUCT_VALUE_IN_MICRO_UNITS - ADE_TOTAL_WEB_CONVERSION_PRODUCT_VALUE_IN_USD - ADE_TOTAL_WEB_CONVERSION_PRODUCT_VALUE_IN_MICRO_USD - ADE_TOTAL_INAPP_CONVERSION_PRODUCT_QUANTITY - ADE_TOTAL_INAPP_CONVERSION_PRODUCT_VALUE - ADE_TOTAL_INAPP_CONVERSION_PRODUCT_VALUE_IN_MICRO_UNITS - ADE_TOTAL_INAPP_CONVERSION_PRODUCT_VALUE_IN_USD - ADE_TOTAL_INAPP_CONVERSION_PRODUCT_VALUE_IN_MICRO_USD - ADE_TOTAL_OFFLINE_CONVERSION_PRODUCT_QUANTITY - ADE_TOTAL_OFFLINE_CONVERSION_PRODUCT_VALUE - ADE_TOTAL_OFFLINE_CONVERSION_PRODUCT_VALUE_IN_MICRO_UNITS - ADE_TOTAL_OFFLINE_CONVERSION_PRODUCT_VALUE_IN_USD - ADE_TOTAL_OFFLINE_CONVERSION_PRODUCT_VALUE_IN_MICRO_USD AdgroupPlacementGroupType: description: Campaign placement group type type: string enum: - ALL - SEARCH - BROWSE - OTHER AdgroupTrackingFeatureType: type: string enum: - TRENDS - CLONE_META - BULK_EDITOR - AD_ROTATION AdgroupTrackingFeatures: type: object properties: enabled: description: Tracking features. To clear this field, set to null. type: array items: $ref: '#/components/schemas/AdgroupTrackingFeatureType' nullable: true AdsAnalytics: type: object properties: AD_ID: type: string pattern: ^\d+$ DATE: type: string format: date required: - AD_ID AdsAnalyticsAccountTargetingType: description: Reporting targeting type type: string example: APPTYPE enum: - KEYWORD - APPTYPE - GENDER - LOCATION - PLACEMENT - COUNTRY - TARGETED_INTEREST - PINNER_INTEREST - AUDIENCE_INCLUDE - GEO - AGE_BUCKET - REGION - AGE_BUCKET_AND_GENDER AdsAnalyticsAdGroupTargetingType: description: Reporting targeting type for ad groups type: string example: APPTYPE enum: - KEYWORD - APPTYPE - GENDER - LOCATION - PLACEMENT - COUNTRY - TARGETED_INTEREST - PINNER_INTEREST - AUDIENCE_INCLUDE - GEO - AGE_BUCKET - REGION - AGE_BUCKET_AND_GENDER - CREATIVE_ENHANCEMENTS AdsAnalyticsAdTargetingType: description: Reporting targeting type for ads type: string example: APPTYPE enum: - KEYWORD - APPTYPE - GENDER - LOCATION - PLACEMENT - COUNTRY - TARGETED_INTEREST - PINNER_INTEREST - AUDIENCE_INCLUDE - GEO - AGE_BUCKET - REGION - QUIZ_RESULT - AGE_BUCKET_AND_GENDER AdsAnalyticsCampaignTargetingType: description: Reporting targeting type for campaigns type: string example: APPTYPE enum: - KEYWORD - APPTYPE - GENDER - LOCATION - PLACEMENT - COUNTRY - TARGETED_INTEREST - PINNER_INTEREST - AUDIENCE_INCLUDE - GEO - AGE_BUCKET - REGION - CREATIVE_TYPE - AGE_BUCKET_AND_GENDER - AUDIENCE_MULTIPLIER AdsAnalyticsCreateAsyncRequest: type: object properties: ad_group_ids: description: List of ad group ids type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' maxItems: 500 minItems: 1 ad_group_statuses: description: List of values for filtering type: array items: $ref: '#/components/schemas/AdGroupSummaryStatus' maxItems: 6 minItems: 1 ad_ids: description: List of ad ids. This parameter is not supported for Product Item level reports. type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' maxItems: 500 minItems: 1 ad_statuses: description: List of values for filtering. This parameter is not supported for Product Item level reports. type: array items: $ref: '#/components/schemas/PinPromotionSummaryStatus' maxItems: 6 minItems: 1 attribution_types: description: List of attribution types for the conversion report. type: array items: $ref: '#/components/schemas/ConversionReportAttributionType' campaign_brand_label: description: Campaign brand label for filtering. type: string campaign_custom_label: description: Campaign custom label for filtering. type: string campaign_ids: description: List of campaign ids type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' maxItems: 500 minItems: 1 campaign_objective_types: description: List of values for filtering. ["WEB_SESSIONS"] is in BETA. type: array maxItems: 7 minItems: 1 campaign_statuses: description: List of status values for filtering type: array items: $ref: '#/components/schemas/CampaignSummaryStatus' maxItems: 6 minItems: 1 click_window_days: description: Number of days to use as the conversion attribution window for a pin click action. default: 30 allOf: - $ref: '#/components/schemas/ConversionAttributionWindowDays' columns: description: Metric and entity columns. Pin promotion and ad related columns are not supported for Product Item level reports. type: array items: $ref: '#/components/schemas/ReportingColumnAsync' combine_targeting_types: description: Determines if the targeting types included in the request should be consolidated into a single breakdown. type: boolean default: false conversion_report_time: description: Date dimension for conversion metrics. default: TIME_OF_AD_ACTION allOf: - $ref: '#/components/schemas/ConversionReportTimeType' custom_conversion_event_metrics: description: List of advertiser-defined custom conversion event metrics to include in the report type: array items: $ref: '#/components/schemas/CustomConversionEventMetrics' end_date: description: 'Metric report end date (UTC). Format: YYYY-MM-DD' type: string pattern: ^\d{4}-\d{2}-\d{2}$ end_hour: description: Which hour of the end date to stop the report (inclusive). Only allowed for hourly reports. type: integer maximum: 23 minimum: 0 engagement_window_days: description: Number of days to use as the conversion attribution window for an engagement action. default: 30 allOf: - $ref: '#/components/schemas/ConversionAttributionWindowDays' granularity: description: |2- TOTAL - metrics are aggregated over the specified date range. DAY - metrics are broken down daily. HOUR - metrics are broken down hourly. WEEKLY - metrics are broken down weekly. MONTHLY - metrics are broken down monthly. allOf: - $ref: '#/components/schemas/Granularity' level: description: Level of the report allOf: - $ref: '#/components/schemas/MetricsReportingLevel' metrics_filters: description: List of metrics filters type: array items: $ref: '#/components/schemas/AdsAnalyticsMetricsFilter' minItems: 1 primary_sort: default: BY_ID allOf: - $ref: '#/components/schemas/PrimarySort' product_group_ids: description: List of product group ids type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' maxItems: 500 minItems: 1 product_group_statuses: description: List of values for filtering type: array items: $ref: '#/components/schemas/ProductGroupSummaryStatus' maxItems: 6 minItems: 1 product_item_ids: description: List of product item ids type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' maxItems: 500 minItems: 1 report_format: default: JSON allOf: - $ref: '#/components/schemas/DataOutputFormat' reporting_timezone: description: Specify the timezone to be applied for the reporting. allOf: - $ref: '#/components/schemas/ReportingTimeZone' start_date: description: 'Metric report start date (UTC). Format: YYYY-MM-DD' type: string pattern: ^\d{4}-\d{2}-\d{2}$ start_hour: description: Which hour of the start date to begin the report. Only allowed for hourly reports. type: integer maximum: 23 minimum: 0 targeting_types: description: List of targeting types. Requires `level` to be a value ending in `_TARGETING`. type: array items: $ref: '#/components/schemas/AdAdsAnalyticsAsyncTargetingTypes' maxItems: 5 minItems: 1 view_window_days: description: Number of days to use as the conversion attribution window for a view action. default: 1 allOf: - $ref: '#/components/schemas/ConversionAttributionWindowDays' required: - end_date - granularity - start_date AdsAnalyticsCreateAsyncResponse: type: object properties: message: type: string nullable: true report_status: $ref: '#/components/schemas/BulkReportingJobStatus' token: type: string AdsAnalyticsFilterColumn: description: Reporting columns for sync reporting data filter type: string example: SPEND_IN_DOLLAR enum: - SPEND_IN_DOLLAR - TOTAL_IMPRESSION AdsAnalyticsFilterOperator: description: Filter operator for sync reporting type: string example: LESS_THAN enum: - LESS_THAN - GREATER_THAN AdsAnalyticsGetAsyncResponse: type: object properties: report_status: $ref: '#/components/schemas/BulkReportingJobStatus' size: type: number nullable: true url: type: string nullable: true AdsAnalyticsMetricsFilter: type: object properties: field: $ref: '#/components/schemas/AdsAnalyticsFilterColumn' operator: $ref: '#/components/schemas/AdsAnalyticsFilterOperator' values: description: List of values for filtering type: array items: type: number minItems: 1 required: - field - operator - values AdsCreditDiscountType: type: string enum: - COUPON - CREDIT - COUPON_APPLIED - CREDIT_APPLIED - MARKETING_OFFER_CREDIT - MARKETING_OFFER_CREDIT_APPLIED - GOODWILL_CREDIT - GOODWILL_CREDIT_APPLIED - INTERNAL_CREDIT - INTERNAL_CREDIT_APPLIED - PREPAID_CREDIT - PREPAID_CREDIT_APPLIED - SALES_INCENTIVE_CREDIT - SALES_INCENTIVE_CREDIT_APPLIED - CREDIT_EXPIRED - FUTURE_CREDIT - REFERRAL_CREDIT - INVOICE_SALES_INCENTIVE_CREDIT - INVOICE_SALES_INCENTIVE_CREDIT_APPLIED - PREPAID_CREDIT_REFUND - null nullable: true AdsCreditDiscountsResponse: type: object properties: active: description: True if the offer code is currently active. type: boolean example: true advertiser_id: description: Advertiser ID the offer was applied to. type: string example: '12312451231' pattern: ^\d+$ discountCurrency: description: Currency value for the discount. type: string example: USD nullable: true discountInMicroCurrency: description: The discount applied in the offer's currency value. type: number example: 125000000 nullable: true discountType: description: The type of discount of this credit allOf: - $ref: '#/components/schemas/AdsCreditDiscountType' nullable: true remainingDiscountInMicroCurrency: description: The credits left to spend. type: number example: 125000000 nullable: true title: description: Human readable title of the offer code. type: string example: Ads Credits nullable: true AdsCreditRedeem: description: Ads credit redemption type: object properties: errorCode: description: Error code type if error occurs type: integer example: 2708 nullable: true readOnly: true errorMessage: description: Reason for failure type: string example: The offer has already been redeemed by this advertiser nullable: true readOnly: true success: description: Returns true if the offer code was successfully applied(validateOnly=false) or can be applied(validateOnly=true). type: boolean example: false readOnly: true example: offerCodeHash: 138e9e0ff7e38cf511b880975eb574c09aa9d5e1657590ab0431040da68caa67 validateOnly: true success: false errorCode: 2708 errorMessage: The offer has already been redeemed by this advertiser AdsCreditRedeemCreate: description: Resource create operation model. type: object properties: offerCodeHash: description: Takes in a SHA256 hash of the offerCode. type: string example: 138e9e0ff7e38cf511b880975eb574c09aa9d5e1657590ab0431040da68caa67 pattern: ^[a-z0-9]*$ validateOnly: description: If true, only validate if we can redeem offer code. Otherwise it will actually apply the offer code to the account type: boolean example: true required: - offerCodeHash - validateOnly AdvancedAuctionBidOptions: description: Object describing a retail catalog item's bid options (bid price and bid multipliers). type: object properties: app_type_multipliers: $ref: '#/components/schemas/AppTypeMultipliers' bid_in_micro_currency: description: Bid price in micro currency. A value of 0 will stop distribution for this item in `MAX_BID` ad groups in `CATALOG_SALES` campaigns. A value of `null` will fallback to the ad group's `bid_in_micro_currency`. type: integer format: int64 nullable: true placement_multipliers: $ref: '#/components/schemas/PlacementMultipliers' AdvancedAuctionItem: type: object properties: bid_options: $ref: '#/components/schemas/AdvancedAuctionBidOptions' country: $ref: '#/components/schemas/Country' item_id: description: The catalog retail item id in the merchant namespace type: string example: DS0294-M language: $ref: '#/components/schemas/Language' required: - country - item_id - language - bid_options title: Advanced Auction Item AdvancedAuctionItems: description: Response object containing item bid options type: object properties: catalog_id: description: Response object of item bid options example: '2680059592705' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' items: description: Array with item bid options type: array items: $ref: '#/components/schemas/AdvancedAuctionItem' AdvancedAuctionItemsGetRequest: description: Request object used to get bid options values for a batch of retail catalog items type: object properties: catalog_id: description: Catalog id pertaining to the retail item example: '2680059592705' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' items: description: A list of retail catalog items to fetch bid options for type: array items: $ref: '#/components/schemas/AdvancedAuctionKey' maxItems: 10000 minItems: 1 required: - catalog_id - items AdvancedAuctionItemsSubmitDeleteRecord: description: Object describing an item bid option deletion operation type: object properties: country: $ref: '#/components/schemas/Country' errors: description: Array with validation errors for the supplied item bid option modification operation. A non empty errors list means this single item operation was not applied. type: array items: $ref: '#/components/schemas/AdvancedAuctionOperationError' item_id: description: The catalog retail item id in the merchant namespace type: string example: DS0294-M language: $ref: '#/components/schemas/Language' operation: type: string enum: - DELETE example: item_id: DS0294-M country: US language: EN operation: DELETE errors: - code: 6 message: Bid in micro currency should be non-negative required: - country - item_id - language - operation AdvancedAuctionItemsSubmitRecord: description: Object describing an item bid option operation type: object discriminator: propertyName: operation mapping: UPSERT: '#/components/schemas/AdvancedAuctionItemsSubmitUpsertRecord' DELETE: '#/components/schemas/AdvancedAuctionItemsSubmitDeleteRecord' oneOf: - $ref: '#/components/schemas/AdvancedAuctionItemsSubmitUpsertRecord' - $ref: '#/components/schemas/AdvancedAuctionItemsSubmitDeleteRecord' AdvancedAuctionItemsSubmitRequest: description: Request containing operations to perform on bid prices and bid multipliers for a batch of retail catalog items type: object properties: catalog_id: description: Catalog id pertaining to all items example: '2680059592705' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' items: description: Array of item bid option operations type: array items: $ref: '#/components/schemas/AdvancedAuctionItemsSubmitRecord' maxItems: 10000 minItems: 1 required: - catalog_id - items AdvancedAuctionItemsSubmitUpsertRecord: description: Object describing an item bid option upsert operation type: object properties: bid_options: $ref: '#/components/schemas/AdvancedAuctionBidOptions' country: $ref: '#/components/schemas/Country' errors: description: Array with validation errors for the supplied item bid option modification operation. A non empty errors list means this single item operation was not applied. type: array items: $ref: '#/components/schemas/AdvancedAuctionOperationError' item_id: description: The catalog retail item id in the merchant namespace type: string example: DS0294-M language: $ref: '#/components/schemas/Language' operation: type: string enum: - UPSERT update_mask: description: The list of item bid option fields to be set or updated. Fields specified in the updated mask without a value specified in the `bid_options` object in the body will be set to `null`. If an item bid option record is being created, fields not specified in the update mask will be initialized to `null`. type: array items: $ref: '#/components/schemas/UpdateMaskBidOptionField' example: - BID - APP_TYPE_BID_MULTIPLIER_SET nullable: true example: item_id: DS0294-M country: US language: EN operation: UPSERT bid_options: bid_in_micro_currency: 5000000 app_type_multipliers: android_mobile: 1.1 android_tablet: 1.1 ipad: 1.2 iphone: 1.2 web: 0.9 web_mobile: 0.8 update_mask: - BID - APP_TYPE_BID_MULTIPLIER_SET errors: - code: 6 message: Bid in micro currency should be non-negative required: - country - item_id - language - bid_options - operation - update_mask AdvancedAuctionKey: description: Object uniquely identifying a retail catalog item type: object properties: country: $ref: '#/components/schemas/Country' item_id: description: The catalog retail item id in the merchant namespace type: string example: DS0294-M language: $ref: '#/components/schemas/Language' required: - country - item_id - language AdvancedAuctionOperationError: description: Error which occurred when applying a bid options operation to a specific item. type: object properties: code: description: The error code for the item bid option operation validation error type: integer example: 6 message: description: Message describing the item bid option operation validation error type: string example: Bid in micro currency should be non-negative AdvancedAuctionProcessedItems: description: Response object containing the results of an operation on an item bid option type: object properties: catalog_id: description: Catalog id pertaining to all items example: '2680059592705' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' items: description: Array of advanced auction processed items type: array items: $ref: '#/components/schemas/AdvancedAuctionItemsSubmitRecord' AdvertiserDefinedEvent: description: Advertiser defined event type: object properties: mapped_conversion_type: description: Standard type mapped to ADE for optimization example: SIGNUP allOf: - $ref: '#/components/schemas/ConversionTagTypeOptimal' name: description: Raw string name of the event, usually logged as raw_event_name in our dataset type: string example: newsletter_signup AdvertiserDefinedEventInput: description: Advertiser defined event input for create/update operations type: object properties: mapped_conversion_type: description: Pinterest standard event type to map this custom event to for campaign optimization and reporting example: SIGNUP allOf: - $ref: '#/components/schemas/AdvertiserDefinedEventMappingType' name: description: Raw string name of the event type: string example: newsletter_signup required: - name - mapped_conversion_type AdvertiserDefinedEventMappingType: description: |- Pinterest standard event types that a custom event can be mapped to. Restricted to event types that are valid ads optimization goals. type: string example: SIGNUP enum: - SIGNUP - ADD_TO_CART - LEAD - CHECKOUT - SUBSCRIBE - ADD_TO_WISHLIST - ADD_PAYMENT_INFO - INITIATE_CHECKOUT - CONTACT - CUSTOMIZE_PRODUCT - FIND_LOCATION - SCHEDULE - SUBMIT_APPLICATION - START_TRIAL - PAGE_VISIT - VIEW_CATEGORY - VIEW_CONTENT - SEARCH - WATCH_VIDEO AdvertiserDefinedEventProcessingRecord: description: Processing record for an advertiser defined event operation type: object properties: exceptions: description: List of exception messages if the operation failed type: array items: type: string name: description: Name of the advertiser defined event type: string example: newsletter_signup status: description: Processing status (success or failure) type: string example: success required: - name - status AdvertiserDefinedEventsCreateRequest: description: Request body for creating or updating advertiser defined events type: object properties: items: description: List of advertiser defined events to create or update type: array items: $ref: '#/components/schemas/AdvertiserDefinedEventInput' minItems: 1 required: - items AgeBucketMultipliers: description: |- This represents a mapping from age bucket to a bid price adjustment. Multiplier values must be between 0 and 10. A value of 10 represents a 900% increase in bid price (from $1 to $10 for example). A value of 0 will stop distribution for this item on the specified age bucket in `MAX_BID` ad groups in `CATALOG_SALES` campaigns. All age bucket multipliers must be set at the same time. If a multiplier is not provided it is assumed to be 1 (no bid adjustment). type: object properties: AGE_BUCKET: description: Age bucket identifier. allOf: - $ref: '#/components/schemas/TargetingSpecAgeBucket' example: 18-24: 0.9 25-34: 1.1 35-44: 1.2 additionalProperties: $ref: '#/components/schemas/AgeBucketMultipliersAdditionalProperties' nullable: true AgeBucketMultipliersAdditionalProperties: description: Bid multiplier value for age bucket targeting. Must be a float64. type: number format: double AgeTrendsBucket: type: string enum: - 18-24 - 25-34 - 35-44 - 45-49 - 50-54 - 55-64 - 65+ AggregatedPinComment: type: object properties: ai_disclosures: description: AI disclosure declarations the creator has made about this Pin. allOf: - $ref: '#/components/schemas/AiDisclosures' alt_text: type: string maxLength: 500 nullable: true board_id: description: The board to which this Pin belongs. type: string pattern: ^\d+$ board_owner: allOf: - $ref: '#/components/schemas/BoardOwner' readOnly: true board_section_id: description: The board section to which this Pin belongs. type: string nullable: true pattern: ^\d+$ created_at: type: string format: date-time readOnly: true creative_type: allOf: - $ref: '#/components/schemas/CreativeType' nullable: true readOnly: true description: type: string maxLength: 800 nullable: true dominant_color: description: Dominant pin color. Hex number, e.g. `#6E7874`. type: string nullable: true has_been_promoted: description: Whether the Pin has been promoted or not. type: boolean readOnly: true id: type: string pattern: ^\d+$ is_owner: description: Whether the "operation user_account" is the Pin owner. type: boolean readOnly: true is_product: description: Whether the Pin is a product Pin. type: boolean readOnly: true is_standard: description: Whether the Pin is standard or not. See documentation on [Changes to Pin creation](/docs/api-features/content-overview/) for more information. type: boolean readOnly: true link: type: string maxLength: 2048 nullable: true media: allOf: - $ref: '#/components/schemas/PinMedia' readOnly: true parent_pin_id: description: The source pin id if this pin was saved from another pin. [Learn more](https://help.pinterest.com/article/save-pins-on-pinterest). type: string nullable: true pattern: ^\d+$ pin_metrics: description: Pin metrics with associated time intervals if any. type: object example: 90d: pin_click: 7 impression: 2 clickthrough: 3 lifetime_metrics: pin_click: 7 impression: 2 clickthrough: 3 reaction: 10 comment: 2 nullable: true readOnly: true title: type: string maxLength: 100 nullable: true nullable: true required: - id AiDisclosureItem: description: AI disclosure declaration the creator has made about the Pin. type: string enum: - AI_MODIFIED - SYNTHETIC_PERFORMER AiDisclosures: description: AI disclosure declarations the creator has made about the Pin. type: object properties: values: description: List of AI disclosure declarations the creator has made about this Pin. type: array items: $ref: '#/components/schemas/AiDisclosureItem' required: - values AiDisclosuresUpdate: description: AI disclosure declarations the creator has made about the Pin. type: object properties: values: description: List of AI disclosure declarations the creator has made about this Pin. type: array items: $ref: '#/components/schemas/AiDisclosureItem' AmazonConnectRequest: description: Request containing OTP and Amazon storefront info called by Amazon type: object properties: amazon_storefront_id: description: The Amazon storefront id type: string amazon_storefront_name: description: The Amazon storefront name type: string amazon_storefront_url: description: The Amazon storefront url type: string amazon_user_id: description: The Amazon user id type: string is_amazon_account_linked: description: The Amazon account linking status type: boolean one_time_passcode: description: The one time passcode for Pinterest-initiated linking requests type: string example: 089aee0d-92d3-4f8f-a947-6dc016d85bf0 pinterest_user_id: description: The Pinterest user id for Amazon-initiated linking requests type: string example: '902057137772013006' pattern: ^\d+$ required: - amazon_storefront_name - amazon_storefront_url - is_amazon_account_linked title: AmazonConnectRequest AmazonConnectResponse: type: object properties: message: description: Amazon connect response message type: string AnalyticsDailyMetrics: type: object properties: data_status: $ref: '#/components/schemas/DataStatus' date: description: 'Metrics date (UTC): YYYY-MM-DD.' type: string example: 2019-12-01 metrics: type: object additionalProperties: type: number AnalyticsMetricsResponse: type: object properties: daily_metrics: description: Array with the requested daily metric records type: array items: $ref: '#/components/schemas/AnalyticsDailyMetrics' summary_metrics: description: The metric name and value over the requested period for each requested metric type: object example: CLOSEUP: 1 CLOSEUP_RATE: 0 ENGAGEMENT: 1 ENGAGEMENT_RATE: 0 IMPRESSION: 240 OUTBOUND_CLICK: 20 OUTBOUND_CLICK_RATE: 0.08 PIN_CLICK: 37 PIN_CLICK_RATE: 0.15 PROFILE_VISIT: 0 QUARTILE_95_PERCENT_VIEW: 8 SAVE: 20 SAVE_RATE: 0.18 VIDEO_10S_VIEW: 2 VIDEO_AVG_WATCH_TIME: 2507.75 VIDEO_MRC_VIEW: 20 VIDEO_START: 29 VIDEO_V50_WATCH_TIME: 10031 additionalProperties: type: number AnalyticsResponse: type: object additionalProperties: $ref: '#/components/schemas/AnalyticsMetricsResponse' AppTypeMultipliers: description: |- This represents a mapping from app type targeting criteria to a bid price adjustment. Multiplier values must be between 0 and 10. A value of 10 represents a 900% increase in bid price (from $1 to $10 for example). A value of 0 will stop distribution for this item on the specified app type in `MAX_BID` ad groups in `CATALOG_SALES` campaigns. All app type multipliers must be set at the same time. If a multiplier is not provided it is assumed to be 1 (no bid adjustment). type: object properties: APP_TYPE: description: App type identifier. allOf: - $ref: '#/components/schemas/TargetingSpecAppType' example: android_mobile: 1.1 android_tablet: 1.1 ipad: 1.2 iphone: 1.2 web: 0.9 web_mobile: 0.8 additionalProperties: type: number format: double nullable: true AppsflyerAudience: description: Request model for creating an AppsFlyer audience type: object properties: container_id: description: The ID of the audience container type: string readOnly: true title: container_id name: description: The name of the audience type: string title: name platform: description: The platform of the audience allOf: - $ref: '#/components/schemas/AppsflyerPlatform' title: platform required: - name - platform - container_id AppsflyerAudienceCreate: description: Resource create operation model. type: object properties: name: description: The name of the audience type: string title: name platform: description: The platform of the audience allOf: - $ref: '#/components/schemas/AppsflyerPlatform' title: platform required: - name - platform AppsflyerAudienceSync: description: Model for AppsFlyerSync type: object AppsflyerAudienceSyncCreate: description: Resource create operation model. type: object properties: container_id: description: The container ID of the audience type: string title: container_id url_adid_sha256: description: The pre-signed URL for SHA256 hashed GAID/IDFA file type: string title: url_adid_sha256 url_email_sha256: description: The pre-signed URL for SHA256 hashed email file type: string title: url_email_sha256 required: - container_id AppsflyerPlatform: description: Platform options for AppsFlyer audience type: string enum: - android - ios AssetAccessRequestError: type: object properties: code: description: Error code associated with the error in requesting asset access. type: integer messages: type: array items: type: string AssetGroupBinding: type: object properties: ad_accounts_ids: description: A list of ad account IDs under the asset group type: array items: $ref: '#/components/schemas/AssetGroupBindingAdAccountsIdsItems' example: - '549755885175' asset_group_description: description: Asset group description type: string example: Asset group that has ad accounts used in Canada nullable: true asset_group_name: description: Asset Group name type: string example: Canada Ad Accounts nullable: true asset_group_types: description: Asset group types type: array items: type: string example: - LOCATION_OR_LANGUAGE catalogs_ids: description: A list of catalog IDs under asset group type: array items: $ref: '#/components/schemas/AssetGroupBindingCatalogsIdsItems' example: - '4836859046874' created_by: description: The data of the user that created the asset group. allOf: - $ref: '#/components/schemas/BusinessAccessUserSummary' created_time: description: The creation time of the asset group type: integer example: 1646767577816 nullable: true id: description: Asset Group ID. type: string example: '666791336903426391' pattern: ^\d+$ owner: description: The data of the business that owns the asset group. allOf: - $ref: '#/components/schemas/BusinessAccessUserSummary' profiles_ids: description: A list of profile IDs under asset group type: array items: $ref: '#/components/schemas/AssetGroupBindingProfilesIdsItems' example: - '630433785246278264' updated_time: description: The last update time of the asset group type: integer example: 1646767577816 nullable: true required: - ad_accounts_ids - asset_group_description - asset_group_name - asset_group_types - catalogs_ids - created_by - created_time - id - owner - profiles_ids - updated_time AssetGroupBindingAdAccountsIdsItems: description: The ID of an ad account in the asset group. type: string pattern: ^\d+$ AssetGroupBindingCatalogsIdsItems: description: The ID of a catalog in an asset group. type: string pattern: ^\d+$ AssetGroupBindingProfilesIdsItems: description: The ID of a profile in an asset group. type: string pattern: ^\d+$ AssetGroupDeleteError: type: object properties: asset_group_id: description: Asset group id of the exception. type: string code: description: Error code associated with the error deleting asset group. type: integer message: description: Error message associated with the error deleting asset group. type: string AssetGroupDeleteExceptions: type: array items: $ref: '#/components/schemas/AssetGroupDeleteError' nullable: true AssetGroupDeletion: type: object properties: deleted_asset_groups: type: array items: type: string readOnly: true exceptions: $ref: '#/components/schemas/AssetGroupDeleteExceptions' readOnly: true AssetGroupDeletionDelete: type: object properties: asset_groups_to_delete: type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' maxItems: 50 minItems: 1 required: - asset_groups_to_delete AssetGroupInput: type: object properties: asset_group: $ref: '#/components/schemas/AssetGroupBinding' AssetGroupInputCreate: type: object properties: asset_group: $ref: '#/components/schemas/AssetGroupBinding' asset_group_description: description: Asset group description. type: string example: Asset groups that has ad accounts shared in Canada asset_group_name: description: Asset Group name. type: string example: Canada Ad Accounts asset_group_types: description: Asset group types. $ref: '#/components/schemas/AssetGroupTypesCreate' required: - asset_group_description - asset_group_name - asset_group_types AssetGroupModification: type: object properties: exceptions: description: A list of errors associated with the asset groups. Will be returned if there is an error. type: array items: $ref: '#/components/schemas/AssetGroupUpdateError' readOnly: true updated_asset_groups: description: A list of successfully edited asset groups. type: array items: $ref: '#/components/schemas/AssetGroupBinding' readOnly: true AssetGroupModificationReadOrUpdate: type: object properties: asset_groups_to_update: description: A list of asset groups and the data that will be used to update them. type: array items: $ref: '#/components/schemas/AssetGroupUpdateItemReadOrUpdateItem' exceptions: description: A list of errors associated with the asset groups. Will be returned if there is an error. type: array items: $ref: '#/components/schemas/AssetGroupUpdateError' readOnly: true updated_asset_groups: description: A list of successfully edited asset groups. type: array items: $ref: '#/components/schemas/AssetGroupBinding' readOnly: true AssetGroupType: description: Asset group type. type: string example: BRAND enum: - BRAND - LOCATION_OR_LANGUAGE - PRODUCT_LINE - OTHER AssetGroupTypesCreate: description: 'Asset Group Types. Note: The asset group types are used for user reference and categorization purposes only and do not impact the functionality of the asset group.' type: array items: $ref: '#/components/schemas/AssetGroupType' example: - BRAND - LOCATION_OR_LANGUAGE - PRODUCT_LINE - OTHER AssetGroupTypesReadOrUpdateItem: description: 'Asset Group Types. Note: The asset group types are used for user reference and categorization purposes only and do not impact the functionality of the asset group.' type: array items: $ref: '#/components/schemas/AssetGroupType' example: - BRAND - LOCATION_OR_LANGUAGE - PRODUCT_LINE - OTHER AssetGroupUpdateError: type: object properties: asset_group_id: type: string code: type: integer message: type: string AssetGroupUpdateItemReadOrUpdateItem: type: object properties: asset_group_id: description: Unique identifier of the asset group to update. type: string title: asset_group_id asset_group_types: description: Asset group types. $ref: '#/components/schemas/AssetGroupTypesReadOrUpdateItem' assets_to_add: description: A list of asset ids to add to the asset group. type: array items: type: string assets_to_remove: description: A list of asset ids to remove from the asset group. type: array items: type: string description: description: Asset group description. type: string title: description name: description: Asset Group name. type: string title: name required: - asset_group_id AssetIdPermissions: description: An object containing the permissions a business member has on the asset. type: object properties: asset_group_info: description: An object containing all the information specific to the provided asset group. This field will be populated only if asset_type equals 'ASSET_GROUP'. allOf: - $ref: '#/components/schemas/AssetGroupBinding' asset_id: description: Unique identifier of a business asset. type: string example: '549755885175' maxLength: 20 minLength: 1 pattern: ^\d+$ asset_type: $ref: '#/components/schemas/AssetTypeResponse' permissions: $ref: '#/components/schemas/PermissionsResponse' required: - asset_id - asset_type - permissions AssetIdToPermissions: description: |- An object mapping asset ids to lists of business permissions. This can be used to setting/requesting permissions on various assets. If accepting an invite or request, this object would be used to grant asset permissions to the member or partner. type: object example: '549760723247': - ANALYST '549760723248': - ANALYST - ADMIN '809944451643622187': - PROFILE_PUBLISHER additionalProperties: $ref: '#/components/schemas/AssetPermissions' AssetIdWithPermissions: description: Asset ID with permission levels. type: object properties: id: description: Unique identifier of a business asset. type: string example: '549755885175' maxLength: 20 minLength: 1 pattern: ^\d+$ permissions: description: Permission levels member or partner has on an asset. type: array items: type: string example: - FINANCE_MANAGER - CATALOGS_MANAGER - AUDIENCE_MANAGER AssetPermissionType: description: Permission aggregation type for asset access type: string example: AGGREGATED_PERMISSION enum: - AGGREGATED_PERMISSION - DIRECT_PERMISSION AssetPermissions: description: The list of permissions held on a single business asset. type: array items: $ref: '#/components/schemas/Permissions' maxItems: 50 minItems: 1 AssetSearchBy: description: The field to search member assets by type: string example: NAME enum: - NAME - ID - NAME_OR_ID - OWNER_NAME - NAME_OR_OWNER AssetSortBy: description: The field to sort member assets by type: string example: NAME enum: - NAME - ID - PERMISSIONS AssetTypeResponse: description: Type of asset. Currently we only support AD_ACCOUNT, PROFILE, ASSET_GROUP and CATALOG. type: string example: AD_ACCOUNT enum: - AD_ACCOUNT - MERCHANT - PROFILE - ASSET_GROUP - PINNER_LIST - CONVERSION_TAG - CATALOG - CONVERSION_SEGMENT AttributionActionType: description: Type of an attributed action. type: string enum: - view - click AttributionMatchType: description: Match type for an attributed event. P for probabilistic, D for deterministic, NA for Not applicable. type: string enum: - P - D - NA AttributionModel: description: Attribution model used to attribute the conversion event. type: string enum: - first_touch - last_touch - multi_touch - mmm AttributionScope: description: Ad event type used for attribution. type: string enum: - view - engagement - click AttributionWindows: type: object properties: click_window_days: type: integer engagement_window_days: type: integer view_window_days: type: integer Audience: type: object properties: ad_account_id: description: Ad account ID. type: string example: '549755885175' pattern: ^\d+$ title: ad_account_id audience_type: description: '[Audience types](/docs/reference/glossary/#Audience Types): ACTALIKE, ENGAGEMENT, CUSTOMER_LIST and VISITOR' allOf: - $ref: '#/components/schemas/PinnerListType' title: audience_type created_by_company_name: description: The company that created this audience. type: string example: Pinterest nullable: true title: created_by_company_name created_timestamp: description: Creation time. Unix timestamp in seconds. type: integer example: 1451431341 nullable: true title: created_time description: description: Audience description. type: string example: People who love making quilts. nullable: true title: description id: description: Audience ID. type: string example: '1234' pattern: ^\d+$ title: id is_nca: description: Whether the audience derives from a new customer acquisition (expanded matching) customer list. Read-only. type: boolean title: is_nca name: description: Audience name. type: string example: ACME Tools title: name rule: $ref: '#/components/schemas/AudienceRule' size: description: Audience size. type: integer example: 1000 nullable: true title: size status: description: Audience status. READY, INITIALIZING, TOO_SMALL - Each audience list needs to have at least 100 people with Pinterest accounts before you can start using it. allOf: - $ref: '#/components/schemas/AudienceStatus' title: status type: description: Always "audience". type: string example: audience title: type updated_timestamp: description: Last update time. Unix timestamp in seconds. type: integer example: 1451431341 nullable: true title: updated_time title: Audience AudienceAccountType: description: Account type filter for audience sharing. type: string enum: - AD_ACCOUNT - BUSINESS_ACCOUNT AudienceCategory: type: object properties: id: description: Interest ID. type: string example: '1234567' title: id index: description: Interest affinity index. type: number example: 1.2 title: index key: description: Interest unique key (same as ID). type: string example: '1234567' title: key name: description: Interest name. type: string example: travel title: name ratio: description: Interest's percent of category's total audience. type: number example: 0.551 title: ratio subcategories: description: Subcategory interest distribution type: array items: $ref: '#/components/schemas/AudienceSubcategory' title: subcategories title: AudienceCategory AudienceDefinition: description: Queryable audience representation. type: object properties: date: description: Generation date type: string example: 2022-10-09 nullable: true title: date scope: type: string example: PARTNER title: AudienceDefinitionScope type: type: string example: IMPRESSION_PLUS_ENGAGEMENT title: AudienceDefinitionType title: AudienceDefinition AudienceDemographicValue: description: Demographic detail for a single audience demographic type: object properties: key: description: Unique key for demographic item type: string example: us title: key name: description: Display name for demographic type: string example: United States title: name ratio: description: Value of demographic item as a percent of total audience type: number example: 0.551 title: ratio example: name: United States key: us ratio: 0.551 title: AudienceDemographicValue AudienceDemographics: description: Audience demographics type: object properties: ages: description: Ages distribution. type: array items: $ref: '#/components/schemas/AudienceDemographicValue' title: ages countries: description: Country area distribution. type: array items: $ref: '#/components/schemas/AudienceDemographicValue' title: countries devices: description: Device usage distribution. type: array items: $ref: '#/components/schemas/AudienceDemographicValue' title: devices genders: description: Gender distribution. type: array items: $ref: '#/components/schemas/AudienceDemographicValue' title: genders metros: description: Geographic metro area distribution. type: array items: $ref: '#/components/schemas/AudienceDemographicValue' title: metros title: AudienceDemographics AudienceInsightType: type: string example: YOUR_TOTAL_AUDIENCE enum: - YOUR_TOTAL_AUDIENCE - YOUR_ENGAGED_AUDIENCE - PINTEREST_TOTAL_AUDIENCE AudienceInsights: description: Audience interests and demographics. type: object properties: categories: description: Category interest distribution type: array items: $ref: '#/components/schemas/AudienceCategory' title: categories date: description: Generation date type: string example: 2022-10-09 nullable: true pattern: ^\d{4}-\d{2}-\d{2}$ title: date demographics: $ref: '#/components/schemas/AudienceDemographics' size: description: Population count. type: integer example: 10000 title: size size_is_upper_bound: description: Indicates whether the audience size has been rounded up to the next highest upper boundary. type: boolean example: true title: size_is_upper_bound type: $ref: '#/components/schemas/AudienceInsightType' title: AudienceInsights AudienceObjectiveType: description: Objective for engagement audience filter. Used only on ad account audience rule; matches baseline ObjectiveType (no VIDEO_VIEW, WEB_SESSIONS). type: string enum: - AWARENESS - CONSIDERATION - WEB_CONVERSION - CATALOG_SALES - VIDEO_COMPLETION - SALES AudienceOwnershipType: description: Filter audiences by ownership type. type: string enum: - OWNED - RECEIVED AudienceRule: description: |- JSON object defining targeted audience users. Example rule formats per audience type: CUSTOMER_LIST: { "customer_list_id": "<customer list ID>"} ACTALIKE: { "seed_id": ["<audience ID>"], "country": "US", "percentage": "10" } (Valid countries include: "US", "CA", and "GB". Percentage should be 1-10. The targeted audience should be this % size across Pinterest.) VISITOR: { "visitor_source_id": ["<conversion tag ID>"], "retention_days": "180", "event_source": {"=": ["web", "mobile"]}, "ingestion_source": {"=": ["tag"]}} (Retention days should be 1-540. Retention applies to specific customers.) ENGAGEMENT: {"engagement_domain": ["www.example.com"], "engager_type": 1} Learn more about [engagement audiences](/docs/work-with-targets-and-audiences/create-audiences/#engagement-audience). type: object properties: ad_account_id: description: Ad account ID. type: string example: '549755885175' pattern: ^\d+$ title: ad_account_id ad_id: description: Ad ID for engagement audience filter. type: array items: type: string example: - '687201361754' title: ad_id campaign_id: description: Campaign ID for engagement audience filter. type: array items: type: string example: - '626744528398' title: campaign_id country: description: 'Valid countries include: "US", "CA", and "GB".' type: string example: US title: country customer_list_id: description: Customer list ID. For CUSTOMER_LIST `audience_type`. type: string example: '5497558859876' pattern: ^\d+$ title: customer_list_id engagement_domain: description: The audience account's verified domain. **Required** for ENGAGEMENT `audience_type`. type: array items: type: string example: - www.somedomain.com title: engagement_domain engagement_type: description: Engagement type enum. Optional for ENGAGEMENT `audience_type`. Supported values are `click`, `save`, `closeup`, `comment` and `like`. All engagements are included if this field is not set. type: string example: click title: engagement_type engager_type: description: Optional for ENGAGEMENT. Engager type value should be 1-2. type: integer example: 1 title: engager_type event: description: A Pinterest tag event. Optional for VISITOR `audience_type`. Possible values are `pagevisit`, `signup`, `checkout`, `viewcategory`, `search`, `addtocart`, `watchvideo`, `lead`, and `custom`. This field also accepts a partner-defined Pinterest tag event. type: string example: checkout title: event event_data: $ref: '#/components/schemas/EventData' event_source: description: "Optional for VISITOR. You can use it as a {'=': [value]}. Supported values are: web, mobile, offline" type: object example: =: - web - mobile title: event_source ingestion_source: description: "Optional for VISITOR. You can use it as a {'=': [value]}. Supported values are: tag, mmp, file_upload, conversions_api" type: object example: =: - tag title: ingestion_source objective_type: description: Objective for engagement audience filter. type: array items: $ref: '#/components/schemas/ObjectiveType' example: - AWARENESS title: objective_type percentage: description: Percentage should be 1-10. The targeted audience should be this % size across Pinterest. type: integer example: 3 title: percentage pin_id: description: 'IDs of engaged organic pins. Optional for ENGAGEMENT `audience_type`. For example, "pin_id:": ["34567"]' type: array items: type: string example: - '34567' title: pin_id prefill: description: Optional for VISITOR `audience_type`. If `true`, the specified rule on existing engagement data is applied to pre-populate the audience. If `false`, the audience is empty at creation time. The default is `true`. type: boolean example: true title: prefill retention_days: description: Number of days a Pinterest user remains in the audience. Optional for ENGAGEMENT and VISITOR `audience_type`. Accepted range is 1-540. Defaults to 180 if not specified. type: integer example: 30 title: retention_days seed_id: description: Audience ID(s). For ACTALIKE `audience_type`. type: array items: type: string example: - '2542620639259' - '2542620639261' title: seed_id url: description: 'Optional for ENGAGEMENT or VISITOR `audience_type`. For ENGAGEMENT, it is the engaged pin''s URL. For VISITOR, you can use it as a string or a {operator: value} object for filtering visitors based on conversion tag event URLs. Supported operators are [ =, !=, contains, not_contains]. Example 1: "url": "http://www.myonlinestore123.com/view_item/shoe" Example 2: "url": {"contains": "/view_item/shoe"}' type: array items: type: string title: url visitor_source_id: description: The conversion tag ID, or the Pinterest tag ID, that you use on your website. For VISITOR `audience_type`. type: string example: '549755885175' pattern: ^\d+$ title: visitor_source_id title: Rule AudienceStatus: description: Audience processing status type: string enum: - INITIALIZING - READY - TOO_SMALL - ELIGIBLE - PERSONAS_INELIGIBLE_SIZE - PERSONAS_INITIALIZING AudienceSubcategory: type: object properties: id: type: string title: id index: type: number title: index key: type: string title: key name: type: string title: name ratio: type: number title: ratio AudienceType: description: Audience type type: string example: ACTALIKE enum: - CUSTOMER_LIST - VISITOR - ENGAGEMENT - ACTALIKE - PERSONA AudienceUpdateOperationType: description: Audience operation type (update or remove). type: string example: UPDATE enum: - UPDATE - REMOVE AuthRespondInviteAction: type: object properties: accept_invite: description: Whether the invite/request is accepted. type: boolean asset_id_to_permissions: $ref: '#/components/schemas/AssetIdToPermissions' required: - accept_invite AuthRespondInvitesBody: description: An object with a list of all the invites the user would like to respond to and the action to take. type: object properties: invites: type: array items: $ref: '#/components/schemas/AuthRespondInvitesBodyItem' maxItems: 100 minItems: 1 required: - invites AuthRespondInvitesBodyItem: type: object properties: action: $ref: '#/components/schemas/AuthRespondInviteAction' invite_id: description: Unique identifier of an invite. type: string maxLength: 25 minLength: 1 pattern: ^\d+$ required: - action - invite_id AutoTargetingEnabled: description: Enable auto-targeting for ad group. Default value is True. Also known as "Pinterest Performance+ targeting". type: boolean AvailabilityFilter: type: object properties: AVAILABILITY: $ref: '#/components/schemas/CatalogsProductGroupMultipleStringCriteria' additionalProperties: false required: - AVAILABILITY title: AVAILABILITY BaseBusinessAssets: description: An object containing the permissions a business has on the asset. type: object properties: asset_group_info: description: An object containing all the information specific to the provided asset group. This field will be populated only if asset_type equals 'ASSET_GROUP'. allOf: - $ref: '#/components/schemas/AssetGroupBinding' asset_id: description: Unique identifier of a business asset. type: string example: '549755885175' maxLength: 20 minLength: 1 pattern: ^\d+$ asset_type: $ref: '#/components/schemas/AssetTypeResponse' permissions: description: Permission levels the requesting business has on an asset. type: array items: type: string example: - FINANCE_MANAGER - CATALOGS_MANAGER - AUDIENCE_MANAGER BaseInviteDataResponse: description: Common invite/request data returned by the business access endpoints. type: object properties: id: description: Unique identifier of the invite/request. type: string example: '383791336903426391' pattern: ^\d+$ invite_data: $ref: '#/components/schemas/InviteDataResponse' is_received_invite: description: Indicates whether the invite/request was received. type: boolean user: description: Metadata for the member/partner that was sent the invite/request. allOf: - $ref: '#/components/schemas/BusinessAccessUserSummary' nullable: true BasePreferredMediaType: type: string enum: - VIDEO - IMAGE BatchOperationStatus: description: The status of the operation performed by the batch type: string example: PROCESSING enum: - PROCESSING - COMPLETED - FAILED BidFloor: description: Bid floor request and response model. type: object properties: bid_floors: description: A list of bid floors in micro currency. For example, [100000, 200000] type: array items: type: integer example: - 100000 - 200000 readOnly: true type: description: Always the string 'bidfloor'. type: string example: bidfloor default: bidfloor readOnly: true example: bid_floors: - 100000 - 200000 type: bidfloor BidFloorCreate: description: Resource create operation model. type: object properties: bid_floor_specs: description: List of bid floor specifications. type: array items: $ref: '#/components/schemas/BidFloorSpec' targeting_spec: description: Ad group targeting specification defining the ad group target audience. allOf: - $ref: '#/components/schemas/TargetingSpecOptimal' required: - bid_floor_specs BidFloorObjectiveType: description: |- Intended result of the campaign. You can only update objectives for draft campaigns. `WEB_SESSIONS` and `VIDEO_VIEW` objectives are deprecated. We recommend using `VIDEO_COMPLETION` as an alternative for the latter. type: string example: AWARENESS enum: - AWARENESS - CONSIDERATION - WEB_CONVERSION - CATALOG_SALES - VIDEO_COMPLETION - SALES BidFloorSpec: description: Bid floor specification for a given campaign configuration. type: object properties: billable_event: description: Ad group billable event type. allOf: - $ref: '#/components/schemas/ActionType' countries: description: List of ISO 3166-1 alpha-2 country codes. type: array items: $ref: '#/components/schemas/Country' creative_type: description: Creative type for the bid floor request. allOf: - $ref: '#/components/schemas/CreativeType' currency: description: Currency for the bid floor value. allOf: - $ref: '#/components/schemas/Currency' objective_type: description: Campaign objective type. allOf: - $ref: '#/components/schemas/BidFloorObjectiveType' optimization_goal_metadata: description: Optimization goal metadata. allOf: - $ref: '#/components/schemas/OptimizationGoalMetadata' required: - billable_event - currency BidOptionsAgeBucketMultipliers: description: |- This represents a mapping from age bucket to a bid price change value. Values represent the change in bid price and can be positive or negative. For percentage changes, a value of 500.0 means a 5% change. For value changes, the amount represents the direct bid adjustment. All age bucket multipliers must be set at the same time. If a multiplier is not provided it is assumed to be 0 (no bid adjustment). The change must still remain between the range of 0 and 10. type: object properties: 18-24: type: number 25-34: type: number 35-44: type: number 45-49: type: number 50-54: type: number 55-64: type: number 65+: type: number BidOptionsAppTypeMultipliers: description: |- This represents a mapping from app type targeting criteria to a bid price change value. Values represent the change in bid price and can be positive or negative. For percentage changes, a value of 500.0 means a 5% change. For value changes, the amount represents the direct bid adjustment. All app type multipliers must be set at the same time. If a multiplier is not provided it is assumed to be 0 (no bid adjustment). The change must still remain between the range of 0 and 10. type: object properties: android_mobile: type: number android_tablet: type: number ipad: type: number iphone: type: number web: type: number web_mobile: type: number BidOptionsAudienceMultipliers: description: |- This represents a mapping from Audience ID to a bid price change value. This is paired with the bid_multipliers schedule type Values represent the change in bid price and can be positive or negative. For percentage changes, a value of 500.0 means a 5% change. For value changes, the amount represents the direct bid adjustment. All audience multipliers must be set at the same time. If a multiplier is not provided it is assumed to be 0 (no bid adjustment). The change must still remain between the range of 0 and 10. type: object properties: audience_id: type: string pattern: ^\d+$ multiplier: type: number required: - audience_id - multiplier BidOptionsGenderMultipliers: description: |- This represents a mapping from gender targeting criteria to a bid price change value. Values represent the change in bid price and can be positive or negative. For percentage changes, a value of 500.0 means a 5% change. For value changes, the amount represents the direct bid adjustment. All gender multipliers must be set at the same time. If a multiplier is not provided it is assumed to be 0 (no bid adjustment). The change must still remain between the range of 0 and 10. type: object properties: female: type: number male: type: number BidOptionsPlacementMultipliers: description: |- This represents a mapping from placement to a bid price change value. Values represent the change in bid price and can be positive or negative. For percentage changes, a value of 500.0 means a 5% change. For value changes, the amount represents the direct bid adjustment. All placement multipliers must be set at the same time. If a multiplier is not provided it is assumed to be 0 (no bid adjustment). The change must still remain between the range of 0 and 10. type: object properties: browse: type: number related_pins: type: number search: type: number BidStrategyType: description: Bid strategy type. For Campaigns with Video Completion objectives, the only supported bid strategy type is AUTOMATIC_BID, also known as "Pinterest Performance+ bidding". type: string enum: - AUTOMATIC_BID - MAX_BID - TARGET_AVG - null nullable: true title: BidStrategyType BillingInvoice: description: A billing invoice in the advertiser account. type: object properties: ad_account_id: description: The ID of the ad account this invoice belongs to type: string pattern: ^\d+$ ad_account_name: description: The name of the ad account this invoice belongs to type: string amount_billed_micro_currency: description: The amount billed in this invoice. Denoted in micro currency type: integer amount_discount_micro_currency: description: The discount in this invoice. Denoted in micro currency type: integer nullable: true amount_net_micro_currency: description: The net amount in this invoice. Denoted in micro currency type: integer nullable: true amount_tax_micro_currency: description: The tax in this invoice. Denoted in micro currency type: integer nullable: true bill_to_country: description: The country of the bill to address type: string billing_period_end_date: description: 'The end date of the billing period. Format: YYYY-MM-DD' type: string format: date billing_period_start_date: description: 'The start date of the billing period. Format: YYYY-MM-DD' type: string format: date currency: $ref: '#/components/schemas/Currency' document_type: description: The type of the document allOf: - $ref: '#/components/schemas/BillingInvoiceDocumentType' id: description: Unique identifier for the billing invoice type: string pattern: ^\d+$ invoice_due_date: description: 'The date the invoice is due. Format: YYYY-MM-DD' type: string format: date payment_terms: description: The payment terms of the invoice type: string example: NET 30 status: description: The status of the invoice example: OPEN allOf: - $ref: '#/components/schemas/BillingInvoiceStatus' BillingInvoiceDocumentType: description: The type of a billing invoice document. type: string enum: - INVOICE - CREDIT_MEMO BillingInvoiceDownloadResponse: type: object properties: download_url: description: The download url for the billing invoice type: string id: description: The billing invoice id type: string title: BillingInvoiceDownloadResponse BillingInvoiceSortField: description: Field by which to sort billing invoices. type: string default: DUE_DATE enum: - DUE_DATE - BILLING_PERIOD - DOCUMENT_TYPE - TOTAL_AMOUNT - INVOICE_NUMBER BillingInvoiceStatus: description: The status of a billing invoice. type: string enum: - OPEN - CLOSED BillingProfileCardType: description: Type of the credit card. type: string enum: - UNKNOWN - VISA - MASTERCARD - AMERICAN_EXPRESS - DISCOVER - ELO BillingProfilePaymentMethodBrand: description: Brand of the payment method. type: string enum: - UNKNOWN - VISA - MASTERCARD - AMERICAN_EXPRESS - DISCOVER - SOFORT - DINERS_CLUB - ELO - CARTE_BANCAIRE BillingProfileStatus: description: Billing profile status type: string enum: - UNSPECIFIED - VALID - INVALID - PENDING - DELETED - SECONDARY - PENDING_SECONDARY BillingProfilesResponse: type: object properties: advertiser_id: description: Advertiser ID of the billing. type: string example: '12312451231' pattern: ^\d+$ billing_type: description: Billing type of the advertiser example: CREDIT_CARD allOf: - $ref: '#/components/schemas/BillingType' card_type: description: Type of the card. example: VISA allOf: - $ref: '#/components/schemas/BillingProfileCardType' id: description: Billing ID. type: string example: '12312451231' pattern: ^\d+$ payment_method_brand: description: Brand of the payment method. example: VISA allOf: - $ref: '#/components/schemas/BillingProfilePaymentMethodBrand' status: description: Status of the billing. example: INVALID allOf: - $ref: '#/components/schemas/BillingProfileStatus' BillingType: description: Advertisers billing type type: string enum: - CREDIT_CARD - INVOICE - INTERNAL - RECURRING - PREPAID Board: description: Board model containing properties related to a Pinterest Board. type: object properties: privacy: description: |2- Privacy setting for a board. Learn more about [secret](https://help.pinterest.com/en/article/secret-boards) boards and [protected](https://help.pinterest.com/en/business/article/protected-boards) boards. **Note:** If you create an ad-only board by setting `is_ads_only` to `true`, the `privacy` settng automatically becomes `PROTECTED`. default: PUBLIC allOf: - $ref: '#/components/schemas/BoardPrivacy' allOf: - $ref: '#/components/schemas/BoardBase' BoardBase: type: object properties: board_pins_modified_at: description: Date and time of last board pins modified. type: string format: date-time readOnly: true collaborator_count: description: Count of collaborators on the board. type: integer example: 17 minimum: 0 readOnly: true created_at: description: Date and time of board creation. type: string format: date-time readOnly: true description: type: string example: My favorite summer recipes nullable: true follower_count: description: Board follower count. type: integer example: 13 minimum: 0 readOnly: true id: type: string example: '549755885175' pattern: ^\d+$ readOnly: true is_ads_only: description: If set to `true`, the board will be ad-only and can store ad-only Pins. type: boolean example: true default: false media: description: Board media. allOf: - $ref: '#/components/schemas/BoardMedia' readOnly: true name: description: |2- Name of the board. **Note:** If you create an ad-only board by setting `is_ads_only` to `true`, the board name automatically becomes "Ad-only Pins". type: string example: Summer recipes owner: allOf: - $ref: '#/components/schemas/BoardOwner' readOnly: true pin_count: description: Count of Pins on the board. type: integer example: 5 minimum: 0 readOnly: true required: - id - name BoardCreate: description: Resource create operation model. type: object properties: description: type: string example: My favorite summer recipes nullable: true is_ads_only: description: If set to `true`, the board will be ad-only and can store ad-only Pins. type: boolean example: true default: false name: description: |2- Name of the board. **Note:** If you create an ad-only board by setting `is_ads_only` to `true`, the board name automatically becomes "Ad-only Pins". type: string example: Summer recipes privacy: description: |2- Privacy setting for a board. Learn more about [secret](https://help.pinterest.com/en/article/secret-boards) boards and [protected](https://help.pinterest.com/en/business/article/protected-boards) boards. **Note:** If you create an ad-only board by setting `is_ads_only` to `true`, the `privacy` settng automatically becomes `PROTECTED`. default: PUBLIC allOf: - $ref: '#/components/schemas/BoardPrivacy' required: - name BoardMedia: type: object properties: image_cover_url: description: Board cover image type: string example: https://i.pinimg.com/400x300/fd/cd/d5/fdcdd5a6d8a80824add0d054125cd957.jpg nullable: true pin_thumbnail_urls: description: Board pin thumbnail urls. type: array items: type: string example: - https://i.pinimg.com/150x150/b4/57/10/b45710f1ede96af55230f4b43935c4af.jpg - https://i.pinimg.com/150x150/dd/ff/46/ddff4616e39c1935cd05738794fa860e.jpg - https://i.pinimg.com/150x150/84/ac/59/84ac59b670ccb5b903dace480a98930c.jpg - https://i.pinimg.com/150x150/4c/54/6f/4c546f521be85e30838fb742bfff6936.jpg title: Board media. BoardOwner: type: object properties: username: type: string readOnly: true title: Board owner containing the username. BoardPrivacy: type: string enum: - PUBLIC - PROTECTED - SECRET BoardPrivacyFilter: type: string enum: - ALL - PUBLIC - PROTECTED - SECRET - PUBLIC_AND_SECRET BoardSection: description: Sections help organize pins within a board. type: object properties: id: type: string example: '549755885175' name: type: string example: Salads maxLength: 180 minLength: 1 required: - name title: Board section BoardSectionCreate: description: Resource create operation model. type: object properties: id: type: string example: '549755885175' name: type: string example: Salads maxLength: 180 minLength: 1 required: - name BoardSectionUpdateWithRequiredBody: description: Resource create or update operation model with required body fields (no OptionalProperties). type: object properties: id: type: string example: '549755885175' name: type: string example: Salads maxLength: 180 minLength: 1 required: - name BoardUpdatePrivacy: type: string enum: - PUBLIC - SECRET BoardWithUpdatePrivacy: type: object properties: privacy: $ref: '#/components/schemas/BoardUpdatePrivacy' allOf: - $ref: '#/components/schemas/BoardBase' BoardWithUpdatePrivacyUpdate: description: Resource create or update operation model. type: object properties: description: type: string example: My favorite summer recipes nullable: true name: description: |2- Name of the board. **Note:** If you create an ad-only board by setting `is_ads_only` to `true`, the board name automatically becomes "Ad-only Pins". type: string example: Summer recipes privacy: $ref: '#/components/schemas/BoardUpdatePrivacy' BookClosed: type: object properties: conversion_metrics_ready: description: Are conversion metrics ready? type: boolean example: false title: conversion_metrics_ready non_conversion_metrics_ready: description: Are non-conversion metrics ready? type: boolean example: false title: non_conversion_metrics_ready required: - conversion_metrics_ready - non_conversion_metrics_ready title: BookClosed BrandAccount: type: object properties: brand_account_id: type: string readOnly: true required: - brand_account_id BrandAccountCreate: description: Resource create operation model. type: object properties: about: description: Brand Account about information type: string country: $ref: '#/components/schemas/Country' name: description: Brand Account name type: string profile_image: $ref: '#/components/schemas/BrandAccountProfileImage' username: description: Brand Account username type: string website: description: Brand Account website type: string required: - country - name - username BrandAccountProfileImage: description: Base64-encoded image media source type: object properties: content_type: type: string enum: - image/jpeg - image/png data: type: string pattern: '[a-zA-Z0-9+\/=]+' required: - content_type - data title: Image Base64 BrandAccountProfileImageUpdate: description: Base64-encoded image media source type: object properties: content_type: type: string enum: - image/jpeg - image/png data: type: string pattern: '[a-zA-Z0-9+\/=]+' title: Image Base64 BrandAccountUpdate: description: Resource create or update operation model. type: object properties: about: description: Brand Account about information type: string country: $ref: '#/components/schemas/Country' name: description: Brand Account name type: string profile_image: $ref: '#/components/schemas/BrandAccountProfileImageUpdate' username: description: Brand Account username type: string website: description: Brand Account website type: string BrandFilter: type: object properties: BRAND: $ref: '#/components/schemas/CatalogsProductGroupMultipleStringCriteria' additionalProperties: false required: - BRAND title: BRAND BudgetDurationType: description: Budget duration type for delivery estimates. type: string enum: - FIXED_DAILY - FLEXIBLE_DAILY - LIFETIME BudgetType: description: Budget type. If DAILY, an ad group's daily spend will not exceed the budget parameter value. If LIFETIME, the end_time parameter is **REQUIRED**, and the ad group spend is spread evenly between the ad group `start_time` and `end_time` range. A CBO campaign automatically generates ad group budgets from its campaign budget to maximize campaign outcome. For CBO campaigns, only "CBO_ADGROUP" is allowed. For WEB_SESSIONS campaigns, only "LIFETIME" is allowed. For update, only draft ad groups may update budget type. type: string example: DAILY enum: - DAILY - LIFETIME - CBO_ADGROUP BulkCampaignDeliveryEstimatesItem: description: Delivery estimate result for a single campaign within a bulk request. type: object properties: adgroup_audience_sizes: description: Range audience sizes for each ad group, in the same order as the ad groups in the request. type: array items: $ref: '#/components/schemas/CampaignPlanningAdGroupAudienceSize' conversion_rate: description: Conversion rate estimate. Used to translate impressions into conversions for oCPM ads, adapted based on the input conversion event and attribution windows. type: number format: float example: 2.32600002288818 conversion_rates: description: Conversion rate estimates. Used to translate impressions into conversions for oCPM ads based on different conversion event and attribution windows settings. type: array items: $ref: '#/components/schemas/CampaignPlanningConversionRate' curves: description: Estimated curves. Each curve will pertain to a single estimation type. type: array items: $ref: '#/components/schemas/CampaignPlanningCurveEstimate' maxItems: 20 derived_metrics: $ref: '#/components/schemas/CampaignDeliveryEstimatesDerivedMetrics' errors: description: Errors encountered during estimation for this campaign. type: array items: $ref: '#/components/schemas/CampaignPlanningResponseError' estimate_id: description: UUID used to track delivery estimates when they are generated as part of a saved campaign. type: string example: db1b0d75-4386-4db3-8a85-e5725d4dff51 max_potential_spend: description: Maximum potential spend estimate. type: integer example: 50000000 BulkCampaignDeliveryEstimatesRequest: description: Bulk campaign delivery estimates request body. Each item describes a single campaign to estimate; results are returned in the same order as the request. type: array items: $ref: '#/components/schemas/CampaignDeliveryEstimatesCampaign' maxItems: 20 minItems: 1 BulkCampaignDeliveryEstimatesResponse: description: Bulk campaign delivery estimates response. type: object properties: data: description: Per-campaign delivery estimate results, in the same order as the request. type: array items: $ref: '#/components/schemas/BulkCampaignDeliveryEstimatesItem' required: - data BulkDownload: description: Ad entities to get in bulk request. type: object properties: request_id: description: ID of the bulk request. type: string example: '2680059592705' readOnly: true example: request_id: '2680059592705' BulkDownloadCampaignFilter: type: object properties: campaign_status: type: array items: $ref: '#/components/schemas/SummaryStatus' end_time: description: Unix UTC timestamp. type: string example: '1622848072' pattern: ^\d+$ name: description: Campaign name type: string example: campaign name objective_type: type: array items: $ref: '#/components/schemas/ConversionObjectiveType' start_time: description: Unix UTC timestamp. type: string example: '1622848072' pattern: ^\d+$ BulkDownloadCreate: description: Resource create operation model. type: object properties: campaign_filter: $ref: '#/components/schemas/BulkDownloadCampaignFilter' entity_ids: description: All entities specified by these IDs as well as their children and grandchildren will be downloaded if the entity type is one of the types requested to be downloaded. type: array items: $ref: '#/components/schemas/BulkDownloadEntityIdsItems' entity_types: description: All entity types specified will be downloaded. Fewer types result in faster downloads. type: array items: $ref: '#/components/schemas/BulkEntityType' example: - CAMPAIGN - AD_GROUP maxItems: 6 minItems: 1 output_format: default: JSON allOf: - $ref: '#/components/schemas/BulkOutputFormat' updated_since: description: Unix UTC timestamp to retrieve all entities that have changed since this time. type: string example: '1622848072' pattern: ^\d+$ BulkDownloadEntityIdsItems: type: string pattern: ^\d+$ BulkEntityType: description: Refers ads entity type. type: string example: AD enum: - CAMPAIGN - AD_GROUP - PRODUCT_GROUP - AD - KEYWORD - LABEL - SCHEDULE - ENTITY_HISTORY BulkJobData: description: Bulk request result data. type: object properties: result_url: description: Presigned s3 file url for the bulk request result. type: string status: $ref: '#/components/schemas/BulkRequestStatus' workload_id: description: Bulk Workload Id. type: integer required: - status BulkOutputFormat: description: Bulk file output format type: string enum: - CSV - JSON BulkReportingJobStatus: description: Possible status for a bulk reporting job type: string example: FINISHED enum: - DOES_NOT_EXIST - FINISHED - IN_PROGRESS - EXPIRED - FAILED - CANCELLED BulkRequestStatus: description: Bulk request status type: string enum: - RUNNING - SUCCEEDED - FAILED BulkUpsertRequest: description: Two set of objects to be managed asyncronusly by bulk. One for creations, one for modifications. type: object properties: create: $ref: '#/components/schemas/BulkUpsertRequestCreate' update: $ref: '#/components/schemas/BulkUpsertRequestUpdate' title: BulkUpsertRequest BulkUpsertRequestCreate: description: Request for creation of entities in bulk. type: object properties: ad_groups: type: array items: $ref: '#/components/schemas/AdGroupCreateRequest' ads: type: array items: $ref: '#/components/schemas/AdCreateRequest' campaigns: type: array items: $ref: '#/components/schemas/CampaignCreateRequest' catalog_product_groups: type: array items: $ref: '#/components/schemas/BulkUpsertRequestCreateCatalogProductGroupsItems' keywords: type: array items: $ref: '#/components/schemas/KeywordsRequest' labels: type: array items: $ref: '#/components/schemas/LabelBulkCreateRequest' product_groups: type: array items: $ref: '#/components/schemas/ProductGroupPromotionCreateRequest' schedules: type: array items: $ref: '#/components/schemas/ScheduleCreateRequest' title: BulkUpsertRequestCreate BulkUpsertRequestCreateCatalogProductGroupsItems: oneOf: - $ref: '#/components/schemas/CatalogsProductGroupCreateRequest' - $ref: '#/components/schemas/CatalogsVerticalProductGroupCreateRequest' BulkUpsertRequestUpdate: description: Request for creation of entities in bulk. type: object properties: ad_groups: type: array items: $ref: '#/components/schemas/AdGroupUpdateRequest' ads: type: array items: $ref: '#/components/schemas/AdUpdateRequest' campaigns: type: array items: $ref: '#/components/schemas/CampaignUpdateRequest' catalog_product_groups: type: array items: $ref: '#/components/schemas/BulkUpsertRequestUpdateCatalogProductGroupsItems' keywords: type: array items: $ref: '#/components/schemas/KeywordUpdateGenerated' labels: type: array items: $ref: '#/components/schemas/LabelBulkUpdateRequest' product_groups: type: array items: $ref: '#/components/schemas/ProductGroupPromotionUpdateRequest' schedules: type: array items: $ref: '#/components/schemas/ScheduleUpdateRequest' title: BulkUpsertRequestUpdate BulkUpsertRequestUpdateCatalogProductGroupsItems: oneOf: - $ref: '#/components/schemas/CatalogsProductGroupUpdateRequest' - $ref: '#/components/schemas/CatalogsVerticalProductGroupUpdateRequest' BulkUpsertResponse: description: ID of the bulk request. type: object properties: request_id: type: string example: 549763856477-1660864560-1407e16a-c586-4add-94df-d0b160bec0ff, 549763856477-1660864560-d0b160bec0ff title: BulkUpsertResponse BusinessAccessRole: description: Permission role for business access. type: string enum: - OWNER - ADMIN - ANALYST - SOS_READER - FINANCE_MANAGER - FINANCE_VIEW - FINANCE_EDIT - AUDIENCE_MANAGER - CAMPAIGN_MANAGER - CATALOGS_MANAGER - RESTRICTED_OWNER - PROFILE_MANAGER - PROFILE_PUBLISHER - RESOURCE_PINNER_LIST_OWNER - RESOURCE_PINNER_LIST_READER - BIZ_PINNER_LIST_SHARER - RESOURCE_CONVERSION_TAGS_READER BusinessAccessUserSummary: description: Metadata of the member/partner that has access to the asset. type: object properties: email: description: Email of the business member/partner. type: string example: business0101@business.com nullable: true id: description: Unique identifier of the business member/partner. type: string example: '549755885175' maxLength: 20 minLength: 1 nullable: true username: description: Username of the business member/partner. type: string example: business0101 nullable: true BusinessAssets: description: An object containing the permissions a business has on the asset. type: object properties: catalog_info: description: An object containing all the information specific to the provided catalog. This field will be populated only if asset_type equals 'CATALOG'. allOf: - $ref: '#/components/schemas/CatalogBinding' allOf: - $ref: '#/components/schemas/BaseBusinessAssets' BusinessInviteOrPartnerId: type: string maxLength: 25 pattern: ^\d+$ BusinessMemberAssetsGetResponse: description: Paginated response for business member assets with total count metadata. type: object properties: bookmark: type: string nullable: true items: type: array items: $ref: '#/components/schemas/AssetIdPermissions' total_data_count: description: Total number of assets matching the query type: integer total_data_count_by_status: description: Breakdown of asset counts by entity status (ad accounts only) allOf: - $ref: '#/components/schemas/TotalCountByEntityStatus' required: - items - total_data_count BusinessMemberAssetsSummary: description: Ad accounts and profiles the business member/partner has access to. type: object properties: ad_accounts: description: List of ad account IDs and respective permission levels. type: array items: $ref: '#/components/schemas/AssetIdWithPermissions' profiles: description: List of profile IDs and respective permission levels. type: array items: $ref: '#/components/schemas/AssetIdWithPermissions' BusinessMemberSortBy: description: The name of field that businesses are sorted by type: string enum: - FULL_NAME - BUSINESS_ROLES - CREATED_TIME BusinessMembersAssetAccessDeleteBody: description: An object with a list of member asset accesses to delete. type: object properties: accesses: description: List of members asset access to be deleted type: array items: $ref: '#/components/schemas/DeleteMemberAssetAccessItem' maxItems: 100 minItems: 1 required: - accesses BusinessMembershipMember: description: A business member identified by `member_id` with their `business_role` in the business. type: object properties: business_role: $ref: '#/components/schemas/BusinessRoleForMembers' member_id: description: Unique identifier of the member. type: string example: '140943737684417' maxLength: 25 pattern: ^\d+$ required: - business_role - member_id BusinessPartnerIdType: type: string maxLength: 22 pattern: ^\d+$ BusinessRoleForInvite: description: |- The business access level to grant member/partner. Note, values are case-sensitive. - EMPLOYEE: Can only view and access assets you assign them to. They cannot see details about other employees, partners, or other assets. - BIZ_ADMIN: Have full control of roles and can add employees and partners as well as grant asset access. - PARTNER: Can only view and access assets you assign them to/or they assign to you. type: string enum: - EMPLOYEE - BIZ_ADMIN - PARTNER BusinessRoleForMembers: description: |- The access level a member has to the business. Values are case-sensitive. - EMPLOYEE: Can only view and access assets you assign to them. They cannot see details about other employees, partners, or other assets. - BIZ_ADMIN: Have full control of roles and can add employees and partners as well as grant asset access. type: string example: BIZ_ADMIN enum: - EMPLOYEE - BIZ_ADMIN BusinessRoleResponse: description: |- The access level a member has to the business. Values are case-sensitive. - EMPLOYEE: Can only view and access assets you assign to them. They cannot see details about other employees, partners, or other assets. - BIZ_ADMIN: Have full control of roles and can add employees and partners as well as grant asset access. type: string example: BIZ_ADMIN BusinessSearchBy: description: The names of fields that business accounts are searched by type: string enum: - FULL_NAME - USERNAME - BUSINESS_ID - EMAIL BusinessToAdAccountSharedAudience: type: object properties: audience_id: description: Unique identifier of an audience example: '2542621871096' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' permissions: description: Permissions granted to the recipients. type: array items: $ref: '#/components/schemas/Role' example: - RESOURCE_PINNER_LIST_READER - RESOURCE_PINNER_LIST_OWNER readOnly: true recipient_account_ids: description: Ad account IDs to share with or revoke from (request) / that received the audience (response). type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' required: - audience_id - recipient_account_ids title: BusinessToAdAccountSharedAudience BusinessToAdAccountSharedAudienceUpdateWithRequiredBody: description: Resource create or update operation model with required body fields (no OptionalProperties). type: object properties: audience_id: description: Unique identifier of an audience example: '2542621871096' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' operation_type: $ref: '#/components/schemas/OperationType' recipient_account_ids: description: Ad account IDs to share with or revoke from (request) / that received the audience (response). type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' required: - audience_id - operation_type - recipient_account_ids BusinessToBusinessSharedAudience: type: object properties: audience_id: description: Unique identifier of an audience example: '2542621871096' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' permissions: description: Permissions granted to the recipients. type: array items: $ref: '#/components/schemas/Role' example: - RESOURCE_PINNER_LIST_READER - RESOURCE_PINNER_LIST_OWNER readOnly: true recipient_business_ids: description: Business IDs to share with or revoke from (request) / that received the audience (response). type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' required: - audience_id - recipient_business_ids title: BusinessToBusinessSharedAudience BusinessToBusinessSharedAudienceUpdateWithRequiredBody: description: Resource create or update operation model with required body fields (no OptionalProperties). type: object properties: audience_id: description: Unique identifier of an audience example: '2542621871096' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' operation_type: $ref: '#/components/schemas/OperationType' recipient_business_ids: description: Business IDs to share with or revoke from (request) / that received the audience (response). type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' required: - audience_id - operation_type - recipient_business_ids Campaign: type: object properties: ad_account_id: description: Campaign's Advertiser ID. type: string example: '549755885175' pattern: ^\d+$ bid_options: description: |- [Restricted](/docs/getting-started/using-beta-and-restricted-features/) Object describing the campaign level bid multipliers. allOf: - $ref: '#/components/schemas/CampaignBidOptions' created_time: description: Campaign creation time. Unix timestamp in seconds. type: integer example: 1432744744 readOnly: true daily_spend_cap: description: |- Note: The default for this field is null, which is treated the same as 0. For campaign budget optimization, a daily or lifetime spend cap must be set, but not both. For ad group level budgets, this field must be 0 or unset. type: integer example: 1432744744 nullable: true default_ad_group_budget_in_micro_currency: description: When transitioning from campaign budget optimization to non-campaign budget optimization, the default_ad_group_budget_in_micro_currency will propagate to each child ad groups daily budget. Unit is micro currency of the associated advertiser account. type: integer example: 0 nullable: true end_time: description: |- Note: To clear this field on update, set the end time to -1. Timestamp in Unix format for scheduling when ads in the campaign stop appearing. Must occur after any end times for child ad groups. If `end_time` is not specified for the campaign, ads run indefinitely unless you update the campaign, changing their status to `paused`. Learn about [scheduling campaigns](/docs/api-features/managing-campaigns/#campaign-scheduling). Different end times can be set for the campaign's child ad groups, but they cannot occur after an `end_time` specified for the campaign. - If your campaign has a child ad group with an end time specified, and if you update that campaign with an `end_time` that is earlier than that of the ad group, the campaign `end_time` will supersede the ad group `end_time`, and the request will not return an error. - In this scenario, if you call [List campaigns](/docs/api/v5/campaigns-list) or [List ad groups](/docs/api/v5/ad_groups-list), the returned campaigns or ad groups are listed with the start and end times that you assigned them, regardless of supersedence. type: integer example: 1644023526 nullable: true id: description: Campaign ID, must be associated with the ad account ID provided in the path. type: string example: '549755885175' maxLength: 18 pattern: ^\d+$ intended_promotion_type: $ref: '#/components/schemas/IntendedPromotionType' is_automated_campaign: description: |- Note: This field is immutable unless the campaign is in draft status. Specifies whether the campaign was created in the automated campaign flow. When using Automated Campaigns, a daily spend cap must be set, and Pinterest Performance+ may not be used. The following objective types are supported: - CONSIDERATION - WEB\_CONVERSION - SALES - LEADS - CATALOG\_SALES type: boolean example: true nullable: true is_campaign_budget_optimization: description: |- Note: This field is immutable unless the campaign is in draft status. Determines if a campaign automatically generates ad-group level budgets given a campaign budget to maximize campaign outcome. When using campaign budgets with a lifetime spend cap, the end time must be provided. type: boolean example: true nullable: true is_carting: description: Whether the campaign contains a carting(where-to-buy link) ad. type: boolean example: true readOnly: true is_flexible_daily_budgets: description: |- Determine if a campaign has setup for flexible daily budgets, also known as "Pinterest Performance+ budgets". Flexible daily budgets are only supported for campaign budget optimization with a daily spend cap, and not a lifetime spend cap. type: boolean example: true nullable: true is_ltv_optimized: description: Specifies whether the campaign is optimized for Lifetime Value (LTV). Only available for eligible advertisers. type: boolean example: true is_performance_plus: description: |- Note: This field is immutable unless the campaign is in draft status. You can only use this feature with the following objectives: - CONSIDERATION - WEB\_CONVERSION - SALES - LEADS - CATALOG\_SALES - APP\_INSTALL Enable Pinterest Performance+ for your campaign. To learn more, see [Pinterest Performance+ Setup](https://developers.pinterest.com/docs/api-features/pinterest-performance-plus-setup/) type: boolean example: true is_top_of_search: description: |- Note: This field is immutable unless the campaign is in draft status. [Restricted](/docs/getting-started/using-beta-and-restricted-features/) Have your ads and content appear at the top of search result lists in Pinterest. You can only use this feature with the following objectives: - CONSIDERATION - WEB\_CONVERSION - SALES - LEADS - CATALOG\_SALES You cannot use this feature with Pinterest Performance+ or Premiere Spotlight enabled. type: boolean example: true lifetime_spend_cap: description: |- Note: The default for this field is null, which is treated the same as 0. For campaign budget optimization, a daily or lifetime spend cap must be set, but not both. For ad group level budgets, this field must be 0 or unset. type: integer example: 1432744744 nullable: true name: description: Campaign name - 255 chars max. type: string example: ACME Tools objective_type: $ref: '#/components/schemas/CampaignObjectiveType' order_line_id: description: |- Note: To clear this field on update, set the order line ID to 0. Order line ID that appears on the invoice. The order line must not be expired. type: string example: '549755885175' nullable: true pattern: ^\d+$ performance_plus_campaign_settings: description: Pinterest Performance+ campaign settings. type: object allOf: - $ref: '#/components/schemas/PerformancePlusCampaignSettings' nullable: true start_time: description: |- Timestamp in Unix format for scheduling when ads in the campaign start to appear. Must precede any start times set for child ad groups. Defaults to current time if no time is specified. Learn about [scheduling campaigns](/docs/api-features/managing-campaigns/#campaign-scheduling). Different start times can be set for the campaign's child ad groups, but they cannot occur before a `start_time` specified for the campaign. - If your campaign has a child ad group with a start time specified, and if you update that campaign with a `start_time` that is later than that of the ad group, the campaign `start_time` will supersede the ad group `start_time`, and the request will not return an error. - In this scenario, if you call [List campaigns](/docs/api/v5/campaigns-list) or [List ad groups](/docs/api/v5/ad_groups-list), the returned campaigns or ad groups are listed with the start and end times that you assigned them, regardless of supersedence. type: integer example: 1580865126 nullable: true status: $ref: '#/components/schemas/EntityStatus' summary_status: allOf: - $ref: '#/components/schemas/SummaryStatus' readOnly: true tracking_urls: type: object allOf: - $ref: '#/components/schemas/TrackingUrls' nullable: true type: description: Always "campaign". type: string example: campaign readOnly: true updated_time: description: UTC timestamp. Last update time. type: integer example: 1432744744 readOnly: true required: - id - objective_type CampaignAdPreview: description: Campaign ad preview record. type: object properties: ad_account_id: description: Advertiser ID for this preview. type: string example: '549755885175' pattern: ^\d+$ readOnly: true ad_group_id: description: Ad group ID to create a preview record for. type: string example: '1234567890' maxLength: 18 pattern: ^\d+$ client_id: description: Client ID that created preview. type: integer readOnly: true expires_at: description: Unix timestamp in milliseconds for preview expiration. type: integer readOnly: true is_active: description: Whether preview link is active. type: boolean readOnly: true pin_id: description: Pin ID for pin promotion preview. type: integer readOnly: true pin_promotion_id: description: Pin promotion ID for this preview. type: integer readOnly: true promoted_product_group_id: description: Promoted product group ID for catalog previews. type: integer readOnly: true url: description: Campaign ad preview URL. type: string example: https://ads.pinterest.com/web-ad-preview/748db198-bd61-4a6f-b756-996c034e8cbb/ readOnly: true user_id: description: User ID that created preview. type: integer readOnly: true uuid: description: Pin promotion preview key. type: string readOnly: true required: - ad_group_id - uuid - url - expires_at - ad_account_id - user_id - is_active title: CampaignAdPreviewData CampaignAdPreviewCreate: description: Resource create operation model. type: object properties: ad_group_id: description: Ad group ID to create a preview record for. type: string example: '1234567890' maxLength: 18 pattern: ^\d+$ required: - ad_group_id CampaignAudienceMultipliers: description: |- This represents a mapping from Audience ID to a bid price adjustment. Multiplier values must be between 0 and 10. A value of 10 represents a 900% increase in bid price (from $1 to $10 for example). A value of 0 will stop distribution for this item on the specified audience in `MAX_BID` ad groups in `CATALOG_SALES` campaigns. All audience multipliers must be set at the same time. If a multiplier is not provided it is assumed to be 1 (no bid adjustment). type: object properties: AUDIENCE_ID: description: Audience ID for the multiplier. type: string pattern: ^\d+$ example: '123': 1.1 '456': 1.2 additionalProperties: $ref: '#/components/schemas/CampaignAudienceMultipliersAdditionalProperties' CampaignAudienceMultipliersAdditionalProperties: description: Bid multiplier value for audience targeting. Must be between 0 and 10. type: number format: double maximum: 10 minimum: 0 CampaignBatchCreateRequest: description: Request body for batch campaign create. type: array items: $ref: '#/components/schemas/CampaignCreateItem' maxItems: 30 minItems: 1 CampaignBatchItem: description: Item in a batch campaign response. type: object properties: data: description: Campaign data on success. allOf: - $ref: '#/components/schemas/CampaignBatchResponseData' exceptions: description: Exceptions on failure. type: array items: $ref: '#/components/schemas/Exception' CampaignBatchResponseData: description: Campaign data in batch response, with all fields optional to support error cases where data may be empty. type: object properties: ad_account_id: description: Campaign's Advertiser ID. type: string example: '549755885175' pattern: ^\d+$ bid_options: description: |- [Restricted](/docs/getting-started/using-beta-and-restricted-features/) Object describing the campaign level bid multipliers. allOf: - $ref: '#/components/schemas/CampaignBidOptions' created_time: description: Campaign creation time. Unix timestamp in seconds. type: integer example: 1432744744 readOnly: true daily_spend_cap: description: |- Note: The default for this field is null, which is treated the same as 0. For campaign budget optimization, a daily or lifetime spend cap must be set, but not both. For ad group level budgets, this field must be 0 or unset. type: integer example: 1432744744 nullable: true default_ad_group_budget_in_micro_currency: description: When transitioning from campaign budget optimization to non-campaign budget optimization, the default_ad_group_budget_in_micro_currency will propagate to each child ad groups daily budget. Unit is micro currency of the associated advertiser account. type: integer example: 0 nullable: true end_time: description: |- Note: To clear this field on update, set the end time to -1. Timestamp in Unix format for scheduling when ads in the campaign stop appearing. Must occur after any end times for child ad groups. If `end_time` is not specified for the campaign, ads run indefinitely unless you update the campaign, changing their status to `paused`. Learn about [scheduling campaigns](/docs/api-features/managing-campaigns/#campaign-scheduling). Different end times can be set for the campaign's child ad groups, but they cannot occur after an `end_time` specified for the campaign. - If your campaign has a child ad group with an end time specified, and if you update that campaign with an `end_time` that is earlier than that of the ad group, the campaign `end_time` will supersede the ad group `end_time`, and the request will not return an error. - In this scenario, if you call [List campaigns](/docs/api/v5/campaigns-list) or [List ad groups](/docs/api/v5/ad_groups-list), the returned campaigns or ad groups are listed with the start and end times that you assigned them, regardless of supersedence. type: integer example: 1644023526 nullable: true id: description: Campaign ID. type: string example: '549755885175' intended_promotion_type: $ref: '#/components/schemas/IntendedPromotionType' is_automated_campaign: description: |- Note: This field is immutable unless the campaign is in draft status. Specifies whether the campaign was created in the automated campaign flow. When using Automated Campaigns, a daily spend cap must be set, and Pinterest Performance+ may not be used. The following objective types are supported: - CONSIDERATION - WEB\_CONVERSION - SALES - LEADS - CATALOG\_SALES type: boolean example: true nullable: true is_campaign_budget_optimization: description: |- Note: This field is immutable unless the campaign is in draft status. Determines if a campaign automatically generates ad-group level budgets given a campaign budget to maximize campaign outcome. When using campaign budgets with a lifetime spend cap, the end time must be provided. type: boolean example: true nullable: true is_carting: description: Whether the campaign contains a carting(where-to-buy link) ad. type: boolean example: true readOnly: true is_flexible_daily_budgets: description: |- Determine if a campaign has setup for flexible daily budgets, also known as "Pinterest Performance+ budgets". Flexible daily budgets are only supported for campaign budget optimization with a daily spend cap, and not a lifetime spend cap. type: boolean example: true nullable: true is_ltv_optimized: description: Specifies whether the campaign is optimized for Lifetime Value (LTV). Only available for eligible advertisers. type: boolean example: true is_performance_plus: description: |- Note: This field is immutable unless the campaign is in draft status. You can only use this feature with the following objectives: - CONSIDERATION - WEB\_CONVERSION - SALES - LEADS - CATALOG\_SALES - APP\_INSTALL Enable Pinterest Performance+ for your campaign. To learn more, see [Pinterest Performance+ Setup](https://developers.pinterest.com/docs/api-features/pinterest-performance-plus-setup/) type: boolean example: true is_top_of_search: description: |- Note: This field is immutable unless the campaign is in draft status. [Restricted](/docs/getting-started/using-beta-and-restricted-features/) Have your ads and content appear at the top of search result lists in Pinterest. You can only use this feature with the following objectives: - CONSIDERATION - WEB\_CONVERSION - SALES - LEADS - CATALOG\_SALES You cannot use this feature with Pinterest Performance+ or Premiere Spotlight enabled. type: boolean example: true lifetime_spend_cap: description: |- Note: The default for this field is null, which is treated the same as 0. For campaign budget optimization, a daily or lifetime spend cap must be set, but not both. For ad group level budgets, this field must be 0 or unset. type: integer example: 1432744744 nullable: true name: description: Campaign name - 255 chars max. type: string example: ACME Tools objective_type: $ref: '#/components/schemas/CampaignObjectiveType' order_line_id: description: |- Note: To clear this field on update, set the order line ID to 0. Order line ID that appears on the invoice. The order line must not be expired. type: string example: '549755885175' nullable: true pattern: ^\d+$ performance_plus_campaign_settings: description: Pinterest Performance+ campaign settings. type: object allOf: - $ref: '#/components/schemas/PerformancePlusCampaignSettings' nullable: true start_time: description: |- Timestamp in Unix format for scheduling when ads in the campaign start to appear. Must precede any start times set for child ad groups. Defaults to current time if no time is specified. Learn about [scheduling campaigns](/docs/api-features/managing-campaigns/#campaign-scheduling). Different start times can be set for the campaign's child ad groups, but they cannot occur before a `start_time` specified for the campaign. - If your campaign has a child ad group with a start time specified, and if you update that campaign with a `start_time` that is later than that of the ad group, the campaign `start_time` will supersede the ad group `start_time`, and the request will not return an error. - In this scenario, if you call [List campaigns](/docs/api/v5/campaigns-list) or [List ad groups](/docs/api/v5/ad_groups-list), the returned campaigns or ad groups are listed with the start and end times that you assigned them, regardless of supersedence. type: integer example: 1580865126 nullable: true status: allOf: - $ref: '#/components/schemas/NullableEntityStatus' nullable: true summary_status: allOf: - $ref: '#/components/schemas/SummaryStatus' readOnly: true tracking_urls: type: object allOf: - $ref: '#/components/schemas/TrackingUrls' nullable: true type: description: Always "campaign". type: string example: campaign readOnly: true updated_time: description: UTC timestamp. Last update time. type: integer example: 1432744744 readOnly: true CampaignBatchUpdateItem: description: Single campaign update item with update-specific bid options. type: object properties: ad_account_id: description: Setting this field does nothing. The ad account ID gets set from the path parameter. type: string example: '549755885175' deprecated: true pattern: ^\d+$ app_id: description: |- [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) The store ID of the mobile app for `APP_INSTALL` campaigns. type: string example: '429047995' app_platform: description: |- [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Platform of the mobile app for `APP_INSTALL` campaigns. example: IOS allOf: - $ref: '#/components/schemas/MobileAppPlatform' bid_options: description: Object describing an update to the campaign level bid multipliers. allOf: - $ref: '#/components/schemas/CampaignBidOptionsUpdate' daily_spend_cap: description: |- Note: The default for this field is null, which is treated the same as 0. For campaign budget optimization, a daily or lifetime spend cap must be set, but not both. For ad group level budgets, this field must be 0 or unset. type: integer example: 1432744744 nullable: true default_ad_group_budget_in_micro_currency: description: Setting this field does nothing. type: integer example: 0 deprecated: true nullable: true end_time: description: |- Note: To clear this field on update, set the end time to -1. Timestamp in Unix format for scheduling when ads in the campaign stop appearing. Must occur after any end times for child ad groups. If `end_time` is not specified for the campaign, ads run indefinitely unless you update the campaign, changing their status to `paused`. Learn about [scheduling campaigns](/docs/api-features/managing-campaigns/#campaign-scheduling). Different end times can be set for the campaign's child ad groups, but they cannot occur after an `end_time` specified for the campaign. - If your campaign has a child ad group with an end time specified, and if you update that campaign with an `end_time` that is earlier than that of the ad group, the campaign `end_time` will supersede the ad group `end_time`, and the request will not return an error. - In this scenario, if you call [List campaigns](/docs/api/v5/campaigns-list) or [List ad groups](/docs/api/v5/ad_groups-list), the returned campaigns or ad groups are listed with the start and end times that you assigned them, regardless of supersedence. type: integer example: 1644023526 nullable: true id: description: Campaign ID, must be associated with the ad account ID provided in the path. type: string example: '549755885175' maxLength: 18 pattern: ^\d+$ intended_promotion_type: $ref: '#/components/schemas/IntendedPromotionType' is_automated_campaign: description: |- Note: This field is immutable unless the campaign is in draft status. Specifies whether the campaign was created in the automated campaign flow. When using Automated Campaigns, a daily spend cap must be set, and Pinterest Performance+ may not be used. The following objective types are supported: - CONSIDERATION - WEB\_CONVERSION - SALES - LEADS - CATALOG\_SALES type: boolean example: true nullable: true is_campaign_budget_optimization: description: |- Note: This field is immutable unless the campaign is in draft status. Determines if a campaign automatically generates ad-group level budgets given a campaign budget to maximize campaign outcome. When using campaign budgets with a lifetime spend cap, the end time must be provided. type: boolean example: true nullable: true is_flexible_daily_budgets: description: |- Determine if a campaign has setup for flexible daily budgets, also known as "Pinterest Performance+ budgets". Flexible daily budgets are only supported for campaign budget optimization with a daily spend cap, and not a lifetime spend cap. type: boolean example: true nullable: true is_ltv_optimized: description: Specifies whether the campaign is optimized for Lifetime Value (LTV). Only available for eligible advertisers. type: boolean example: true is_performance_plus: description: |- Note: This field is immutable unless the campaign is in draft status. You can only use this feature with the following objectives: - CONSIDERATION - WEB\_CONVERSION - SALES - LEADS - CATALOG\_SALES - APP\_INSTALL Enable Pinterest Performance+ for your campaign. To learn more, see [Pinterest Performance+ Setup](https://developers.pinterest.com/docs/api-features/pinterest-performance-plus-setup/) type: boolean example: true is_top_of_search: description: |- Note: This field is immutable unless the campaign is in draft status. [Restricted](/docs/getting-started/using-beta-and-restricted-features/) Have your ads and content appear at the top of search result lists in Pinterest. You can only use this feature with the following objectives: - CONSIDERATION - WEB\_CONVERSION - SALES - LEADS - CATALOG\_SALES You cannot use this feature with Pinterest Performance+ or Premiere Spotlight enabled. type: boolean example: true lifetime_spend_cap: description: |- Note: The default for this field is null, which is treated the same as 0. For campaign budget optimization, a daily or lifetime spend cap must be set, but not both. For ad group level budgets, this field must be 0 or unset. type: integer example: 1432744744 nullable: true name: description: Campaign name - 255 chars max. type: string example: ACME Tools objective_type: $ref: '#/components/schemas/ConversionObjectiveType' order_line_id: description: |- Note: To clear this field on update, set the order line ID to 0. Order line ID that appears on the invoice. The order line must not be expired. type: string example: '549755885175' nullable: true pattern: ^\d+$ performance_plus_campaign_settings: description: Pinterest Performance+ campaign settings. type: object allOf: - $ref: '#/components/schemas/PerformancePlusCampaignSettings' nullable: true start_time: description: |- Timestamp in Unix format for scheduling when ads in the campaign start to appear. Must precede any start times set for child ad groups. Defaults to current time if no time is specified. Learn about [scheduling campaigns](/docs/api-features/managing-campaigns/#campaign-scheduling). Different start times can be set for the campaign's child ad groups, but they cannot occur before a `start_time` specified for the campaign. - If your campaign has a child ad group with a start time specified, and if you update that campaign with a `start_time` that is later than that of the ad group, the campaign `start_time` will supersede the ad group `start_time`, and the request will not return an error. - In this scenario, if you call [List campaigns](/docs/api/v5/campaigns-list) or [List ad groups](/docs/api/v5/ad_groups-list), the returned campaigns or ad groups are listed with the start and end times that you assigned them, regardless of supersedence. type: integer example: 1580865126 nullable: true status: $ref: '#/components/schemas/EntityStatus' tracking_urls: type: object allOf: - $ref: '#/components/schemas/TrackingUrls' nullable: true required: - id CampaignBatchUpdateRequest: description: Request body for batch campaign update. type: array items: $ref: '#/components/schemas/CampaignBatchUpdateItem' maxItems: 30 minItems: 1 CampaignBatchWriteResponseModel: description: Response model for batch campaign write operations. type: object properties: items: type: array items: $ref: '#/components/schemas/CampaignBatchItem' required: - items CampaignBidOptions: description: Object describing the campaign level bid multipliers. type: object properties: age_bucket_multipliers: description: Age bucket multipliers for bid adjustments. allOf: - $ref: '#/components/schemas/AgeBucketMultipliers' app_type_multipliers: description: App type multipliers for bid adjustments. allOf: - $ref: '#/components/schemas/AppTypeMultipliers' audience_multipliers: description: Audience multipliers for bid adjustments. allOf: - $ref: '#/components/schemas/CampaignAudienceMultipliers' freq_bid_multiplier_time_window: description: The time window for frequency bid multipliers. allOf: - $ref: '#/components/schemas/FreqBidMultiplierTimeWindow' nullable: true frequency_multipliers: description: Frequency multipliers for bid adjustments. type: object allOf: - $ref: '#/components/schemas/FrequencyMultipliers' nullable: true gender_multipliers: description: Gender multipliers for bid adjustments. allOf: - $ref: '#/components/schemas/GenderMultipliers' placement_multipliers: description: Placement multipliers for bid adjustments. allOf: - $ref: '#/components/schemas/PlacementMultipliers' nullable: true CampaignBidOptionsCreate: description: Object describing the campaign level bid multipliers for create operations. type: object properties: age_bucket_multipliers: description: Age bucket multipliers for bid adjustments. allOf: - $ref: '#/components/schemas/AgeBucketMultipliers' app_type_multipliers: description: App type multipliers for bid adjustments. allOf: - $ref: '#/components/schemas/AppTypeMultipliers' audience_multipliers: description: Audience multipliers for bid adjustments. allOf: - $ref: '#/components/schemas/CampaignAudienceMultipliers' freq_bid_multiplier_time_window: description: The time window for frequency bid multipliers. allOf: - $ref: '#/components/schemas/FreqBidMultiplierTimeWindow' nullable: true frequency_multipliers: description: Frequency multipliers for bid adjustments. type: object allOf: - $ref: '#/components/schemas/FrequencyMultipliers' nullable: true gender_multipliers: description: Gender multipliers for bid adjustments. allOf: - $ref: '#/components/schemas/GenderMultipliers' placement_multipliers: description: Placement multipliers for bid adjustments. allOf: - $ref: '#/components/schemas/PlacementMultipliers' nullable: true CampaignBidOptionsUpdate: description: Object describing an update to the campaign level bid multipliers. type: object properties: age_bucket_multipliers: description: Age bucket multipliers for bid adjustments. allOf: - $ref: '#/components/schemas/AgeBucketMultipliers' app_type_multipliers: description: App type multipliers for bid adjustments. allOf: - $ref: '#/components/schemas/AppTypeMultipliers' audience_multipliers: description: Audience multipliers for bid adjustments. allOf: - $ref: '#/components/schemas/CampaignAudienceMultipliers' freq_bid_multiplier_time_window: description: The time window for frequency bid multipliers. allOf: - $ref: '#/components/schemas/FreqBidMultiplierTimeWindow' nullable: true frequency_multipliers: description: Frequency multipliers for bid adjustments. type: object allOf: - $ref: '#/components/schemas/FrequencyMultipliers' nullable: true gender_multipliers: description: Gender multipliers for bid adjustments. allOf: - $ref: '#/components/schemas/GenderMultipliers' placement_multipliers: description: Placement multipliers for bid adjustments. allOf: - $ref: '#/components/schemas/PlacementMultipliers' update_mask: description: List of fields to update. Only the fields in the list will be updated. type: array items: $ref: '#/components/schemas/CampaignBidOptionsUpdateMaskItems' nullable: true required: - update_mask CampaignBidOptionsUpdateMaskItems: description: Fields that can be updated in campaign bid options. type: string enum: - AUDIENCE - APP_TYPE - PLACEMENT - GENDER - AGE_BUCKET - FREQUENCY CampaignCreateItem: description: Single campaign create item with create-specific defaults. type: object properties: ad_account_id: description: Setting this field does nothing. The ad account ID gets set from the path parameter. type: string example: '549755885175' deprecated: true pattern: ^\d+$ app_id: description: |- [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) The store ID of the mobile app for `APP_INSTALL` campaigns. type: string example: '429047995' app_platform: description: |- [Closed beta](/docs/getting-started/using-beta-and-restricted-features/) Platform of the mobile app for `APP_INSTALL` campaigns. example: IOS allOf: - $ref: '#/components/schemas/MobileAppPlatform' bid_options: description: |- [Restricted](/docs/getting-started/using-beta-and-restricted-features/) Object describing the campaign level bid multipliers. allOf: - $ref: '#/components/schemas/CampaignBidOptions' daily_spend_cap: description: |- Note: The default for this field is null, which is treated the same as 0. For campaign budget optimization, a daily or lifetime spend cap must be set, but not both. For ad group level budgets, this field must be 0 or unset. type: integer example: 1432744744 nullable: true default_ad_group_budget_in_micro_currency: description: Setting this field does nothing. type: integer example: 0 deprecated: true nullable: true end_time: description: |- Note: To clear this field on update, set the end time to -1. Timestamp in Unix format for scheduling when ads in the campaign stop appearing. Must occur after any end times for child ad groups. If `end_time` is not specified for the campaign, ads run indefinitely unless you update the campaign, changing their status to `paused`. Learn about [scheduling campaigns](/docs/api-features/managing-campaigns/#campaign-scheduling). Different end times can be set for the campaign's child ad groups, but they cannot occur after an `end_time` specified for the campaign. - If your campaign has a child ad group with an end time specified, and if you update that campaign with an `end_time` that is earlier than that of the ad group, the campaign `end_time` will supersede the ad group `end_time`, and the request will not return an error. - In this scenario, if you call [List campaigns](/docs/api/v5/campaigns-list) or [List ad groups](/docs/api/v5/ad_groups-list), the returned campaigns or ad groups are listed with the start and end times that you assigned them, regardless of supersedence. type: integer example: 1644023526 nullable: true intended_promotion_type: $ref: '#/components/schemas/IntendedPromotionType' is_automated_campaign: description: |- Note: This field is immutable unless the campaign is in draft status. Specifies whether the campaign was created in the automated campaign flow. When using Automated Campaigns, a daily spend cap must be set, and Pinterest Performance+ may not be used. The following objective types are supported: - CONSIDERATION - WEB\_CONVERSION - SALES - LEADS - CATALOG\_SALES type: boolean example: true default: false nullable: true is_campaign_budget_optimization: description: |- Note: This field is immutable unless the campaign is in draft status. Determines if a campaign automatically generates ad-group level budgets given a campaign budget to maximize campaign outcome. When using campaign budgets with a lifetime spend cap, the end time must be provided. type: boolean example: true default: true nullable: true is_flexible_daily_budgets: description: |- Determine if a campaign has setup for flexible daily budgets, also known as "Pinterest Performance+ budgets". Flexible daily budgets are only supported for campaign budget optimization with a daily spend cap, and not a lifetime spend cap. type: boolean example: true default: false nullable: true is_ltv_optimized: description: Specifies whether the campaign is optimized for Lifetime Value (LTV). Only available for eligible advertisers. type: boolean example: true is_performance_plus: description: |- Note: This field is immutable unless the campaign is in draft status. You can only use this feature with the following objectives: - CONSIDERATION - WEB\_CONVERSION - SALES - LEADS - CATALOG\_SALES - APP\_INSTALL Enable Pinterest Performance+ for your campaign. To learn more, see [Pinterest Performance+ Setup](https://developers.pinterest.com/docs/api-features/pinterest-performance-plus-setup/) type: boolean example: true default: false is_top_of_search: description: |- Note: This field is immutable unless the campaign is in draft status. [Restricted](/docs/getting-started/using-beta-and-restricted-features/) Have your ads and content appear at the top of search result lists in Pinterest. You can only use this feature with the following objectives: - CONSIDERATION - WEB\_CONVERSION - SALES - LEADS - CATALOG\_SALES You cannot use this feature with Pinterest Performance+ or Premiere Spotlight enabled. type: boolean example: true default: false lifetime_spend_cap: description: |- Note: The default for this field is null, which is treated the same as 0. For campaign budget optimization, a daily or lifetime spend cap must be set, but not both. For ad group level budgets, this field must be 0 or unset. type: integer example: 1432744744 nullable: true name: description: Campaign name - 255 chars max. type: string example: ACME Tools objective_type: $ref: '#/components/schemas/ConversionObjectiveType' order_line_id: description: |- Note: To clear this field on update, set the order line ID to 0. Order line ID that appears on the invoice. The order line must not be expired. type: string example: '549755885175' nullable: true pattern: ^\d+$ start_time: description: |- Timestamp in Unix format for scheduling when ads in the campaign start to appear. Must precede any start times set for child ad groups. Defaults to current time if no time is specified. Learn about [scheduling campaigns](/docs/api-features/managing-campaigns/#campaign-scheduling). Different start times can be set for the campaign's child ad groups, but they cannot occur before a `start_time` specified for the campaign. - If your campaign has a child ad group with a start time specified, and if you update that campaign with a `start_time` that is later than that of the ad group, the campaign `start_time` will supersede the ad group `start_time`, and the request will not return an error. - In this scenario, if you call [List campaigns](/docs/api/v5/campaigns-list) or [List ad groups](/docs/api/v5/ad_groups-list), the returned campaigns or ad groups are listed with the start and end times that you assigned them, regardless of supersedence. type: integer example: 1580865126 nullable: true status: default: ACTIVE allOf: - $ref: '#/components/schemas/EntityStatus' tracking_urls: type: object allOf: - $ref: '#/components/schemas/TrackingUrls' nullable: true required: - name - objective_type CampaignCreateRequest: type: object properties: ad_account_id: description: Campaign's Advertiser ID. If you want to create a campaign in a Business Account shared account you need to specify the Business Access advertiser ID in both the query path param as well as the request body schema. type: string example: '549755885175' pattern: ^\d+$ daily_spend_cap: description: Campaign daily spending cap. Required for Campaign Budget Optimization (CBO) campaigns. This and "lifetime_spend_cap" cannot be set at the same time. type: integer example: 1432744744 nullable: true default_ad_group_budget_in_micro_currency: description: When transitioning from campaign budget optimization to non-campaign budget optimization, the default_ad_group_budget_in_micro_currency will propagate to each child ad groups daily budget. Unit is micro currency of the associated advertiser account. type: integer nullable: true end_time: description: |- Timestamp in Unix format for scheduling when ads in the campaign stop appearing. Must occur after any end times for child ad groups. If `end_time` is not specified for the campaign, ads run indefinitely unless you update the campaign, changing their status to `paused`. Learn about scheduling campaigns. Different end times can be set for the campaign's child ad groups, but they cannot occur after an `end_time` specified for the campaign. - If your campaign has a child ad group with an end time specified, and if you update that campaign with an `end_time` that is earlier than that of the ad group, the campaign `end_time` will supersede the ad group `end_time`, and the request will not return an error. - In this scenario, if you call List campaigns or List ad groups, the returned campaigns or ad groups are listed with the start and end times that you assigned them, regardless of supersedence. type: integer example: 1644023526 nullable: true is_automated_campaign: $ref: '#/components/schemas/CampaignIsAutomatedCampaign' is_campaign_budget_optimization: $ref: '#/components/schemas/CampaignIsCampaignBudgetOptimization' is_flexible_daily_budgets: $ref: '#/components/schemas/CampaignIsFlexibleDailyBudgets' lifetime_spend_cap: description: Campaign total spending cap. Required for Campaign Budget Optimization (CBO) campaigns. This and "daily_spend_cap" cannot be set at the same time. type: integer example: 1432744744 nullable: true name: description: Campaign name. type: string example: ACME Tools order_line_id: description: Order line ID that appears on the invoice. type: string example: '549755885175' nullable: true pattern: ^\d+$ start_time: description: |- Timestamp in Unix format for scheduling when ads in the campaign start to appear. Must precede any start times set for child ad groups. Defaults to current time if no time is specified. Learn about scheduling campaigns. Different start times can be set for the campaign's child ad groups, but they cannot occur before a `start_time` specified for the campaign. - If your campaign has a child ad group with a start time specified, and if you update that campaign with a `start_time` that is later than that of the ad group, the campaign `start_time` will supersede the ad group `start_time`, and the request will not return an error. - In this scenario, if you call List campaigns or List ad groups, the returned campaigns or ad groups are listed with the start and end times that you assigned them, regardless of supersedence. type: integer example: 1580865126 nullable: true status: $ref: '#/components/schemas/EntityStatus' tracking_urls: type: object allOf: - $ref: '#/components/schemas/TrackingUrls' nullable: true allOf: - type: object required: - ad_account_id - name - objective_type properties: bid_options: $ref: '#/components/schemas/CampaignBidOptionsCreate' intended_promotion_type: $ref: '#/components/schemas/IntendedPromotionType' is_automated_campaign: default: false allOf: - $ref: '#/components/schemas/CampaignIsAutomatedCampaign' is_campaign_budget_optimization: default: true allOf: - $ref: '#/components/schemas/CampaignIsCampaignBudgetOptimization' is_flexible_daily_budgets: default: false allOf: - $ref: '#/components/schemas/CampaignIsFlexibleDailyBudgets' is_ltv_optimized: description: Specifies whether the campaign is optimized for Lifetime Value (LTV). Only available for eligible advertisers. type: boolean is_performance_plus: description: Enable Pinterest Performance+ for your campaign. To learn more, see Pinterest Performance+ Setup. type: boolean default: false is_top_of_search: description: |- Restricted Have your ads and content appear at the top of search result lists in Pinterest. You can only use this feature with the following objectives: `CONSIDERATION` `WEB_CONVERSION` `CATALOG_SALES` You cannot use this feature with Pinterest Performance+ or Premiere Spotlight enabled. You cannot change your `true` or `false` selection of this campaign if you update it. type: boolean default: false objective_type: $ref: '#/components/schemas/ObjectiveType' status: default: ACTIVE allOf: - $ref: '#/components/schemas/EntityStatus' title: CampaignCreateRequest CampaignCreateRequestAllOf1: type: object properties: bid_options: $ref: '#/components/schemas/CampaignBidOptionsCreate' intended_promotion_type: $ref: '#/components/schemas/IntendedPromotionType' is_automated_campaign: default: false allOf: - $ref: '#/components/schemas/CampaignIsAutomatedCampaign' is_campaign_budget_optimization: default: true allOf: - $ref: '#/components/schemas/CampaignIsCampaignBudgetOptimization' is_flexible_daily_budgets: default: false allOf: - $ref: '#/components/schemas/CampaignIsFlexibleDailyBudgets' is_ltv_optimized: description: Specifies whether the campaign is optimized for Lifetime Value (LTV). Only available for eligible advertisers. type: boolean is_performance_plus: description: Enable Pinterest Performance+ for your campaign. To learn more, see Pinterest Performance+ Setup. type: boolean default: false is_top_of_search: description: |- Restricted Have your ads and content appear at the top of search result lists in Pinterest. You can only use this feature with the following objectives: `CONSIDERATION` `WEB_CONVERSION` `CATALOG_SALES` You cannot use this feature with Pinterest Performance+ or Premiere Spotlight enabled. You cannot change your `true` or `false` selection of this campaign if you update it. type: boolean default: false objective_type: $ref: '#/components/schemas/ObjectiveType' status: default: ACTIVE allOf: - $ref: '#/components/schemas/EntityStatus' required: - objective_type CampaignDeliveryEstimatesCampaign: description: Campaign configuration for delivery estimates. type: object properties: ad_groups: type: array items: $ref: '#/components/schemas/AdGroupDeliveryEstimates' maxItems: 10 minItems: 1 budget_duration_type: description: Duration type of the budget example: FIXED_DAILY allOf: - $ref: '#/components/schemas/BudgetDurationType' daily_spend_cap: description: Campaign daily spend cap. When the budget_duration_type is FIXED_DAILY or FLEXIBLE_DAILY, this field is required. type: integer example: 50000000 end_date: description: End date of the date range for an ad campaign, pattern YYYY-MM-DD. Required when budget_duration_type is LIFETIME. type: string pattern: ^\d{4}-\d{2}-\d{2}$ lifetime_spend_cap: description: Campaign total spending cap. When the budget_duration_type is LIFETIME, this field is required. The end date field is also required for lifetime spending. type: integer example: 500000000 objective_type: $ref: '#/components/schemas/DeliveryEstimateObjectiveType' start_date: description: Start date of the date range for an ad campaign, pattern YYYY-MM-DD. type: string pattern: ^\d{4}-\d{2}-\d{2}$ required: - ad_groups - budget_duration_type - objective_type - start_date CampaignDeliveryEstimatesCampaignRequest: description: Campaign delivery estimates request body. type: array items: $ref: '#/components/schemas/CampaignDeliveryEstimatesCampaign' maxItems: 1 minItems: 1 CampaignDeliveryEstimatesDerivedMetrics: description: Derived metrics for an ad campaign. type: object properties: cpc: description: Estimated cost per click. type: number format: float example: 0.56 cpc_lower: description: Lower estimate of the cost per click. type: number format: float example: 0.47 cpc_upper: description: Upper estimate of the cost per click. type: number format: float example: 0.65 cpm: description: Estimated cost per thousand impressions. type: number format: float example: 10 cpm_lower: description: Lower estimate of cost per thousand impressions. type: number format: float example: 8 cpm_upper: description: Upper estimate of cost per thousand impressions. type: number format: float example: 12 lifetime_frequency: description: Estimated lifetime frequency. type: number format: float lifetime_frequency_lower: description: Lower estimate of lifetime frequency. type: number format: float lifetime_frequency_upper: description: Upper estimate of lifetime frequency. type: number format: float lifetime_impression: description: Estimated lifetime impressions. type: number format: float lifetime_impression_lower: description: Lower estimate of lifetime impressions. type: number format: float lifetime_impression_upper: description: Upper estimate of lifetime impressions. type: number format: float lifetime_reach: description: Estimated lifetime reach. type: number format: float lifetime_reach_lower: description: Lower estimate of lifetime reach. type: number format: float lifetime_reach_upper: description: Upper estimate of lifetime reach. type: number format: float weekly_click: description: Estimated weekly clicks. type: number format: float example: 1000 weekly_click_lower: description: Lower estimate of weekly clicks. type: number format: float example: 800 weekly_click_upper: description: Upper estimate of weekly clicks. type: number format: float example: 1200 weekly_frequency: description: Estimated weekly frequency. type: number format: float example: 3 weekly_frequency_lower: description: Lower estimate of weekly frequency. type: number format: float example: 2.5 weekly_frequency_upper: description: Upper estimate of weekly frequency. type: number format: float example: 3.5 weekly_impression: description: Estimated weekly impressions. type: number format: float example: 400000 weekly_impression_lower: description: Lower estimate of weekly impressions. type: number format: float example: 350000 weekly_impression_upper: description: Upper estimate of weekly impressions. type: number format: float example: 450000 weekly_reach: description: Estimated weekly reach. type: number format: float example: 102074.85050444445 weekly_reach_lower: description: Lower estimate of weekly reach. type: number format: float example: 90000 weekly_reach_upper: description: Upper estimate of weekly reach. type: number format: float example: 150000 CampaignDeliveryEstimatesResponse: description: Delivery estimates response for a campaign. type: object properties: curves: description: Estimated curves. Each curve will pertain to a single estimation type. type: array items: $ref: '#/components/schemas/CampaignPlanningCurveEstimate' maxItems: 20 derived_metrics: $ref: '#/components/schemas/CampaignDeliveryEstimatesDerivedMetrics' max_potential_spend: description: Maximum potential spend estimate. type: integer example: 50000000 CampaignIdRequiredType: type: string maxLength: 18 pattern: ^\d+$ CampaignIdType: type: string maxLength: 18 pattern: ^\d+$ CampaignIsAutomatedCampaign: description: |- Note: This field is immutable unless the campaign is in draft status. Specifies whether the campaign was created in the automated campaign flow. When using Automated Campaigns, a daily spend cap must be set, and Pinterest Performance+ may not be used. The following objective types are supported: - CONSIDERATION - WEB\_CONVERSION - SALES - CATALOG\_SALES type: boolean nullable: true CampaignIsCampaignBudgetOptimization: description: |- Note: This field is immutable unless the campaign is in draft status. Determines if a campaign automatically generates ad-group level budgets given a campaign budget to maximize campaign outcome. When using campaign budgets with a lifetime spend cap, the end time must be provided. type: boolean nullable: true CampaignIsFlexibleDailyBudgets: description: |- Determine if a campaign has setup for flexible daily budgets, also known as "Pinterest Performance+ budgets". Flexible daily budgets are only supported for campaign budget optimization with a daily spend cap, and not a lifetime spend cap. type: boolean nullable: true CampaignObjectiveType: description: Campaign objective type. If set as one of ["AWARENESS", "CONSIDERATION", "WEB_CONVERSION", "CATALOG_SALES", "VIDEO_COMPLETION", "CTV_CONSIDERATION"] the campaign is considered as a Campaign Budget Optimization (CBO) campaign, meaning budget needs to be set at the campaign level rather than at the ad group level. ["WEB_SESSIONS"] is DEPRECATED. `VIDEO_VIEW` is deprecated; use `VIDEO_COMPLETION` instead. `CTV_CONSIDERATION` is in BETA. For update, only draft campaigns may update objective type. type: string enum: - AWARENESS - CONSIDERATION - VIDEO_VIEW - WEB_CONVERSION - CATALOG_SALES - WEB_SESSIONS - VIDEO_COMPLETION - APP_INSTALL - SALES - LEADS - CTV_CONSIDERATION CampaignPlanningAdGroupAudienceSize: description: Range audience size for an ad group. type: object properties: count_lower: description: Lower bound of the audience size estimate. type: integer example: 1000000 minimum: 0 count_upper: description: Upper bound of the audience size estimate. type: integer example: 2000000 minimum: 0 CampaignPlanningBudgetRecommendation: description: Budget recommendation response containing recommended budget, estimated days, and point estimations. type: object properties: budget_recommendation: description: The recommended budget amount. type: integer example: 5000000 experiment_campaign_budget_recommendation: description: List of experimental budget recommendations. type: array items: $ref: '#/components/schemas/CampaignPlanningExperimentBudgetRecommendation' lifetime_days_recommendation: description: Recommended number of days for the campaign lifetime. type: integer example: 30 point_estimations: description: List of point estimations for different budget scenarios. type: array items: $ref: '#/components/schemas/CampaignPlanningBudgetRecommendationPoint' CampaignPlanningBudgetRecommendationPoint: description: A point estimation containing the estimate data and estimation type for a budget recommendation. type: object properties: estimation_type: description: Estimation type for this point. allOf: - $ref: '#/components/schemas/CampaignPlanningEstimationType' point_estimate: description: Point estimate data. allOf: - $ref: '#/components/schemas/CampaignPlanningPointEstimate' CampaignPlanningConfidenceLevelAlert: description: A confidence level alert for the delivery estimates provided in the response. type: object properties: description: description: Human-readable context for debugging. Not intended for display to end users. type: string reason: description: Reason for the confidence level alert. allOf: - $ref: '#/components/schemas/CampaignPlanningConfidenceLevelAlertReason' severity: description: Severity of the confidence level alert. allOf: - $ref: '#/components/schemas/CampaignPlanningConfidenceLevelAlertSeverity' CampaignPlanningConfidenceLevelAlertReason: description: Reason for a confidence level alert on delivery estimates. type: string enum: - UNKNOWN - OTHER - ADVERTISER_HAS_NO_RECENT_CAMPAIGNS - ADVERTISER_HAS_NO_RECENT_CONVERSIONS CampaignPlanningConfidenceLevelAlertSeverity: description: Severity of a confidence level alert on delivery estimates. type: string enum: - UNKNOWN - LOW_MILD - LOW_MODERATE - LOW_SEVERE CampaignPlanningConversionAttribution: description: Attribution windows for a conversion event. type: object properties: click_window_days: description: Number of days to use as the conversion attribution window for a pin click action. allOf: - $ref: '#/components/schemas/CampaignPlanningConversionAttributionWindowDays' engagement_window_days: description: Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. allOf: - $ref: '#/components/schemas/CampaignPlanningConversionAttributionWindowDays' view_window_days: description: Number of days to use as the conversion attribution window for a view action. allOf: - $ref: '#/components/schemas/CampaignPlanningConversionAttributionWindowDays' CampaignPlanningConversionAttributionWindowDays: description: Conversion attribution window in days. type: string enum: - DAYS_0 - DAYS_1 - DAYS_7 - DAYS_30 - DAYS_60 CampaignPlanningConversionEvent: description: Conversion event for which a conversion rate estimate is computed. type: string enum: - SIGNUP - CHECKOUT - ADD_TO_CART - LEAD CampaignPlanningConversionRate: description: Conversion rate estimate for a specific conversion event and attribution window combination. type: object properties: attribution_windows: $ref: '#/components/schemas/CampaignPlanningConversionAttribution' conversion_event: $ref: '#/components/schemas/CampaignPlanningConversionEvent' conversion_rate: description: Conversion rate estimate. Used to translate impressions into conversions for oCPM ads. type: number format: float example: 2.32600002288818 required: - conversion_event - attribution_windows - conversion_rate CampaignPlanningCurveEstimate: type: object properties: estimation_type: description: Estimation type for campaign planning estimated curve example: IMPRESSION allOf: - $ref: '#/components/schemas/CampaignPlanningEstimationType' points: description: The estimation points that make up the estimated curve. type: array items: $ref: '#/components/schemas/CampaignPlanningPointEstimate' maxItems: 100 CampaignPlanningEstimationType: description: Estimation type for campaign planning estimated curve type: string enum: - IMPRESSION - CLICK - CONVERSION - WEEKLY_FREQUENCY - WEEKLY_REACH - LIFETIME_FREQUENCY - LIFETIME_REACH - CPM - CPC - CPA CampaignPlanningExperimentBudgetRecommendation: description: Experimental budget recommendation for a single experiment version. type: object properties: budget_recommendation: description: Recommended budget for this experiment version. type: integer example: 5500000 lifetime_days_recommendation: description: Recommended lifetime days for this experiment. type: integer example: 35 point_estimations: description: Point estimations for this experiment version. type: array items: $ref: '#/components/schemas/CampaignPlanningBudgetRecommendationPoint' version_id: description: Version identifier for the experiment. type: string CampaignPlanningPointEstimate: description: A JSON object that represents a single estimation point. An estimation point contains the expected budget used and the estimated result, Y, along with an expected range based for the budget. type: object properties: budget: description: The budget value of the point. type: integer example: 5000000 double_y: description: Y value as a decimal. type: number format: double example: 10.68 nullable: true max_y: description: The maximum Y value of the point. type: integer example: 2000 nullable: true min_y: description: The minimum Y value of the point. type: integer example: 1000 nullable: true y: description: The expected Y value of the point. type: integer example: 1500 nullable: true required: - budget - double_y - max_y - min_y - y CampaignPlanningResponseError: description: Error encountered while estimating delivery for a campaign. type: object properties: code: $ref: '#/components/schemas/CampaignPlanningResponseErrorCode' message: description: Human-readable error message. type: string CampaignPlanningResponseErrorCode: description: Error code returned for a campaign planning estimate failure. type: string enum: - SERVER_ERROR - AUDIENCE_LIST_MISSING - INVALID_REQUEST - PRODUCT_GROUP_MISSING CampaignSummaryStatus: type: string enum: - RUNNING - PAUSED - NOT_STARTED - COMPLETED - ADVERTISER_DISABLED - ARCHIVED - DRAFT - DELETED_DRAFT CampaignUpdateRequest: type: object properties: ad_account_id: description: Campaign's Advertiser ID. If you want to create a campaign in a Business Account shared account you need to specify the Business Access advertiser ID in both the query path param as well as the request body schema. type: string example: '549755885175' pattern: ^\d+$ daily_spend_cap: description: Campaign daily spending cap. Required for Campaign Budget Optimization (CBO) campaigns. This and "lifetime_spend_cap" cannot be set at the same time. type: integer example: 1432744744 nullable: true default_ad_group_budget_in_micro_currency: description: When transitioning from campaign budget optimization to non-campaign budget optimization, the default_ad_group_budget_in_micro_currency will propagate to each child ad groups daily budget. Unit is micro currency of the associated advertiser account. type: integer nullable: true end_time: description: |- Timestamp in Unix format for scheduling when ads in the campaign stop appearing. Must occur after any end times for child ad groups. If `end_time` is not specified for the campaign, ads run indefinitely unless you update the campaign, changing their status to `paused`. Learn about scheduling campaigns. Different end times can be set for the campaign's child ad groups, but they cannot occur after an `end_time` specified for the campaign. - If your campaign has a child ad group with an end time specified, and if you update that campaign with an `end_time` that is earlier than that of the ad group, the campaign `end_time` will supersede the ad group `end_time`, and the request will not return an error. - In this scenario, if you call List campaigns or List ad groups, the returned campaigns or ad groups are listed with the start and end times that you assigned them, regardless of supersedence. type: integer example: 1644023526 nullable: true id: description: Campaign ID. type: string example: '549755885175' pattern: ^\d+$ is_automated_campaign: $ref: '#/components/schemas/CampaignIsAutomatedCampaign' is_campaign_budget_optimization: $ref: '#/components/schemas/CampaignIsCampaignBudgetOptimization' is_flexible_daily_budgets: $ref: '#/components/schemas/CampaignIsFlexibleDailyBudgets' lifetime_spend_cap: description: Campaign total spending cap. Required for Campaign Budget Optimization (CBO) campaigns. This and "daily_spend_cap" cannot be set at the same time. type: integer example: 1432744744 nullable: true name: description: Campaign name. type: string example: ACME Tools order_line_id: description: Order line ID that appears on the invoice. type: string example: '549755885175' nullable: true pattern: ^\d+$ start_time: description: |- Timestamp in Unix format for scheduling when ads in the campaign start to appear. Must precede any start times set for child ad groups. Defaults to current time if no time is specified. Learn about scheduling campaigns. Different start times can be set for the campaign's child ad groups, but they cannot occur before a `start_time` specified for the campaign. - If your campaign has a child ad group with a start time specified, and if you update that campaign with a `start_time` that is later than that of the ad group, the campaign `start_time` will supersede the ad group `start_time`, and the request will not return an error. - In this scenario, if you call List campaigns or List ad groups, the returned campaigns or ad groups are listed with the start and end times that you assigned them, regardless of supersedence. type: integer example: 1580865126 nullable: true status: $ref: '#/components/schemas/EntityStatus' tracking_urls: type: object allOf: - $ref: '#/components/schemas/TrackingUrls' nullable: true allOf: - type: object properties: bid_options: $ref: '#/components/schemas/CampaignBidOptionsUpdate' intended_promotion_type: $ref: '#/components/schemas/IntendedPromotionType' is_ltv_optimized: description: Specifies whether the campaign is optimized for Lifetime Value (LTV). Only available for eligible advertisers. type: boolean is_performance_plus: description: Enable Pinterest Performance+ for your campaign. To learn more, see Pinterest Performance+ Setup. This field is immutable, except only for campaigns in draft status which may update this field. type: boolean is_top_of_search: description: Enable Top Of Search for your campaign. This field is immutable, except only for campaigns in draft status which may update this field. type: boolean objective_type: allOf: - $ref: '#/components/schemas/ObjectiveType' nullable: true required: - ad_account_id - id title: CampaignUpdateRequest CampaignUpdateRequestAllOf2: type: object properties: bid_options: $ref: '#/components/schemas/CampaignBidOptionsUpdate' intended_promotion_type: $ref: '#/components/schemas/IntendedPromotionType' is_ltv_optimized: description: Specifies whether the campaign is optimized for Lifetime Value (LTV). Only available for eligible advertisers. type: boolean is_performance_plus: description: Enable Pinterest Performance+ for your campaign. To learn more, see Pinterest Performance+ Setup. This field is immutable, except only for campaigns in draft status which may update this field. type: boolean is_top_of_search: description: Enable Top Of Search for your campaign. This field is immutable, except only for campaigns in draft status which may update this field. type: boolean objective_type: allOf: - $ref: '#/components/schemas/ObjectiveType' nullable: true CampaignsAnalyticsMetrics: type: object properties: CAMPAIGN_ID: description: The ID of the campaing that this metrics belongs to. Returned as long as aggregate_report_rows is not true. type: string pattern: ^\d+$ DATE: description: Current metrics date. Only returned when granularity is a time-based value (`DAY`, `HOUR`, `WEEK`, `MONTH`) type: string format: date CancelInviteException: description: An exception object if there is an error performing the cancellation. It will only be provided if there is an error. type: object properties: invite_id: type: string pattern: ^\d+$ message: type: string nullable: true CancelInviteResult: type: object properties: id: type: string pattern: ^\d+$ invite_data: $ref: '#/components/schemas/InviteDataResponse' is_received_invite: type: boolean user: $ref: '#/components/schemas/CancelInviteResultUser' nullable: true CancelInviteResultItem: type: object properties: exception: $ref: '#/components/schemas/CancelInviteException' invite: $ref: '#/components/schemas/CancelInviteResult' CancelInviteResultUser: description: Metadata of the member/partner that has access to the asset. type: object properties: email: description: Email of the business member/partner. type: string id: description: Unique identifier of the business member/partner. type: string maxLength: 20 minLength: 1 username: description: Username of the business member/partner. type: string CancelInvitesRequest: description: An object with the list of invite/request ids to cancel. type: object properties: invite_ids: description: A list of invite/request ids to cancel. type: array items: $ref: '#/components/schemas/BusinessInviteOrPartnerId' maxItems: 50 minItems: 1 required: - invite_ids CancelInvitesResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/CancelInviteResultItem' CarouselSlot: type: object properties: description: description: Carousel Pin slot description. type: string link: description: Carousel Pin slot link. type: string title: description: Carousel Pin slot title. type: string CartingPlatformType: description: The vendor platform type of the carting ad. 1 for MIKMAK, 2 for PEAR. type: integer maximum: 2 minimum: 1 CartingProduct: type: object properties: carting_product_id: description: the internal Pinterest carting product id (different from industry product id) type: string pattern: ^\d+$ display_preferred_retailers_only: description: Whether to display only the preferred retailers for the carting product type: boolean display_product_price: description: Whether to display the price for the carting product type: boolean preferred_retailers: description: A sorted array of preferred retailers for the carting product type: array items: $ref: '#/components/schemas/CartingRetailer' randomize_preferred_retailers: description: Whether to randomize preferred retailers for the carting product type: boolean required: - carting_product_id CartingRetailer: type: object properties: retailer_id: description: Unique identifier for the retailer type: string retailer_name: description: Name of the retailer type: string required: - retailer_id - retailer_name Catalog: description: Catalog entity type: object properties: catalog_type: $ref: '#/components/schemas/CatalogsType' created_at: type: string format: date-time example: 2022-03-14T15:15:22Z readOnly: true id: description: ID of the catalog entity. type: string example: '864344156814050986' pattern: ^\d+$ name: description: A human-friendly name associated to a catalog entity. type: string updated_at: type: string format: date-time example: 2022-03-14T15:16:34Z readOnly: true required: - id - name - catalog_type - created_at - updated_at CatalogBinding: description: Information about a catalog asset. type: object properties: catalog_type: description: Catalog type type: string id: description: Catalog ID. type: string pattern: ^\d+$ name: description: Catalog name type: string CatalogCreate: description: Resource create operation model. type: object properties: catalog_type: $ref: '#/components/schemas/CatalogsType' name: description: A human-friendly name associated to a catalog entity. type: string required: - name - catalog_type CatalogUpdate: description: Resource create or update operation model. type: object properties: catalog_type: $ref: '#/components/schemas/CatalogsType' name: description: A human-friendly name associated to a catalog entity. type: string CatalogsAiContentDisclosure: description: AI content disclosure for a single asset of a catalog item. type: object properties: disclosure: description: Disclosure labels that apply to this asset. type: array items: $ref: '#/components/schemas/CatalogsAiContentDisclosureLabel' example: - ai_modified minItems: 1 url: description: URL of the asset. Must match one of image_link, additional_image_link, or video_link. type: string example: https://scene.example.com/image/image_v2.jpg maxLength: 2000 required: - url - disclosure CatalogsAiContentDisclosureLabel: description: Disclosure label for AI-generated or AI-modified content in a catalog item asset. type: string example: ai_modified enum: - ai_modified - synthetic_performer CatalogsAvailableFilterValues: description: Object holding available filter values for each filter key type: object discriminator: propertyName: catalog_type mapping: RETAIL: '#/components/schemas/CatalogsRetailAvailableFilterValues' HOTEL: '#/components/schemas/CatalogsHotelAvailableFilterValues' CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsAvailableFilterValues' oneOf: - $ref: '#/components/schemas/CatalogsRetailAvailableFilterValues' - $ref: '#/components/schemas/CatalogsHotelAvailableFilterValues' - $ref: '#/components/schemas/CatalogsCreativeAssetsAvailableFilterValues' title: catalogs_available_filter_values CatalogsBaseFilterKeys: description: Base filter keys shared across catalog filtering anyOf: - $ref: '#/components/schemas/MinPriceFilter' - $ref: '#/components/schemas/MaxPriceFilter' - $ref: '#/components/schemas/CurrencyFilter' - $ref: '#/components/schemas/ItemIdFilter' - $ref: '#/components/schemas/AvailabilityFilter' - $ref: '#/components/schemas/BrandFilter' - $ref: '#/components/schemas/ConditionFilter' - $ref: '#/components/schemas/CustomLabel0Filter' - $ref: '#/components/schemas/CustomLabel1Filter' - $ref: '#/components/schemas/CustomLabel2Filter' - $ref: '#/components/schemas/CustomLabel3Filter' - $ref: '#/components/schemas/CustomLabel4Filter' - $ref: '#/components/schemas/ItemGroupIdFilter' - $ref: '#/components/schemas/GenderFilter' - $ref: '#/components/schemas/MediaTypeFilter' - $ref: '#/components/schemas/ProductType4Filter' - $ref: '#/components/schemas/ProductType3Filter' - $ref: '#/components/schemas/ProductType2Filter' - $ref: '#/components/schemas/ProductType1Filter' - $ref: '#/components/schemas/ProductType0Filter' - $ref: '#/components/schemas/GoogleProductCategory6Filter' - $ref: '#/components/schemas/GoogleProductCategory5Filter' - $ref: '#/components/schemas/GoogleProductCategory4Filter' - $ref: '#/components/schemas/GoogleProductCategory3Filter' - $ref: '#/components/schemas/GoogleProductCategory2Filter' - $ref: '#/components/schemas/GoogleProductCategory1Filter' - $ref: '#/components/schemas/GoogleProductCategory0Filter' - $ref: '#/components/schemas/CustomNumber0Filter' - $ref: '#/components/schemas/CustomNumber1Filter' - $ref: '#/components/schemas/CustomNumber2Filter' - $ref: '#/components/schemas/CustomNumber3Filter' - $ref: '#/components/schemas/CustomNumber4Filter' - $ref: '#/components/schemas/TitleKeywordsFilter' - $ref: '#/components/schemas/PinterestProductCategoriesFilter' title: catalogs_base_filter_keys CatalogsBaseFiltersAllOf: type: object properties: all_of: type: array items: $ref: '#/components/schemas/CatalogsBaseFilterKeys' minItems: 1 additionalProperties: false required: - all_of title: all_of CatalogsBaseFiltersAnyOf: type: object properties: any_of: type: array items: $ref: '#/components/schemas/CatalogsBaseFilterKeys' minItems: 1 additionalProperties: false required: - any_of title: any_of CatalogsCreateCreativeAssetsItem: description: A creative assets item to be created. type: object properties: attributes: $ref: '#/components/schemas/CatalogsCreativeAssetsAttributes' creative_assets_id: description: The catalog creative assets id in the merchant namespace type: string example: DS0294-M operation: type: string enum: - CREATE required: - attributes - creative_assets_id - operation CatalogsCreateHotelItem: description: A hotel item to be created. type: object properties: attributes: $ref: '#/components/schemas/CatalogsHotelAttributes' hotel_id: description: The catalog hotel id in the merchant namespace type: string example: DS0294-M operation: type: string enum: - CREATE required: - attributes - hotel_id - operation CatalogsCreateReportResponse: type: object properties: token: description: Token to be used to get the report type: string CatalogsCreateRetailItem: description: An item to be created type: object properties: attributes: $ref: '#/components/schemas/ItemAttributesRequest' item_id: description: The catalog item id in the merchant namespace type: string example: DS0294-M operation: type: string enum: - CREATE required: - attributes - item_id - operation CatalogsCreativeAssetsAttributes: type: object properties: ai_disclosures: description: AI content disclosures for individual assets (image_link or video_link) on this creative assets item. Each entry declares which disclosure types apply to a single asset URL. type: array items: $ref: '#/components/schemas/CatalogsAiContentDisclosure' example: - url: https://scene.example.com/image/image_v2.jpg disclosure: - ai_modified image_link: description: The creative assets image. type: string example: https://scene.example.com/image/image_v2.jpg video_link: description: The creative assets video. type: string example: https://scene.example.com/image/image_v2.mp4 allOf: - $ref: '#/components/schemas/CatalogsUpdatableCreativeAssetsAttributes' CatalogsCreativeAssetsAvailableFilterValues: type: object properties: catalog_type: type: string enum: - CREATIVE_ASSETS filter_values: $ref: '#/components/schemas/CatalogsCreativeAssetsFilterValuesMap' required: - catalog_type - filter_values title: catalogs_creative_assets_available_filter_values CatalogsCreativeAssetsBatchItem: description: Creative assets batch item type: object discriminator: propertyName: operation mapping: CREATE: '#/components/schemas/CatalogsCreateCreativeAssetsItem' UPSERT: '#/components/schemas/CatalogsUpsertCreativeAssetsItem' UPDATE: '#/components/schemas/CatalogsUpdateCreativeAssetsItem' DELETE: '#/components/schemas/CatalogsDeleteCreativeAssetsItem' oneOf: - $ref: '#/components/schemas/CatalogsCreateCreativeAssetsItem' - $ref: '#/components/schemas/CatalogsUpsertCreativeAssetsItem' - $ref: '#/components/schemas/CatalogsUpdateCreativeAssetsItem' - $ref: '#/components/schemas/CatalogsDeleteCreativeAssetsItem' CatalogsCreativeAssetsBatchRequest: description: Request object to update catalogs creative assets items type: object properties: catalog_id: description: Catalog id pertaining to the creative assets item. If not provided, default to oldest creative assets catalog example: '2680059592705' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' catalog_type: type: string enum: - CREATIVE_ASSETS country: $ref: '#/components/schemas/Country' items: description: Array with creative assets item operations type: array items: $ref: '#/components/schemas/CatalogsCreativeAssetsBatchItem' maxItems: 1000 minItems: 1 language: description: We recommend using the CatalogsLocale values. anyOf: - $ref: '#/components/schemas/CatalogsLocale' - $ref: '#/components/schemas/Language' required: - catalog_type - country - items - language CatalogsCreativeAssetsFeed: description: Catalogs Creative Asset Feed object type: object properties: catalog_id: description: Catalog id pertaining to the feed. If not provided, feed will use a default catalog based on type. type: string pattern: ^\d+$ catalog_type: type: string enum: - CREATIVE_ASSETS created_at: type: string format: date-time readOnly: true credentials: $ref: '#/components/schemas/CatalogsFeedCredentials' default_country: $ref: '#/components/schemas/Country' default_currency: $ref: '#/components/schemas/NullableCurrency' default_locale: description: The locale used within a feed for product descriptions. type: string format: $ref: '#/components/schemas/CatalogsFormat' id: description: ID of the feed entity. type: string example: '864344156814050986' pattern: ^\d+$ readOnly: true location: description: The URL where a feed is available for download. This URL is what Pinterest will use to download a feed for processing. type: string pattern: ^(http|https|ftp|sftp):// name: description: A human-friendly name associated to a given feed. This value is currently nullable due to historical reasons. It is expected to become non-nullable in the future. type: string nullable: true preferred_processing_schedule: $ref: '#/components/schemas/CatalogsFeedProcessingSchedule' status: $ref: '#/components/schemas/CatalogsStatus' updated_at: type: string format: date-time readOnly: true required: - id - default_locale - location - name - created_at - updated_at - format - status - catalog_type - catalog_id - default_country title: catalogs_creative_assets_feed CatalogsCreativeAssetsFeedsCreateRequest: description: Request object for creating a feed. type: object properties: catalog_id: description: Catalog id pertaining to the feed. If not provided, feed will use a default catalog based on type. type: string pattern: ^\d+$ catalog_type: type: string enum: - CREATIVE_ASSETS credentials: $ref: '#/components/schemas/CatalogsFeedCredentials' default_country: $ref: '#/components/schemas/Country' default_currency: $ref: '#/components/schemas/NullableCurrency' default_locale: description: The locale used within a feed for product descriptions. anyOf: - $ref: '#/components/schemas/CatalogsLocale' - $ref: '#/components/schemas/DeprecatedCatalogFeedsCreateRequestDefaultLocale' format: $ref: '#/components/schemas/CatalogsFormat' location: $ref: '#/components/schemas/FeedLocation' name: $ref: '#/components/schemas/FeedDisplayName' preferred_processing_schedule: $ref: '#/components/schemas/CatalogsFeedProcessingSchedule' status: default: ACTIVE allOf: - $ref: '#/components/schemas/CatalogsStatus' additionalProperties: false required: - default_locale - format - location - name - catalog_type - default_country title: feeds_creative_assets_create_request CatalogsCreativeAssetsFeedsUpdateRequest: description: Request object for updating a feed. type: object properties: catalog_type: type: string enum: - CREATIVE_ASSETS credentials: $ref: '#/components/schemas/CatalogsFeedCredentials' default_currency: $ref: '#/components/schemas/NullableCurrency' format: $ref: '#/components/schemas/CatalogsFormat' location: $ref: '#/components/schemas/FeedLocation' name: $ref: '#/components/schemas/FeedDisplayName' preferred_processing_schedule: $ref: '#/components/schemas/CatalogsFeedProcessingSchedule' status: $ref: '#/components/schemas/CatalogsStatus' additionalProperties: false required: - catalog_type title: catalogs_feeds_update_request CatalogsCreativeAssetsFilterValuesMap: description: A map of filter attributes to their available values. type: object properties: custom_label_0: type: array items: type: string custom_label_1: type: array items: type: string custom_label_2: type: array items: type: string custom_label_3: type: array items: type: string custom_label_4: type: array items: type: string google_product_category_0: type: array items: type: string google_product_category_1: type: array items: type: string google_product_category_2: type: array items: type: string google_product_category_3: type: array items: type: string google_product_category_4: type: array items: type: string google_product_category_5: type: array items: type: string google_product_category_6: type: array items: type: string media_type: type: array items: $ref: '#/components/schemas/MediaType' title: catalogs_creative_assets_filter_values_map CatalogsCreativeAssetsItemErrorResponse: description: Object describing a creative assets item error type: object properties: catalog_type: type: string enum: - CREATIVE_ASSETS creative_assets_id: description: The catalog creative assets id in the merchant namespace type: string example: DS0294-M errors: description: Array with the errors for the item id requested type: array items: $ref: '#/components/schemas/ItemValidationEvent' item_response_kind: description: Discriminator literal identifying this leaf inside an `ItemResponse` payload. type: string enum: - creative_assets_item_error additionalProperties: false required: - catalog_type - item_response_kind - errors title: catalogs_creative_assets_item_error_response CatalogsCreativeAssetsItemResponse: description: Object describing a creative assets item record type: object properties: attributes: $ref: '#/components/schemas/CatalogsCreativeAssetsAttributes' catalog_type: type: string enum: - CREATIVE_ASSETS creative_assets_id: description: The catalog creative assets id in the merchant namespace type: string example: DS0294-M item_response_kind: description: Discriminator literal identifying this leaf inside an `ItemResponse` payload. type: string enum: - creative_assets_item pins: description: The pins mapped to the item type: array items: $ref: '#/components/schemas/Pin' maxItems: 11 nullable: true additionalProperties: false required: - catalog_type - item_response_kind title: catalogs_creative_assets_item_response CatalogsCreativeAssetsItemsBatch: description: Object describing the catalogs creative assets items batch type: object properties: batch_id: description: Id of the catalogs items batch example: '595953100599279259' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' catalog_type: type: string enum: - CREATIVE_ASSETS completed_time: description: "Date and time (UTC) of the batch completion: YYYY-MM-DD'T'hh:mm:ss" type: string format: date-time example: 2024-01-01T20:20:00Z nullable: true created_time: description: "Date and time (UTC) of the batch creation: YYYY-MM-DD'T'hh:mm:ss" type: string format: date-time example: 2024-01-01T20:10:40Z items: description: Array with the catalogs items processing records part of the catalogs items batch type: array items: $ref: '#/components/schemas/CreativeAssetsProcessingRecord' status: $ref: '#/components/schemas/BatchOperationStatus' required: - catalog_type CatalogsCreativeAssetsItemsPostFilter: type: object properties: catalog_id: description: Catalog id pertaining to the creative assets item. If not provided, default to oldest creative assets catalog type: string pattern: ^\d+$ catalog_type: type: string enum: - CREATIVE_ASSETS creative_assets_ids: type: array items: type: string maxItems: 1000 minItems: 1 required: - catalog_type - creative_assets_ids CatalogsCreativeAssetsListProductsByCatalogBasedFilterRequest: description: Request object to list products for a given creative assets catalog_id and product group filter. type: object properties: catalog_id: description: Catalog ID pertaining to the product group. example: '2680059592705' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' catalog_type: type: string enum: - CREATIVE_ASSETS filters: $ref: '#/components/schemas/CatalogsCreativeAssetsProductGroupFilters' additionalProperties: false required: - catalog_id - catalog_type - filters title: creative_assets_list_products_by_catalog_based_filter_request CatalogsCreativeAssetsProduct: type: object properties: catalog_type: type: string enum: - CREATIVE_ASSETS metadata: $ref: '#/components/schemas/CatalogsCreativeAssetsProductMetadata' pin: $ref: '#/components/schemas/Pin' required: - catalog_type - metadata - pin CatalogsCreativeAssetsProductGroup: type: object properties: catalog_id: description: Catalog ID pertaining to the product group. example: '2680059592705' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' catalog_type: type: string enum: - CREATIVE_ASSETS created_at: description: Unix timestamp in seconds of when catalog product group was created. type: integer example: 1621350033000 description: type: string nullable: true filters: $ref: '#/components/schemas/CatalogsCreativeAssetsProductGroupFilters' id: description: ID of the catalog product group. example: '443727193917' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' name: description: Name of catalog product group type: string example: Most Popular updated_at: description: Unix timestamp in seconds of last time catalog product group was updated. type: integer example: 1622742155000 required: - catalog_id - id - catalog_type - filters title: creative_assets_product_group CatalogsCreativeAssetsProductGroupCreateRequest: description: Request object for creating a creative assets product group. type: object properties: catalog_id: description: Catalog ID pertaining to the product group. example: '2680059592705' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' catalog_type: type: string enum: - CREATIVE_ASSETS description: type: string nullable: true filters: $ref: '#/components/schemas/CatalogsCreativeAssetsProductGroupFilters' name: type: string additionalProperties: false required: - catalog_id - name - catalog_type - filters title: creative_assets_product_groups_create_request CatalogsCreativeAssetsProductGroupFilterKeys: anyOf: - $ref: '#/components/schemas/CreativeAssetsIdFilter' - $ref: '#/components/schemas/CustomLabel0Filter' - $ref: '#/components/schemas/CustomLabel1Filter' - $ref: '#/components/schemas/CustomLabel2Filter' - $ref: '#/components/schemas/CustomLabel3Filter' - $ref: '#/components/schemas/CustomLabel4Filter' - $ref: '#/components/schemas/GoogleProductCategory6Filter' - $ref: '#/components/schemas/GoogleProductCategory5Filter' - $ref: '#/components/schemas/GoogleProductCategory4Filter' - $ref: '#/components/schemas/GoogleProductCategory3Filter' - $ref: '#/components/schemas/GoogleProductCategory2Filter' - $ref: '#/components/schemas/GoogleProductCategory1Filter' - $ref: '#/components/schemas/GoogleProductCategory0Filter' - $ref: '#/components/schemas/MediaTypeFilter' - $ref: '#/components/schemas/TitleKeywordsFilter' - $ref: '#/components/schemas/LinkFilter' title: catalogs_product_group_keys CatalogsCreativeAssetsProductGroupFilters: description: Object holding a group of filters for a creative assets product group anyOf: - $ref: '#/components/schemas/CatalogsCreativeAssetsProductGroupFiltersAnyOf' - $ref: '#/components/schemas/CatalogsCreativeAssetsProductGroupFiltersAllOf' title: catalogs_product_group_filters CatalogsCreativeAssetsProductGroupFiltersAllOf: type: object properties: all_of: type: array items: $ref: '#/components/schemas/CatalogsCreativeAssetsProductGroupFilterKeys' additionalProperties: false required: - all_of title: all_of CatalogsCreativeAssetsProductGroupFiltersAnyOf: type: object properties: any_of: type: array items: $ref: '#/components/schemas/CatalogsCreativeAssetsProductGroupFilterKeys' additionalProperties: false required: - any_of title: any_of CatalogsCreativeAssetsProductGroupProductCounts: description: Product counts for a Creative Assets CatalogsProductGroup type: object properties: app_links: type: number minimum: 0 catalog_type: type: string enum: - CREATIVE_ASSETS images: type: number minimum: 0 total: type: number minimum: 0 videos: type: number minimum: 0 required: - catalog_type - total - videos - images - app_links title: catalogs_creative_assets_product_group_product_counts CatalogsCreativeAssetsProductGroupUpdateRequest: description: Request object for updating a creative assets product group. type: object properties: catalog_type: type: string enum: - CREATIVE_ASSETS description: type: string nullable: true filters: $ref: '#/components/schemas/CatalogsCreativeAssetsProductGroupFilters' name: description: Name of catalog product group type: string example: Most Popular additionalProperties: false title: creative_assets_product_groups_update_request CatalogsCreativeAssetsProductMetadata: description: Creative assets product metadata entity type: object properties: creative_assets_id: description: The user-created unique ID that represents the creative assets item. type: string example: 123abc visibility: $ref: '#/components/schemas/CreativeAssetsVisibilityType' required: - creative_assets_id - visibility CatalogsDeleteCreativeAssetsItem: description: A creative assets item to be deleted type: object properties: creative_assets_id: description: The catalog creative assets id in the merchant namespace type: string example: DS0294-M operation: type: string enum: - DELETE required: - creative_assets_id - operation CatalogsDeleteHotelItem: description: A hotel item to be deleted type: object properties: hotel_id: description: The catalog hotel id in the merchant namespace type: string example: DS0294-M operation: type: string enum: - DELETE required: - hotel_id - operation CatalogsDeleteRetailItem: description: An item to be deleted type: object properties: item_id: description: The catalog item id in the merchant namespace type: string example: DS0294-M last_updated_time: description: The millisecond timestamp when the item was lastly modified by the merchant. type: integer format: int64 example: 1641483432072 operation: type: string enum: - DELETE required: - item_id - operation CatalogsFeed: description: Catalogs Feed object type: object discriminator: propertyName: catalog_type mapping: RETAIL: '#/components/schemas/CatalogsRetailFeed' HOTEL: '#/components/schemas/CatalogsHotelFeed' CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsFeed' oneOf: - $ref: '#/components/schemas/CatalogsRetailFeed' - $ref: '#/components/schemas/CatalogsHotelFeed' - $ref: '#/components/schemas/CatalogsCreativeAssetsFeed' title: catalogs_feed CatalogsFeedCreateRequestSchema: oneOf: - $ref: '#/components/schemas/CatalogsVerticalFeedsCreateRequest' - $ref: '#/components/schemas/CatalogsFeedsCreateRequest' CatalogsFeedCredentials: description: This field is **OPTIONAL**. Use this if your feed file requires username and password. type: object properties: password: description: The required password for downloading a feed. type: string format: password username: description: The required username for downloading a feed. type: string nullable: true required: - password - username CatalogsFeedIngestion: type: object properties: created_at: description: Timestamp of the feed ingestion. type: string format: date-time example: 2022-03-14T15:15:22Z feed_id: description: Catalog Feed id pertaining to the feed ingestion. type: string example: '2680059592705' pattern: ^\d+$ id: description: Unique identifier of a feed ingestion. type: string example: '2680059592705' pattern: ^\d+$ status: description: Status of the feed ingestion. allOf: - $ref: '#/components/schemas/CatalogsFeedProcessingStatus' required: - created_at - feed_id - id - status CatalogsFeedIngestionDetails: type: object properties: errors: $ref: '#/components/schemas/CatalogsFeedIngestionErrors' info: $ref: '#/components/schemas/CatalogsFeedIngestionInfo' warnings: $ref: '#/components/schemas/CatalogsFeedIngestionWarnings' required: - errors - info - warnings CatalogsFeedIngestionErrors: type: object properties: ACCOUNT_FLAGGED: description: We detected an issue with your account and are not currently ingesting your items. Please review our policies at policy.pinterest.com/community-guidelines#section-spam or contact us at help.pinterest.com/contact for more information. type: integer FETCH_GOOGLE_SHEET_NOT_SHARED: description: Update your Google Sheets sharing settings to 'Anyone with link' as a Viewer so that Pinterest can access your file. type: integer IMAGE_FILE_NOT_ACCESSIBLE: description: Image files are unreadable. Please upload new files to continue. type: integer IMAGE_FILE_NOT_FOUND: description: Image files are unreadable. Please upload new files to continue. type: integer IMAGE_INVALID_FILE: description: Image files are unreadable. Please upload new files to continue. type: integer IMAGE_LEVEL_INTERNAL_ERROR: description: We experienced a technical difficulty and were unable to download some images. The next download attempt will happen in 24 hours. type: integer IMAGE_MALFORMED_URL: description: Image files are unreadable. Please check your link and upload new files to continue. type: integer LARGE_PRODUCT_COUNT_DECREASE: description: The product count has decreased by more than 99% compared to the last successful ingestion. type: integer LINE_LEVEL_INTERNAL_ERROR: description: We experienced a technical difficulty and were unable to ingest this some items. The next ingestion will happen in 24 hours. type: integer CatalogsFeedIngestionInfo: type: object properties: IN_STOCK: description: The number of ingested products that are in stock. type: integer OUT_OF_STOCK: description: The number of ingested products that are in out of stock. type: integer PREORDER: description: The number of ingested products that are in preorder. type: integer CatalogsFeedIngestionWarnings: type: object properties: AD_IMAGE_DOWNLOAD_CONTENT_READ_ERROR: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_DNS_LOOKUP_ERROR: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_FILE_NOT_ACCESSIBLE: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_FILE_NOT_FOUND: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_HTTP_STATUS_400: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_HTTP_STATUS_403: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_HTTP_STATUS_404: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_HTTP_STATUS_405: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_HTTP_STATUS_410: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_HTTP_STATUS_429: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_HTTP_STATUS_500: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_HTTP_STATUS_502: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_HTTP_STATUS_503: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_HTTP_STATUS_504: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_HTTP_STATUS_507: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_HTTP_STATUS_508: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_HTTP_STATUS_520: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_HTTP_STATUS_521: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_HTTP_STATUS_522: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_HTTP_STATUS_525: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_INTERNAL_CONFIGURATION_ERROR: description: We experienced a technical difficulty and were unable to download some additional images. The next download attempt will happen in 24 hours. type: integer AD_IMAGE_DOWNLOAD_INTERNAL_ERROR: description: We experienced a technical difficulty and were unable to download some additional images. The next download attempt will happen in 24 hours. type: integer AD_IMAGE_DOWNLOAD_INTERNAL_FAILED_TO_DOWNLOAD: description: We experienced a technical difficulty and were unable to download some additional images. The next download attempt will happen in 24 hours. type: integer AD_IMAGE_DOWNLOAD_INTERNAL_MALFORMED_URL: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_INTERNAL_RATE_LIMITED: description: We experienced a technical difficulty and were unable to download some additional images. The next download attempt will happen in 24 hours. type: integer AD_IMAGE_DOWNLOAD_INTERNAL_REQUEST_EXPIRED: description: We experienced a technical difficulty and were unable to download some additional images. The next download attempt will happen in 24 hours. type: integer AD_IMAGE_DOWNLOAD_INVALID_FILE: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_SITE_ERROR: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_SITE_TIMEOUT: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_SSL_ERROR: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_DOWNLOAD_SSL_HANDSHAKE_ERROR: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_PROCESSING_EMPTY_FILE: description: Ad image files are unreadable. Please check your link and upload new files to continue. type: integer AD_IMAGE_PROCESSING_HEIGHT_TOO_SMALL: description: Ad images must have a height larger than 75 pixels type: integer AD_IMAGE_PROCESSING_TOO_MANY_PIXELS: description: Ad images must have a maximum area (width x height) of less than 89478485 pixels type: integer AD_IMAGE_PROCESSING_TYPE_MISMATCH: description: Some ad images could not be processed due to a file type mismatch. type: integer AD_IMAGE_PROCESSING_WIDTH_TOO_SMALL: description: Ad images must have a width larger than 75 pixels type: integer AD_VIDEO_DOWNLOAD_CONTENT_READ_ERROR: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_DNS_LOOKUP_ERROR: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_FILE_NOT_ACCESSIBLE: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_FILE_NOT_FOUND: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_HTTP_STATUS_400: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_HTTP_STATUS_403: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_HTTP_STATUS_404: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_HTTP_STATUS_405: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_HTTP_STATUS_410: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_HTTP_STATUS_429: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_HTTP_STATUS_500: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_HTTP_STATUS_502: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_HTTP_STATUS_503: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_HTTP_STATUS_504: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_HTTP_STATUS_507: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_HTTP_STATUS_508: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_HTTP_STATUS_520: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_HTTP_STATUS_521: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_HTTP_STATUS_522: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_HTTP_STATUS_525: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_INTERNAL_CONFIGURATION_ERROR: description: We experienced a technical difficulty and were unable to download some additional images. The next download attempt will happen in 24 hours. type: integer AD_VIDEO_DOWNLOAD_INTERNAL_ERROR: description: We experienced a technical difficulty and were unable to download some additional images. The next download attempt will happen in 24 hours. type: integer AD_VIDEO_DOWNLOAD_INTERNAL_FAILED_TO_DOWNLOAD: description: We experienced a technical difficulty and were unable to download some additional images. The next download attempt will happen in 24 hours. type: integer AD_VIDEO_DOWNLOAD_INTERNAL_MALFORMED_URL: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_INTERNAL_RATE_LIMITED: description: We experienced a technical difficulty and were unable to download some additional images. The next download attempt will happen in 24 hours. type: integer AD_VIDEO_DOWNLOAD_INTERNAL_REQUEST_EXPIRED: description: We experienced a technical difficulty and were unable to download some additional images. The next download attempt will happen in 24 hours. type: integer AD_VIDEO_DOWNLOAD_INVALID_FILE: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_SITE_ERROR: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_SITE_TIMEOUT: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_SSL_ERROR: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_DOWNLOAD_SSL_HANDSHAKE_ERROR: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_LENGTH_TOO_SHORT: description: Ad videos length is too short. Please ensure that all ad videos are at least 4 seconds long. type: integer AD_VIDEO_PROCESSING_EMPTY_FILE: description: Ad video files are unreadable. Please check your link and upload new files to continue. type: integer AD_VIDEO_PROCESSING_HEIGHT_TOO_SMALL: description: Ad videos must have a height larger than 75 pixels type: integer AD_VIDEO_PROCESSING_TOO_MANY_PIXELS: description: Ad videos must have a maximum area (width x height) of less than 89478485 pixels type: integer AD_VIDEO_PROCESSING_TYPE_MISMATCH: description: Some ad videos could not be processed due to a file type mismatch. type: integer AD_VIDEO_PROCESSING_WIDTH_TOO_SMALL: description: Ad videos must have a width larger than 75 pixels type: integer ADDITIONAL_IMAGE_FILE_NOT_ACCESSIBLE: description: Additional image files are unreadable. Please upload new files to continue. type: integer ADDITIONAL_IMAGE_FILE_NOT_FOUND: description: Additional image files are unreadable. Please upload new files to continue. type: integer ADDITIONAL_IMAGE_INVALID_FILE: description: Additional image files are unreadable. Please upload new files to continue. type: integer ADDITIONAL_IMAGE_LEVEL_INTERNAL_ERROR: description: We experienced a technical difficulty and were unable to download some additional images. The next download attempt will happen in 24 hours. type: integer ADDITIONAL_IMAGE_MALFORMED_URL: description: Additional image files are unreadable. Please check your link and upload new files to continue. type: integer FETCH_GOOGLE_SHEET_PUBLIC_CAN_EDIT: description: Update your Google Sheets sharing settings from 'Editor' to 'Viewer'. type: integer HOTEL_PRICE_HEADER_IS_PRESENT: description: Price is not a supported column. Use base_price and sale_price instead. type: integer VIDEO_DOWNLOAD_VIDEO_TOO_SHORT: description: Video length is too short. Please ensure that the main video is at least 4 seconds long. type: integer VIDEO_FILE_NOT_ACCESSIBLE: description: Video files are unreadable. Please upload new files to continue. type: integer VIDEO_FILE_NOT_FOUND: description: Video files are unreadable. Please upload new files to continue. type: integer VIDEO_INVALID_FILE: description: Video files are unreadable. Please upload new files to continue. type: integer VIDEO_LEVEL_INTERNAL_ERROR: description: We experienced a technical difficulty and were unable to download some additional videos. The next download attempt will happen in 24 hours. type: integer VIDEO_MALFORMED_URL: description: Video files are unreadable. Please check your link and upload new files to continue. type: integer CatalogsFeedProcessingResult: type: object properties: created_at: type: string format: date-time example: 2022-03-14T15:15:22Z readOnly: true id: description: ID of the feed processing result. type: string example: '864344156814050986' pattern: ^\d+$ ingestion_details: $ref: '#/components/schemas/CatalogsFeedIngestionDetails' product_counts: $ref: '#/components/schemas/CatalogsFeedProductCounts' status: $ref: '#/components/schemas/CatalogsFeedProcessingStatus' updated_at: type: string format: date-time example: 2022-03-14T15:16:34Z readOnly: true validation_details: $ref: '#/components/schemas/CatalogsFeedValidationDetails' video_counts: $ref: '#/components/schemas/CatalogsFeedVideoCounts' required: - id - created_at - updated_at - ingestion_details - product_counts - status - validation_details CatalogsFeedProcessingSchedule: description: Daily processing schedule. This field is **OPTIONAL**. Use this to configure the preferred time for processing a feed (otherwise random). type: object properties: time: description: A time in format HH:MM with leading 0 (zero) type: string pattern: ^(0[0-9]|1[0-9]|2[0-3]):[0-5][0-9]$ timezone: description: The timezone considered for the processing schedule time. allOf: - $ref: '#/components/schemas/CatalogsFeedProcessingScheduleTimezone' nullable: true required: - time - timezone title: catalogs_processing_schedule CatalogsFeedProcessingScheduleTimezone: description: The timezone selected for the processing schedule time type: string enum: - Africa/Abidjan - Africa/Accra - Africa/Algiers - Africa/Bissau - Africa/Cairo - Africa/Casablanca - Africa/Ceuta - Africa/El_Aaiun - Africa/Johannesburg - Africa/Juba - Africa/Khartoum - Africa/Lagos - Africa/Maputo - Africa/Monrovia - Africa/Nairobi - Africa/Ndjamena - Africa/Sao_Tome - Africa/Tripoli - Africa/Tunis - Africa/Windhoek - America/Adak - America/Anchorage - America/Araguaina - America/Argentina/Buenos_Aires - America/Argentina/Catamarca - America/Argentina/Cordoba - America/Argentina/Jujuy - America/Argentina/La_Rioja - America/Argentina/Mendoza - America/Argentina/Rio_Gallegos - America/Argentina/Salta - America/Argentina/San_Juan - America/Argentina/San_Luis - America/Argentina/Tucuman - America/Argentina/Ushuaia - America/Asuncion - America/Atikokan - America/Bahia - America/Bahia_Banderas - America/Barbados - America/Belem - America/Belize - America/Blanc-Sablon - America/Boa_Vista - America/Bogota - America/Boise - America/Cambridge_Bay - America/Campo_Grande - America/Cancun - America/Caracas - America/Cayenne - America/Chicago - America/Chihuahua - America/Costa_Rica - America/Creston - America/Cuiaba - America/Curacao - America/Danmarkshavn - America/Dawson - America/Dawson_Creek - America/Denver - America/Detroit - America/Edmonton - America/Eirunepe - America/El_Salvador - America/Fort_Nelson - America/Fortaleza - America/Glace_Bay - America/Goose_Bay - America/Grand_Turk - America/Guatemala - America/Guayaquil - America/Guyana - America/Halifax - America/Havana - America/Hermosillo - America/Indiana/Indianapolis - America/Indiana/Knox - America/Indiana/Marengo - America/Indiana/Petersburg - America/Indiana/Tell_City - America/Indiana/Vevay - America/Indiana/Vincennes - America/Indiana/Winamac - America/Inuvik - America/Iqaluit - America/Jamaica - America/Juneau - America/Kentucky/Louisville - America/Kentucky/Monticello - America/La_Paz - America/Lima - America/Los_Angeles - America/Maceio - America/Managua - America/Manaus - America/Martinique - America/Matamoros - America/Mazatlan - America/Menominee - America/Merida - America/Metlakatla - America/Mexico_City - America/Miquelon - America/Moncton - America/Monterrey - America/Montevideo - America/Nassau - America/New_York - America/Nipigon - America/Nome - America/Noronha - America/North_Dakota/Beulah - America/North_Dakota/Center - America/North_Dakota/New_Salem - America/Nuuk - America/Ojinaga - America/Panama - America/Pangnirtung - America/Paramaribo - America/Phoenix - America/Port-au-Prince - America/Port_of_Spain - America/Porto_Velho - America/Puerto_Rico - America/Punta_Arenas - America/Rainy_River - America/Rankin_Inlet - America/Recife - America/Regina - America/Resolute - America/Rio_Branco - America/Santarem - America/Santiago - America/Santo_Domingo - America/Sao_Paulo - America/Scoresbysund - America/Sitka - America/St_Johns - America/Swift_Current - America/Tegucigalpa - America/Thule - America/Thunder_Bay - America/Tijuana - America/Toronto - America/Vancouver - America/Whitehorse - America/Winnipeg - America/Yakutat - America/Yellowknife - Antarctica/Casey - Antarctica/Davis - Antarctica/DumontDUrville - Antarctica/Macquarie - Antarctica/Mawson - Antarctica/Palmer - Antarctica/Rothera - Antarctica/Syowa - Antarctica/Troll - Antarctica/Vostok - Asia/Almaty - Asia/Amman - Asia/Anadyr - Asia/Aqtau - Asia/Aqtobe - Asia/Ashgabat - Asia/Atyrau - Asia/Baghdad - Asia/Baku - Asia/Bangkok - Asia/Barnaul - Asia/Beirut - Asia/Bishkek - Asia/Brunei - Asia/Chita - Asia/Choibalsan - Asia/Colombo - Asia/Damascus - Asia/Dhaka - Asia/Dili - Asia/Dubai - Asia/Dushanbe - Asia/Famagusta - Asia/Gaza - Asia/Hebron - Asia/Ho_Chi_Minh - Asia/Hong_Kong - Asia/Hovd - Asia/Irkutsk - Asia/Jakarta - Asia/Jayapura - Asia/Jerusalem - Asia/Kabul - Asia/Kamchatka - Asia/Karachi - Asia/Kathmandu - Asia/Khandyga - Asia/Kolkata - Asia/Krasnoyarsk - Asia/Kuala_Lumpur - Asia/Kuching - Asia/Macau - Asia/Magadan - Asia/Makassar - Asia/Manila - Asia/Nicosia - Asia/Novokuznetsk - Asia/Novosibirsk - Asia/Omsk - Asia/Oral - Asia/Pontianak - Asia/Pyongyang - Asia/Qatar - Asia/Qostanay - Asia/Qyzylorda - Asia/Riyadh - Asia/Sakhalin - Asia/Samarkand - Asia/Seoul - Asia/Shanghai - Asia/Singapore - Asia/Srednekolymsk - Asia/Taipei - Asia/Tashkent - Asia/Tbilisi - Asia/Tehran - Asia/Thimphu - Asia/Tokyo - Asia/Tomsk - Asia/Ulaanbaatar - Asia/Urumqi - Asia/Ust-Nera - Asia/Vladivostok - Asia/Yakutsk - Asia/Yangon - Asia/Yekaterinburg - Asia/Yerevan - Atlantic/Azores - Atlantic/Bermuda - Atlantic/Canary - Atlantic/Cape_Verde - Atlantic/Faroe - Atlantic/Madeira - Atlantic/Reykjavik - Atlantic/South_Georgia - Atlantic/Stanley - Australia/Adelaide - Australia/Brisbane - Australia/Broken_Hill - Australia/Currie - Australia/Darwin - Australia/Eucla - Australia/Hobart - Australia/Lindeman - Australia/Lord_Howe - Australia/Melbourne - Australia/Perth - Australia/Sydney - CET - CST6CDT - EET - EST - EST5EDT - Etc/GMT - Etc/GMT+1 - Etc/GMT+10 - Etc/GMT+11 - Etc/GMT+12 - Etc/GMT+2 - Etc/GMT+3 - Etc/GMT+4 - Etc/GMT+5 - Etc/GMT+6 - Etc/GMT+7 - Etc/GMT+8 - Etc/GMT+9 - Etc/GMT-1 - Etc/GMT-10 - Etc/GMT-11 - Etc/GMT-12 - Etc/GMT-13 - Etc/GMT-14 - Etc/GMT-2 - Etc/GMT-3 - Etc/GMT-4 - Etc/GMT-5 - Etc/GMT-6 - Etc/GMT-7 - Etc/GMT-8 - Etc/GMT-9 - Etc/UTC - Europe/Amsterdam - Europe/Andorra - Europe/Astrakhan - Europe/Athens - Europe/Belgrade - Europe/Berlin - Europe/Brussels - Europe/Bucharest - Europe/Budapest - Europe/Chisinau - Europe/Copenhagen - Europe/Dublin - Europe/Gibraltar - Europe/Helsinki - Europe/Istanbul - Europe/Kaliningrad - Europe/Kiev - Europe/Kirov - Europe/Lisbon - Europe/London - Europe/Luxembourg - Europe/Madrid - Europe/Malta - Europe/Minsk - Europe/Monaco - Europe/Moscow - Europe/Oslo - Europe/Paris - Europe/Prague - Europe/Riga - Europe/Rome - Europe/Samara - Europe/Saratov - Europe/Simferopol - Europe/Sofia - Europe/Stockholm - Europe/Tallinn - Europe/Tirane - Europe/Ulyanovsk - Europe/Uzhgorod - Europe/Vienna - Europe/Vilnius - Europe/Volgograd - Europe/Warsaw - Europe/Zaporozhye - Europe/Zurich - HST - Indian/Chagos - Indian/Christmas - Indian/Cocos - Indian/Kerguelen - Indian/Mahe - Indian/Maldives - Indian/Mauritius - Indian/Reunion - MET - MST - MST7MDT - PST8PDT - Pacific/Apia - Pacific/Auckland - Pacific/Bougainville - Pacific/Chatham - Pacific/Chuuk - Pacific/Easter - Pacific/Efate - Pacific/Enderbury - Pacific/Fakaofo - Pacific/Fiji - Pacific/Funafuti - Pacific/Galapagos - Pacific/Gambier - Pacific/Guadalcanal - Pacific/Guam - Pacific/Honolulu - Pacific/Kiritimati - Pacific/Kosrae - Pacific/Kwajalein - Pacific/Majuro - Pacific/Marquesas - Pacific/Nauru - Pacific/Niue - Pacific/Norfolk - Pacific/Noumea - Pacific/Pago_Pago - Pacific/Palau - Pacific/Pitcairn - Pacific/Pohnpei - Pacific/Port_Moresby - Pacific/Rarotonga - Pacific/Tahiti - Pacific/Tarawa - Pacific/Tongatapu - Pacific/Wake - Pacific/Wallis - WET - null nullable: true CatalogsFeedProcessingStatus: type: string enum: - COMPLETED - FAILED - PROCESSING CatalogsFeedProductCounts: description: The counts can be null early in the process. type: object properties: ingested: description: The number of products successfully ingested from the feed file. type: integer original: description: The number of products in the feed file. type: integer nullable: true CatalogsFeedUpdateRequestSchema: oneOf: - $ref: '#/components/schemas/CatalogsVerticalFeedsUpdateRequest' - $ref: '#/components/schemas/CatalogsFeedsUpdateRequest' CatalogsFeedValidationDetails: type: object properties: errors: $ref: '#/components/schemas/CatalogsFeedValidationErrors' warnings: $ref: '#/components/schemas/CatalogsFeedValidationWarnings' required: - errors - warnings CatalogsFeedValidationErrors: type: object properties: ADULT_INVALID: description: Some items have invalid adult values. type: integer ADWORDS_FORMAT_INVALID: description: Some adwords links contain too many characters. type: integer AVAILABILITY_INVALID: description: Some items are missing an availability value in their product metadata, those items will not be published. type: integer BLOCKLISTED_IMAGE_SIGNATURE: description: Some items were not published because they don't meet Pinterest's Merchant Guidelines. type: integer DELIMITER_ERROR: description: Your feed includes data with formatting errors. type: integer DESCRIPTION_MISSING: description: Some items are missing a description in their product metadata, those items will not be published. type: integer DUPLICATE_PRODUCTS: description: Some products are duplicated. type: integer ENCODING_ERROR: description: Your feed includes data with an unsupported encoding format. type: integer FEED_LENGTH_TOO_LONG: description: Your feed contains too many items, some items will not be published. type: integer FEED_TOO_SMALL: description: Your feed couldn't be validated because the file doesn't contain the minimum number of lines required. type: integer FETCH_ERROR: description: Pinterest couldn't download your feed. type: integer FETCH_INACTIVE_FEED_ERROR: description: Your feed wasn't ingested because it hasn't changed in the previous 90 days. type: integer IMAGE_LINK_INVALID: description: Some image links are formatted incorrectly. type: integer IMAGE_LINK_LENGTH_TOO_LONG: description: Some items have image_link URLs that contain too many characters, so those items will not be published. type: integer IMAGE_LINK_MISSING: description: Some items are missing an image link URL in their product metadata, those items will not be published. type: integer INTERNAL_SERVICE_ERROR: description: We experienced a technical difficulty and were unable to ingest your feed. The next ingestion will happen in 24 hours. type: integer INVALID_DOMAIN: description: Some of your product link values don't match the verified domain associated with this account. type: integer ITEM_MAIN_IMAGE_DOWNLOAD_FAILURE: description: Some items' main images can't be found. type: integer ITEMID_MISSING: description: Some items are missing an item id in their product metadata, those items will not be published. type: integer LINK_FORMAT_INVALID: description: Some link values are formatted incorrectly. type: integer LINK_LENGTH_TOO_LONG: description: Some product links contain too many characters, those items will not be published. type: integer LIST_PRICE_INVALID: description: Some items have list price formatting errors in their product metadata, those items will not be published. type: integer MALFORMED_XML: description: Your feed couldn't be validated because the xml file is formatted incorrectly. type: integer MAX_ITEMS_PER_ITEM_GROUP_EXCEEDED: description: Some items exceed the maximum number of items per item group, those items will not be published. type: integer NO_VERIFIED_DOMAIN: description: Your merchant domain needs to be claimed. type: integer PARSE_LINE_ERROR: description: Your feed contains formatting errors for some items. type: integer PINJOIN_CONTENT_UNSAFE: description: Some items were not published because they don't meet Pinterest's Merchant Guidelines. type: integer PRICE_CANNOT_BE_DETERMINED: description: Some items were not published because price cannot be determined. The price, list price, and sale price are all different, so those items will not be published. type: integer PRICE_MISSING: description: Some products are missing a price, those items will not be published. type: integer PRODUCT_LINK_MISSING: description: Some items are missing a link URL in their product metadata, those items will not be published. type: integer PRODUCT_PRICE_INVALID: description: Some items have price formatting errors in their product metadata, those items will not be published. type: integer REQUIRED_COLUMNS_MISSING: description: Your feed is missing some required column headers. type: integer TITLE_MISSING: description: Some items are missing a title in their product metadata, those items will not be published. type: integer CatalogsFeedValidationWarnings: type: object properties: AD_IMAGE_0_LINK_DUPLICATED: description: ad_image_0_link is duplicated with another ad image link. type: integer AD_IMAGE_0_LINK_LENGTH_TOO_LONG: description: Ad image link 0 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_0_LINK_REQUIRED: description: Ad image link 0 is required because an image tag was provided. type: integer AD_IMAGE_0_LINK_WARNING: description: Ad image link 0 format is unsupported. type: integer AD_IMAGE_0_TAG_DUPLICATED: description: ad_image_0_tag is duplicated with another ad image tag. type: integer AD_IMAGE_0_TAG_LENGTH_TOO_LONG: description: Ad image tag 0 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_0_TAG_REQUIRED: description: Ad image tag 0 is required because an image link was provided. type: integer AD_IMAGE_10_LINK_DUPLICATED: description: ad_image_10_link is duplicated with another ad image link. type: integer AD_IMAGE_10_LINK_LENGTH_TOO_LONG: description: Ad image link 10 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_10_LINK_REQUIRED: description: Ad image link 10 is required because an image tag was provided. type: integer AD_IMAGE_10_LINK_WARNING: description: Ad image link 10 format is unsupported. type: integer AD_IMAGE_10_TAG_DUPLICATED: description: ad_image_10_tag is duplicated with another ad image tag. type: integer AD_IMAGE_10_TAG_LENGTH_TOO_LONG: description: Ad image tag 10 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_10_TAG_REQUIRED: description: Ad image tag 10 is required because an image link was provided. type: integer AD_IMAGE_11_LINK_DUPLICATED: description: ad_image_11_link is duplicated with another ad image link. type: integer AD_IMAGE_11_LINK_LENGTH_TOO_LONG: description: Ad image link 11 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_11_LINK_REQUIRED: description: Ad image link 11 is required because an image tag was provided. type: integer AD_IMAGE_11_LINK_WARNING: description: Ad image link 11 format is unsupported. type: integer AD_IMAGE_11_TAG_DUPLICATED: description: ad_image_11_tag is duplicated with another ad image tag. type: integer AD_IMAGE_11_TAG_LENGTH_TOO_LONG: description: Ad image tag 11 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_11_TAG_REQUIRED: description: Ad image tag 11 is required because an image link was provided. type: integer AD_IMAGE_12_LINK_DUPLICATED: description: ad_image_12_link is duplicated with another ad image link. type: integer AD_IMAGE_12_LINK_LENGTH_TOO_LONG: description: Ad image link 12 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_12_LINK_REQUIRED: description: Ad image link 12 is required because an image tag was provided. type: integer AD_IMAGE_12_LINK_WARNING: description: Ad image link 12 format is unsupported. type: integer AD_IMAGE_12_TAG_DUPLICATED: description: ad_image_12_tag is duplicated with another ad image tag. type: integer AD_IMAGE_12_TAG_LENGTH_TOO_LONG: description: Ad image tag 12 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_12_TAG_REQUIRED: description: Ad image tag 12 is required because an image link was provided. type: integer AD_IMAGE_13_LINK_DUPLICATED: description: ad_image_13_link is duplicated with another ad image link. type: integer AD_IMAGE_13_LINK_LENGTH_TOO_LONG: description: Ad image link 13 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_13_LINK_REQUIRED: description: Ad image link 13 is required because an image tag was provided. type: integer AD_IMAGE_13_LINK_WARNING: description: Ad image link 13 format is unsupported. type: integer AD_IMAGE_13_TAG_DUPLICATED: description: ad_image_13_tag is duplicated with another ad image tag. type: integer AD_IMAGE_13_TAG_LENGTH_TOO_LONG: description: Ad image tag 13 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_13_TAG_REQUIRED: description: Ad image tag 13 is required because an image link was provided. type: integer AD_IMAGE_14_LINK_DUPLICATED: description: ad_image_14_link is duplicated with another ad image link. type: integer AD_IMAGE_14_LINK_LENGTH_TOO_LONG: description: Ad image link 14 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_14_LINK_REQUIRED: description: Ad image link 14 is required because an image tag was provided. type: integer AD_IMAGE_14_LINK_WARNING: description: Ad image link 14 format is unsupported. type: integer AD_IMAGE_14_TAG_DUPLICATED: description: ad_image_14_tag is duplicated with another ad image tag. type: integer AD_IMAGE_14_TAG_LENGTH_TOO_LONG: description: Ad image tag 14 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_14_TAG_REQUIRED: description: Ad image tag 14 is required because an image link was provided. type: integer AD_IMAGE_15_LINK_DUPLICATED: description: ad_image_15_link is duplicated with another ad image link. type: integer AD_IMAGE_15_LINK_LENGTH_TOO_LONG: description: Ad image link 15 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_15_LINK_REQUIRED: description: Ad image link 15 is required because an image tag was provided. type: integer AD_IMAGE_15_LINK_WARNING: description: Ad image link 15 format is unsupported. type: integer AD_IMAGE_15_TAG_DUPLICATED: description: ad_image_15_tag is duplicated with another ad image tag. type: integer AD_IMAGE_15_TAG_LENGTH_TOO_LONG: description: Ad image tag 15 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_15_TAG_REQUIRED: description: Ad image tag 15 is required because an image link was provided. type: integer AD_IMAGE_16_LINK_DUPLICATED: description: ad_image_16_link is duplicated with another ad image link. type: integer AD_IMAGE_16_LINK_LENGTH_TOO_LONG: description: Ad image link 16 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_16_LINK_REQUIRED: description: Ad image link 16 is required because an image tag was provided. type: integer AD_IMAGE_16_LINK_WARNING: description: Ad image link 16 format is unsupported. type: integer AD_IMAGE_16_TAG_DUPLICATED: description: ad_image_16_tag is duplicated with another ad image tag. type: integer AD_IMAGE_16_TAG_LENGTH_TOO_LONG: description: Ad image tag 16 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_16_TAG_REQUIRED: description: Ad image tag 16 is required because an image link was provided. type: integer AD_IMAGE_17_LINK_DUPLICATED: description: ad_image_17_link is duplicated with another ad image link. type: integer AD_IMAGE_17_LINK_LENGTH_TOO_LONG: description: Ad image link 17 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_17_LINK_REQUIRED: description: Ad image link 17 is required because an image tag was provided. type: integer AD_IMAGE_17_LINK_WARNING: description: Ad image link 17 format is unsupported. type: integer AD_IMAGE_17_TAG_DUPLICATED: description: ad_image_17_tag is duplicated with another ad image tag. type: integer AD_IMAGE_17_TAG_LENGTH_TOO_LONG: description: Ad image tag 17 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_17_TAG_REQUIRED: description: Ad image tag 17 is required because an image link was provided. type: integer AD_IMAGE_18_LINK_DUPLICATED: description: ad_image_18_link is duplicated with another ad image link. type: integer AD_IMAGE_18_LINK_LENGTH_TOO_LONG: description: Ad image link 18 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_18_LINK_REQUIRED: description: Ad image link 18 is required because an image tag was provided. type: integer AD_IMAGE_18_LINK_WARNING: description: Ad image link 18 format is unsupported. type: integer AD_IMAGE_18_TAG_DUPLICATED: description: ad_image_18_tag is duplicated with another ad image tag. type: integer AD_IMAGE_18_TAG_LENGTH_TOO_LONG: description: Ad image tag 18 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_18_TAG_REQUIRED: description: Ad image tag 18 is required because an image link was provided. type: integer AD_IMAGE_19_LINK_DUPLICATED: description: ad_image_19_link is duplicated with another ad image link. type: integer AD_IMAGE_19_LINK_LENGTH_TOO_LONG: description: Ad image link 19 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_19_LINK_REQUIRED: description: Ad image link 19 is required because an image tag was provided. type: integer AD_IMAGE_19_LINK_WARNING: description: Ad image link 19 format is unsupported. type: integer AD_IMAGE_19_TAG_DUPLICATED: description: ad_image_19_tag is duplicated with another ad image tag. type: integer AD_IMAGE_19_TAG_LENGTH_TOO_LONG: description: Ad image tag 19 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_19_TAG_REQUIRED: description: Ad image tag 19 is required because an image link was provided. type: integer AD_IMAGE_1_LINK_DUPLICATED: description: ad_image_1_link is duplicated with another ad image link. type: integer AD_IMAGE_1_LINK_LENGTH_TOO_LONG: description: Ad image link 1 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_1_LINK_REQUIRED: description: Ad image link 1 is required because an image tag was provided. type: integer AD_IMAGE_1_LINK_WARNING: description: Ad image link 1 format is unsupported. type: integer AD_IMAGE_1_TAG_DUPLICATED: description: ad_image_1_tag is duplicated with another ad image tag. type: integer AD_IMAGE_1_TAG_LENGTH_TOO_LONG: description: Ad image tag 1 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_1_TAG_REQUIRED: description: Ad image tag 1 is required because an image link was provided. type: integer AD_IMAGE_2_LINK_DUPLICATED: description: ad_image_2_link is duplicated with another ad image link. type: integer AD_IMAGE_2_LINK_LENGTH_TOO_LONG: description: Ad image link 2 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_2_LINK_REQUIRED: description: Ad image link 2 is required because an image tag was provided. type: integer AD_IMAGE_2_LINK_WARNING: description: Ad image link 2 format is unsupported. type: integer AD_IMAGE_2_TAG_DUPLICATED: description: ad_image_2_tag is duplicated with another ad image tag. type: integer AD_IMAGE_2_TAG_LENGTH_TOO_LONG: description: Ad image tag 2 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_2_TAG_REQUIRED: description: Ad image tag 2 is required because an image link was provided. type: integer AD_IMAGE_3_LINK_DUPLICATED: description: ad_image_3_link is duplicated with another ad image link. type: integer AD_IMAGE_3_LINK_LENGTH_TOO_LONG: description: Ad image link 3 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_3_LINK_REQUIRED: description: Ad image link 3 is required because an image tag was provided. type: integer AD_IMAGE_3_LINK_WARNING: description: Ad image link 3 format is unsupported. type: integer AD_IMAGE_3_TAG_DUPLICATED: description: ad_image_3_tag is duplicated with another ad image tag. type: integer AD_IMAGE_3_TAG_LENGTH_TOO_LONG: description: Ad image tag 3 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_3_TAG_REQUIRED: description: Ad image tag 3 is required because an image link was provided. type: integer AD_IMAGE_4_LINK_DUPLICATED: description: ad_image_4_link is duplicated with another ad image link. type: integer AD_IMAGE_4_LINK_LENGTH_TOO_LONG: description: Ad image link 4 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_4_LINK_REQUIRED: description: Ad image link 4 is required because an image tag was provided. type: integer AD_IMAGE_4_LINK_WARNING: description: Ad image link 4 format is unsupported. type: integer AD_IMAGE_4_TAG_DUPLICATED: description: ad_image_4_tag is duplicated with another ad image tag. type: integer AD_IMAGE_4_TAG_LENGTH_TOO_LONG: description: Ad image tag 4 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_4_TAG_REQUIRED: description: Ad image tag 4 is required because an image link was provided. type: integer AD_IMAGE_5_LINK_DUPLICATED: description: ad_image_5_link is duplicated with another ad image link. type: integer AD_IMAGE_5_LINK_LENGTH_TOO_LONG: description: Ad image link 5 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_5_LINK_REQUIRED: description: Ad image link 5 is required because an image tag was provided. type: integer AD_IMAGE_5_LINK_WARNING: description: Ad image link 5 format is unsupported. type: integer AD_IMAGE_5_TAG_DUPLICATED: description: ad_image_5_tag is duplicated with another ad image tag. type: integer AD_IMAGE_5_TAG_LENGTH_TOO_LONG: description: Ad image tag 5 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_5_TAG_REQUIRED: description: Ad image tag 5 is required because an image link was provided. type: integer AD_IMAGE_6_LINK_DUPLICATED: description: ad_image_6_link is duplicated with another ad image link. type: integer AD_IMAGE_6_LINK_LENGTH_TOO_LONG: description: Ad image link 6 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_6_LINK_REQUIRED: description: Ad image link 6 is required because an image tag was provided. type: integer AD_IMAGE_6_LINK_WARNING: description: Ad image link 6 format is unsupported. type: integer AD_IMAGE_6_TAG_DUPLICATED: description: ad_image_6_tag is duplicated with another ad image tag. type: integer AD_IMAGE_6_TAG_LENGTH_TOO_LONG: description: Ad image tag 6 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_6_TAG_REQUIRED: description: Ad image tag 6 is required because an image link was provided. type: integer AD_IMAGE_7_LINK_DUPLICATED: description: ad_image_7_link is duplicated with another ad image link. type: integer AD_IMAGE_7_LINK_LENGTH_TOO_LONG: description: Ad image link 7 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_7_LINK_REQUIRED: description: Ad image link 7 is required because an image tag was provided. type: integer AD_IMAGE_7_LINK_WARNING: description: Ad image link 7 format is unsupported. type: integer AD_IMAGE_7_TAG_DUPLICATED: description: ad_image_7_tag is duplicated with another ad image tag. type: integer AD_IMAGE_7_TAG_LENGTH_TOO_LONG: description: Ad image tag 7 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_7_TAG_REQUIRED: description: Ad image tag 7 is required because an image link was provided. type: integer AD_IMAGE_8_LINK_DUPLICATED: description: ad_image_8_link is duplicated with another ad image link. type: integer AD_IMAGE_8_LINK_LENGTH_TOO_LONG: description: Ad image link 8 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_8_LINK_REQUIRED: description: Ad image link 8 is required because an image tag was provided. type: integer AD_IMAGE_8_LINK_WARNING: description: Ad image link 8 format is unsupported. type: integer AD_IMAGE_8_TAG_DUPLICATED: description: ad_image_8_tag is duplicated with another ad image tag. type: integer AD_IMAGE_8_TAG_LENGTH_TOO_LONG: description: Ad image tag 8 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_8_TAG_REQUIRED: description: Ad image tag 8 is required because an image link was provided. type: integer AD_IMAGE_9_LINK_DUPLICATED: description: ad_image_9_link is duplicated with another ad image link. type: integer AD_IMAGE_9_LINK_LENGTH_TOO_LONG: description: Ad image link 9 length is too long. The maximum length is 2047 characters. type: integer AD_IMAGE_9_LINK_REQUIRED: description: Ad image link 9 is required because an image tag was provided. type: integer AD_IMAGE_9_LINK_WARNING: description: Ad image link 9 format is unsupported. type: integer AD_IMAGE_9_TAG_DUPLICATED: description: ad_image_9_tag is duplicated with another ad image tag. type: integer AD_IMAGE_9_TAG_LENGTH_TOO_LONG: description: Ad image tag 9 length is too long. The maximum length is 511 characters. type: integer AD_IMAGE_9_TAG_REQUIRED: description: Ad image tag 9 is required because an image link was provided. type: integer AD_LINK_FORMAT_WARNING: description: Some items have ad links that are formatted incorrectly. type: integer AD_LINK_SAME_AS_LINK: description: Some items have ad link URLs that are duplicates of the link URLs for those items. type: integer AD_VIDEO_0_LINK_DUPLICATED: description: ad_video_0_link is duplicated with another ad video link. type: integer AD_VIDEO_0_LINK_LENGTH_TOO_LONG: description: ad_video_0_link length is too long. The maximum length is 511 characters. type: integer AD_VIDEO_0_LINK_REQUIRED: description: ad_video_0_link is required for this item because ad_video_0_tag was provided. type: integer AD_VIDEO_0_LINK_WARNING: description: ad_video_0_link is formatted incorrectly and will not be published with your items. type: integer AD_VIDEO_0_TAG_DUPLICATED: description: ad_video_0_tag is duplicated with another ad video tag. type: integer AD_VIDEO_0_TAG_LENGTH_TOO_LONG: description: ad_video_0_tag length is too long. The maximum length is 511 characters. type: integer AD_VIDEO_0_TAG_REQUIRED: description: ad_video_0_tag is required because ad_video_0_link was provided. type: integer AD_VIDEO_1_LINK_DUPLICATED: description: ad_video_1_link is duplicated with another ad video link. type: integer AD_VIDEO_1_LINK_LENGTH_TOO_LONG: description: ad_video_1_link length is too long. The maximum length is 511 characters. type: integer AD_VIDEO_1_LINK_REQUIRED: description: ad_video_1_link is required for this item because ad_video_1_tag was provided. type: integer AD_VIDEO_1_LINK_WARNING: description: ad_video_1_link is formatted incorrectly and will not be published with your items. type: integer AD_VIDEO_1_TAG_DUPLICATED: description: ad_video_1_tag is duplicated with another ad video tag. type: integer AD_VIDEO_1_TAG_LENGTH_TOO_LONG: description: ad_video_1_tag length is too long. The maximum length is 511 characters. type: integer AD_VIDEO_1_TAG_REQUIRED: description: ad_video_1_tag is required because ad_video_1_link was provided. type: integer AD_VIDEO_2_LINK_DUPLICATED: description: ad_video_2_link is duplicated with another ad video link. type: integer AD_VIDEO_2_LINK_LENGTH_TOO_LONG: description: ad_video_2_link length is too long. The maximum length is 511 characters. type: integer AD_VIDEO_2_LINK_REQUIRED: description: ad_video_2_link is required for this item because ad_video_2_tag was provided. type: integer AD_VIDEO_2_LINK_WARNING: description: ad_video_2_link is formatted incorrectly and will not be published with your items. type: integer AD_VIDEO_2_TAG_DUPLICATED: description: ad_video_2_tag is duplicated with another ad video tag. type: integer AD_VIDEO_2_TAG_LENGTH_TOO_LONG: description: ad_video_2_tag length is too long. The maximum length is 511 characters. type: integer AD_VIDEO_2_TAG_REQUIRED: description: ad_video_2_tag is required because ad_video_2_link was provided. type: integer ADDITIONAL_IMAGE_LINK_LENGTH_TOO_LONG: description: Some items have additional_image_link URLs that contain too many characters, so those items will not be published. type: integer ADDITIONAL_IMAGE_LINK_WARNING: description: Some items have additional_image_link URLs that are formatted incorrectly and will not be published with your items. type: integer ADWORDS_FORMAT_WARNING: description: Some items have adwords_redirect links that are formatted incorrectly. type: integer ADWORDS_SAME_AS_LINK: description: Some items have adwords_redirect URLs that are duplicates of the link URLs for those items. type: integer AGE_GROUP_INVALID: description: Some items have age group values that are formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences. type: integer ANDROID_DEEP_LINK_INVALID: description: Some items include invalid android_deep_link. type: integer AVAILABILITY_DATE_INVALID: description: Some items have availability_date values that are formatted incorrectly, those items will be published without an availability date. type: integer COUNTRY_DOES_NOT_MAP_TO_CURRENCY: description: Some items include a currency that doesn't match the usual currency for the location where that product is sold or shipped. type: integer CUSTOM_LABEL_LENGTH_TOO_LONG: description: Some items have custom_label values that are too long, those items will be published without that custom label. type: integer DESCRIPTION_LENGTH_TOO_LONG: description: The description for some items were truncated because they contain too many characters. type: integer DUPLICATE_HEADERS: description: Your feed contains duplicate headers. type: integer EXPIRATION_DATE_INVALID: description: Some items have expiration_date values that are formatted incorrectly, those items will be published without an expiration date. type: integer FETCH_SAME_SIGNATURE: description: Ingestion completed early because there are no changes to your feed since the last successful update. type: integer GENDER_INVALID: description: Some items have gender values that are formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences. type: integer GTIN_INVALID: description: Some items include incorrectly formatted GTINs. type: integer IMAGE_LINK_WARNING: description: Some items have image_link URLs that are formatted incorrectly and will not be published with those items. type: integer INCONSISTENT_CURRENCY_VALUES: description: Some items include inconsistent currencies in price fields. type: integer INDEXED_PRODUCT_COUNT_LARGE_DELTA: description: The product count has increased or decreased significantly compared to the last successful ingestion. type: integer IOS_DEEP_LINK_INVALID: description: Some items include invalid ios_deep_link values. type: integer IS_BUNDLE_INVALID: description: Some items have is_bundle values that are formatted incorrectly, those items will be published without being bundled with other products. type: integer ITEM_ADDITIONAL_IMAGE_DOWNLOAD_FAILURE: description: Some items include additional_image_links that can't be found. type: integer LINK_FORMAT_WARNING: description: Some items have an invalid product link which contains invalid UTM tracking paramaters. type: integer MIN_AD_PRICE_INVALID: description: Some items include min_ad_price values that are formatted incorrectly. type: integer MPN_INVALID: description: Some items include incorrectly formatted MPNs. type: integer MULTIPACK_INVALID: description: Some items have invalid multipack values. type: integer OPTIONAL_CONDITION_INVALID: description: Some items include condition values that are formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences. type: integer OPTIONAL_CONDITION_MISSING: description: Some items are missing a condition value, which may limit visibility in recommendations, search results and shopping experiences. type: integer OPTIONAL_PRODUCT_CATEGORY_INVALID: description: Some items include google_product_category values that are not formatted correctly according to the GPC taxonomy. type: integer OPTIONAL_PRODUCT_CATEGORY_MISSING: description: Some items are missing a google_product_category. type: integer PRODUCT_CATEGORY_DEPTH_WARNING: description: Some items only have 1 or 2 levels of google_product_category values, which may limit visibility in recommendations, search results and shopping experiences. type: integer PRODUCT_TYPE_LENGTH_TOO_LONG: description: Some items have product_type values that are too long, those items will be published without that product type. type: integer SALE_DATE_INVALID: description: Some items have sale_price_effective_date values that are formatted incorrectly, those items will be published without a sale date. type: integer SALES_PRICE_INVALID: description: Some items have sale price values that are higher than the original price of the item. type: integer SALES_PRICE_TOO_HIGH: description: Some items include a sales price that is higher than the list price. The sales price has been defaulted to the list price. type: integer SALES_PRICE_TOO_LOW: description: Some items include sales price that is much lower than the list price. type: integer SHIPPING_HEIGHT_INVALID: description: Some items include incorrectly formatted shipping_height. type: integer SHIPPING_INVALID: description: Some items have shipping values that are formatted incorrectly. type: integer SHIPPING_WEIGHT_INVALID: description: Some items have invalid shipping_weight values. type: integer SHIPPING_WIDTH_INVALID: description: Some items include incorrectly formatted shipping_width. type: integer SIZE_SYSTEM_INVALID: description: Some items have size system values which are not one of the supported size systems. type: integer SIZE_TYPE_INVALID: description: Some items have size type values that are formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences. type: integer TAX_INVALID: description: Some items have tax values that are formatted incorrectly. type: integer TITLE_LENGTH_TOO_LONG: description: The title for some items were truncated because they contain too many characters. type: integer TOO_MANY_ADDITIONAL_IMAGE_LINKS: description: Some items have additional_image_link values that exceed the limit for additional images, those items will be published without some of your images. type: integer UPDATED_TIME_INVALID: description: Some items have updated_time values thate are formatted incorrectly, those items will be published without an updated time. type: integer UTM_SOURCE_AUTO_CORRECTED: description: Some items include utm_source values that are formatted incorrectly and have been automatically corrected. type: integer VIDEO_REQUIRED_WHEN_AD_VIDEO_PROVIDED: description: A video is required in the item when ad_video fields are provided. type: integer WEIGHT_UNIT_INVALID: description: Some items have weight_unit values that are formatted incorrectly, those items will be published without a weight unit. type: integer CatalogsFeedVideoCounts: description: Counts of total, ingested, and not ingested videos in the feed file. The counts may not appear early in the process. type: object properties: ingested_videos: description: The number of videos successfully ingested from the feed file. type: integer not_ingested_videos: description: The number of videos that were not ingested from the feed file. type: integer total_videos: description: The number of videos in the feed file. type: integer CatalogsFeedsCreateRequest: description: Request object for creating a feed. Please, be aware that "default_country" and "default_locale" are not required in the spec for forward compatibility but for now the API will not accept requests without those fields. type: object properties: credentials: $ref: '#/components/schemas/CatalogsFeedCredentials' default_availability: $ref: '#/components/schemas/ProductAvailabilityType' default_country: $ref: '#/components/schemas/Country' default_currency: $ref: '#/components/schemas/NullableCurrency' default_locale: description: The locale used within a feed for product descriptions. anyOf: - $ref: '#/components/schemas/CatalogsLocale' - $ref: '#/components/schemas/DeprecatedCatalogFeedsCreateRequestDefaultLocale' format: $ref: '#/components/schemas/CatalogsFormat' location: $ref: '#/components/schemas/FeedLocation' name: $ref: '#/components/schemas/FeedDisplayName' preferred_processing_schedule: $ref: '#/components/schemas/CatalogsFeedProcessingSchedule' status: default: ACTIVE allOf: - $ref: '#/components/schemas/CatalogsStatus' additionalProperties: false required: - format - location - name title: legacy_retail_only CatalogsFeedsUpdateRequest: description: Request object for updating a feed. type: object properties: credentials: $ref: '#/components/schemas/CatalogsFeedCredentials' default_availability: $ref: '#/components/schemas/ProductAvailabilityType' default_currency: $ref: '#/components/schemas/NullableCurrency' format: $ref: '#/components/schemas/CatalogsFormat' location: $ref: '#/components/schemas/FeedLocation' name: $ref: '#/components/schemas/FeedDisplayName' preferred_processing_schedule: $ref: '#/components/schemas/CatalogsFeedProcessingSchedule' status: $ref: '#/components/schemas/CatalogsStatus' additionalProperties: false title: legacy_retail_only CatalogsFormat: description: The file format of a feed. type: string enum: - TSV - CSV - XML - INTEGRATION CatalogsHotelAddress: type: object properties: addr1: description: Primary street address of hotel. type: string city: description: City where the hotel is located. type: string country: description: Country where the hotel is located. type: string postal_code: description: Required for countries with a postal code system. Postal or zip code of the hotel. type: string region: description: State, county, province, where the hotel is located. type: string CatalogsHotelAttributes: type: object properties: additional_image_link: description: <= 2000 characters. The links to additional images for your hotel. Up to ten additional images can be used to show a hotel from different angles. Must begin with http:// or https://. type: array items: type: string example: - https://scene.example.com/image/image_v2.jpg - https://scene.example.com/image/image_v3.jpg nullable: true ai_disclosures: description: AI content disclosures for individual assets (main_image.link or additional_image_link) on this hotel item. Each entry declares which disclosure types apply to a single asset URL. type: array items: $ref: '#/components/schemas/CatalogsAiContentDisclosure' example: - url: https://scene.example.com/image/image_v3.jpg disclosure: - ai_modified main_image: description: The main hotel image allOf: - $ref: '#/components/schemas/CatalogsHotelMainImage' allOf: - $ref: '#/components/schemas/CatalogsUpdatableHotelAttributes' CatalogsHotelAvailableFilterValues: type: object properties: catalog_type: type: string enum: - HOTEL filter_values: $ref: '#/components/schemas/CatalogsHotelFilterValuesMap' required: - catalog_type - filter_values title: catalogs_hotel_available_filter_values CatalogsHotelBatchItem: description: Hotel batch item type: object discriminator: propertyName: operation mapping: CREATE: '#/components/schemas/CatalogsCreateHotelItem' UPSERT: '#/components/schemas/CatalogsUpsertHotelItem' UPDATE: '#/components/schemas/CatalogsUpdateHotelItem' DELETE: '#/components/schemas/CatalogsDeleteHotelItem' oneOf: - $ref: '#/components/schemas/CatalogsCreateHotelItem' - $ref: '#/components/schemas/CatalogsUpsertHotelItem' - $ref: '#/components/schemas/CatalogsUpdateHotelItem' - $ref: '#/components/schemas/CatalogsDeleteHotelItem' CatalogsHotelBatchRequest: description: Request object to update catalogs hotel items type: object properties: catalog_id: description: Catalog id pertaining to the hotel item. If not provided, default to oldest hotel catalog example: '2680059592705' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' catalog_type: type: string enum: - HOTEL country: $ref: '#/components/schemas/Country' items: description: Array with catalogs item operations type: array items: $ref: '#/components/schemas/CatalogsHotelBatchItem' maxItems: 1000 minItems: 1 language: description: We recommend using the CatalogsLocale values. anyOf: - $ref: '#/components/schemas/CatalogsLocale' - $ref: '#/components/schemas/Language' required: - catalog_type - country - items - language CatalogsHotelFeed: description: Catalogs Hotel Feed object type: object properties: catalog_id: description: Catalog id pertaining to the feed. If not provided, feed will use a default catalog based on type. type: string nullable: true pattern: ^\d+$ catalog_type: type: string enum: - HOTEL created_at: type: string format: date-time readOnly: true credentials: $ref: '#/components/schemas/CatalogsFeedCredentials' default_currency: $ref: '#/components/schemas/NullableCurrency' default_locale: description: The locale used within a feed for product descriptions. type: string format: $ref: '#/components/schemas/CatalogsFormat' id: description: ID of the feed entity. type: string example: '864344156814050986' pattern: ^\d+$ readOnly: true location: description: The URL where a feed is available for download. This URL is what Pinterest will use to download a feed for processing. type: string pattern: ^(http|https|ftp|sftp):// name: description: A human-friendly name associated to a given feed. This value is currently nullable due to historical reasons. It is expected to become non-nullable in the future. type: string nullable: true preferred_processing_schedule: $ref: '#/components/schemas/CatalogsFeedProcessingSchedule' status: $ref: '#/components/schemas/CatalogsStatus' updated_at: type: string format: date-time readOnly: true required: - id - default_locale - location - name - created_at - updated_at - format - status - catalog_type - catalog_id title: catalogs_hotel_feed CatalogsHotelFeedsCreateRequest: description: Request object for creating a feed. Please, be aware that "default_country" and "default_locale" are not required in the spec for forward compatibility but for now the API will not accept requests without those fields. type: object properties: catalog_id: description: Catalog id pertaining to the feed. If not provided, feed will use a default catalog based on type. type: string pattern: ^\d+$ catalog_type: type: string enum: - HOTEL credentials: $ref: '#/components/schemas/CatalogsFeedCredentials' default_currency: $ref: '#/components/schemas/NullableCurrency' default_locale: description: The locale used within a feed for product descriptions. anyOf: - $ref: '#/components/schemas/CatalogsLocale' - $ref: '#/components/schemas/DeprecatedCatalogFeedsCreateRequestDefaultLocale' format: $ref: '#/components/schemas/CatalogsFormat' location: $ref: '#/components/schemas/FeedLocation' name: $ref: '#/components/schemas/FeedDisplayName' preferred_processing_schedule: $ref: '#/components/schemas/CatalogsFeedProcessingSchedule' status: default: ACTIVE allOf: - $ref: '#/components/schemas/CatalogsStatus' additionalProperties: false required: - default_locale - format - location - name - catalog_type title: feeds_hotel_create_request CatalogsHotelFeedsUpdateRequest: description: Request object for updating a feed. type: object properties: catalog_type: type: string enum: - HOTEL credentials: $ref: '#/components/schemas/CatalogsFeedCredentials' default_currency: $ref: '#/components/schemas/NullableCurrency' format: $ref: '#/components/schemas/CatalogsFormat' location: $ref: '#/components/schemas/FeedLocation' name: $ref: '#/components/schemas/FeedDisplayName' preferred_processing_schedule: $ref: '#/components/schemas/CatalogsFeedProcessingSchedule' status: $ref: '#/components/schemas/CatalogsStatus' additionalProperties: false required: - catalog_type title: catalogs_feeds_update_request CatalogsHotelFilterValuesMap: description: A map of filter attributes to their available values. type: object properties: brand: type: array items: type: string custom_label_0: type: array items: type: string custom_label_1: type: array items: type: string custom_label_2: type: array items: type: string custom_label_3: type: array items: type: string custom_label_4: type: array items: type: string title: catalogs_hotel_filter_values_map CatalogsHotelGuestRatings: type: object properties: max_score: description: Max value for the hotel rating score. type: number nullable: true number_of_reviewers: description: Total number of people who have rated this hotel. type: integer nullable: true rating_system: description: System you use for guest reviews. type: string nullable: true score: description: Your hotel's rating. type: number nullable: true CatalogsHotelItemErrorResponse: description: Object describing a hotel item error type: object properties: catalog_type: type: string enum: - HOTEL errors: description: Array with the errors for the item id requested type: array items: $ref: '#/components/schemas/ItemValidationEvent' hotel_id: description: The catalog hotel id in the merchant namespace type: string example: DS0294-M item_response_kind: description: Discriminator literal identifying this leaf inside an `ItemResponse` payload. type: string enum: - hotel_item_error additionalProperties: false required: - catalog_type - item_response_kind - errors title: catalogs_hotel_item_error_response CatalogsHotelItemResponse: description: Object describing a hotel record type: object properties: attributes: $ref: '#/components/schemas/CatalogsHotelAttributes' catalog_type: type: string enum: - HOTEL hotel_id: description: The catalog hotel id in the merchant namespace type: string example: DS0294-M item_response_kind: description: Discriminator literal identifying this leaf inside an `ItemResponse` payload. type: string enum: - hotel_item pins: description: The pins mapped to the item type: array items: $ref: '#/components/schemas/Pin' maxItems: 11 nullable: true additionalProperties: false required: - catalog_type - item_response_kind title: catalogs_hotel_item_response CatalogsHotelItemsBatch: description: Object describing the catalogs hotel items batch. If specified, you must provide all properties. type: object properties: batch_id: description: Id of the catalogs items batch example: '595953100599279259' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' catalog_type: type: string enum: - HOTEL completed_time: description: "Date and time (UTC) of the batch completion: YYYY-MM-DD'T'hh:mm:ss" type: string format: date-time example: 2024-01-01T20:20:00Z nullable: true created_time: description: "Date and time (UTC) of the batch creation: YYYY-MM-DD'T'hh:mm:ss" type: string format: date-time example: 2024-01-01T20:10:40Z items: description: Array with the catalogs items processing records part of the catalogs items batch type: array items: $ref: '#/components/schemas/HotelProcessingRecord' status: $ref: '#/components/schemas/BatchOperationStatus' required: - catalog_type CatalogsHotelItemsPostFilter: type: object properties: catalog_id: description: Catalog id pertaining to the hotel item. If not provided, default to oldest hotel catalog type: string pattern: ^\d+$ catalog_type: type: string enum: - HOTEL hotel_ids: type: array items: type: string maxItems: 1000 minItems: 1 required: - catalog_type - hotel_ids CatalogsHotelListProductsByCatalogBasedFilterRequest: description: Request object to list products for a given hotel catalog_id and product group filter. type: object properties: catalog_id: description: Catalog ID pertaining to the product group. example: '2680059592705' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' catalog_type: type: string enum: - HOTEL filters: $ref: '#/components/schemas/CatalogsHotelProductGroupFilters' additionalProperties: false required: - catalog_id - catalog_type - filters title: hotel_list_products_by_catalog_based_filter_request CatalogsHotelMainImage: description: The main hotel image type: object properties: link: description: <= 2000 characters. The link to the main hotel image. Image should be at least 75x75 pixels to avoid errors. Must start with http:// or https://. type: string tag: description: Tag appended to the image that identifies image category or details. There can be multiple tags associated with an image type: array items: type: string nullable: true CatalogsHotelProduct: type: object properties: catalog_type: type: string enum: - HOTEL metadata: $ref: '#/components/schemas/CatalogsHotelProductMetadata' pin: $ref: '#/components/schemas/Pin' required: - catalog_type - metadata - pin CatalogsHotelProductGroup: type: object properties: catalog_id: description: Catalog ID pertaining to the product group. example: '2680059592705' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' catalog_type: type: string enum: - HOTEL created_at: description: Unix timestamp in seconds of when catalog product group was created. type: integer example: 1621350033000 description: type: string nullable: true filters: $ref: '#/components/schemas/CatalogsHotelProductGroupFilters' id: description: ID of the catalog product group. example: '443727193917' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' name: description: Name of catalog product group type: string example: Most Popular type: $ref: '#/components/schemas/CatalogsHotelProductGroupType' updated_at: description: Unix timestamp in seconds of last time catalog product group was updated. type: integer example: 1622742155000 required: - catalog_id - id - catalog_type - filters - type title: hotel_product_group CatalogsHotelProductGroupCreateRequest: description: Request object for creating a hotel product group. type: object properties: catalog_id: description: Catalog ID pertaining to the product group. example: '2680059592705' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' catalog_type: type: string enum: - HOTEL description: type: string nullable: true filters: $ref: '#/components/schemas/CatalogsHotelProductGroupFilters' name: type: string additionalProperties: false required: - catalog_id - name - catalog_type - filters title: hotel_product_groups_create_request CatalogsHotelProductGroupFilterKeys: anyOf: - $ref: '#/components/schemas/PriceFilter' - $ref: '#/components/schemas/HotelIdFilter' - $ref: '#/components/schemas/BrandFilter' - $ref: '#/components/schemas/CustomLabel0Filter' - $ref: '#/components/schemas/CustomLabel1Filter' - $ref: '#/components/schemas/CustomLabel2Filter' - $ref: '#/components/schemas/CustomLabel3Filter' - $ref: '#/components/schemas/CustomLabel4Filter' - $ref: '#/components/schemas/CountryFilter' - $ref: '#/components/schemas/TitleKeywordsFilter' title: catalogs_product_group_keys CatalogsHotelProductGroupFilters: description: Object holding a group of filters for a hotel product group anyOf: - $ref: '#/components/schemas/CatalogsHotelProductGroupFiltersAnyOf' - $ref: '#/components/schemas/CatalogsHotelProductGroupFiltersAllOf' title: catalogs_product_group_filters CatalogsHotelProductGroupFiltersAllOf: type: object properties: all_of: type: array items: $ref: '#/components/schemas/CatalogsHotelProductGroupFilterKeys' additionalProperties: false required: - all_of title: all_of CatalogsHotelProductGroupFiltersAnyOf: type: object properties: any_of: type: array items: $ref: '#/components/schemas/CatalogsHotelProductGroupFilterKeys' additionalProperties: false required: - any_of title: any_of CatalogsHotelProductGroupProductCounts: description: Product counts for a Hotel CatalogsProductGroup type: object properties: catalog_type: type: string enum: - HOTEL total: type: number minimum: 0 required: - catalog_type - total title: catalogs_hotel_product_group_product_counts CatalogsHotelProductGroupType: description: Catalog hotel product group type type: string example: MERCHANT_CREATED enum: - MERCHANT_CREATED - ALL_LISTINGS title: hotel_product_group_type CatalogsHotelProductGroupUpdateRequest: description: Request object for updating a hotel product group. type: object properties: catalog_type: type: string enum: - HOTEL description: type: string nullable: true filters: $ref: '#/components/schemas/CatalogsHotelProductGroupFilters' name: description: Name of catalog product group type: string example: Most Popular additionalProperties: false title: hotel_product_groups_update_request CatalogsHotelProductMetadata: description: Hotel product metadata entity type: object properties: hotel_id: description: The user-created unique ID that represents the hotel item. type: string example: 123abc required: - hotel_id CatalogsHotelReportParameters: description: Parameters for hotel report type: object properties: catalog_type: type: string enum: - HOTEL report: $ref: '#/components/schemas/CatalogsHotelReportParametersReport' required: - catalog_type - report CatalogsHotelReportParametersReport: type: object discriminator: propertyName: report_type mapping: FEED_INGESTION_ISSUES: '#/components/schemas/CatalogsReportFeedIngestionFilter' DISTRIBUTION_ISSUES: '#/components/schemas/CatalogsReportDistributionIssueFilter' oneOf: - $ref: '#/components/schemas/CatalogsReportFeedIngestionFilter' - $ref: '#/components/schemas/CatalogsReportDistributionIssueFilter' CatalogsHotelReportStatsParameters: description: Parameters for hotel report type: object properties: catalog_type: type: string enum: - HOTEL report: $ref: '#/components/schemas/CatalogsHotelReportStatsParametersReport' required: - catalog_type - report CatalogsHotelReportStatsParametersReport: type: object discriminator: propertyName: report_type mapping: FEED_INGESTION_ISSUES: '#/components/schemas/CatalogsReportFeedIngestionFilter' DISTRIBUTION_ISSUES: '#/components/schemas/CatalogsReportDistributionIssueFilter' oneOf: - $ref: '#/components/schemas/CatalogsReportFeedIngestionFilter' - $ref: '#/components/schemas/CatalogsReportDistributionIssueFilter' CatalogsItemValidationDetails: type: object properties: attribute_name: description: Attribute that has a validation issue. allOf: - $ref: '#/components/schemas/NullableCatalogsItemFieldType' provided_value: description: Provided value that caused the validation issue. type: string nullable: true required: - attribute_name - provided_value CatalogsItemValidationErrors: type: object properties: ADULT_INVALID: description: Item has an invalid adult value. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' ADWORDS_FORMAT_INVALID: description: Adword link contains too many characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AVAILABILITY_INVALID: description: Item is missing availability value in its product metadata, this item will not be published. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' BLOCKLISTED_IMAGE_SIGNATURE: description: Item will not be published because it doesn't meet Pinterest's Merchant Guidelines. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' DESCRIPTION_MISSING: description: Item is missing description in its product metadata, this item will not be published. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' DUPLICATE_PRODUCTS: description: This product is duplicated. The duplicate entry will not be published. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' IMAGE_LINK_INVALID: description: Image link is invalid. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' IMAGE_LINK_LENGTH_TOO_LONG: description: Item has image_link URL that contains too many characters, so the item will not be published. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' IMAGE_LINK_MISSING: description: Item is missing an image link URL in its product metadata, this item will not be published. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' INVALID_DOMAIN: description: Product link value doesn't match the verified domain associated with this account. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' ITEM_MAIN_IMAGE_DOWNLOAD_FAILURE: description: Main image can't be found. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' ITEMID_MISSING: description: Item is missing item id in its product metadata, this item will not be published. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' LINK_FORMAT_INVALID: description: Link is invalid. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' LINK_LENGTH_TOO_LONG: description: Product link contains too many characters, this item will not be published. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' LIST_PRICE_INVALID: description: Item has a list price formatting error, this item will not be published. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' MAX_ITEMS_PER_ITEM_GROUP_EXCEEDED: description: Item exceed the maximum number of items per item group, this item will not be published. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' PARSE_LINE_ERROR: description: Item contains formating errors. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' PINJOIN_CONTENT_UNSAFE: description: Item will not be published because it doesn't meet Pinterest's Merchant Guidelines. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' PRICE_CANNOT_BE_DETERMINED: description: Item price cannot be determined because the price, list price, and sale price are all different. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' PRICE_MISSING: description: Product is missing a price, this item will not be published. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' PRODUCT_LINK_MISSING: description: Item is missing a link URL in its product metadata, this item will not be published. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' PRODUCT_PRICE_INVALID: description: Item has a price formatting error in its product metadata, this item will not be published. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' TITLE_MISSING: description: Item is missing title in its product metadata, this item will not be published. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' CatalogsItemValidationIssue: type: string enum: - AD_IMAGE_0_LINK_LENGTH_TOO_LONG - AD_IMAGE_1_LINK_LENGTH_TOO_LONG - AD_IMAGE_2_LINK_LENGTH_TOO_LONG - AD_IMAGE_3_LINK_LENGTH_TOO_LONG - AD_IMAGE_4_LINK_LENGTH_TOO_LONG - AD_IMAGE_5_LINK_LENGTH_TOO_LONG - AD_IMAGE_6_LINK_LENGTH_TOO_LONG - AD_IMAGE_7_LINK_LENGTH_TOO_LONG - AD_IMAGE_8_LINK_LENGTH_TOO_LONG - AD_IMAGE_9_LINK_LENGTH_TOO_LONG - AD_IMAGE_10_LINK_LENGTH_TOO_LONG - AD_IMAGE_11_LINK_LENGTH_TOO_LONG - AD_IMAGE_12_LINK_LENGTH_TOO_LONG - AD_IMAGE_13_LINK_LENGTH_TOO_LONG - AD_IMAGE_14_LINK_LENGTH_TOO_LONG - AD_IMAGE_15_LINK_LENGTH_TOO_LONG - AD_IMAGE_16_LINK_LENGTH_TOO_LONG - AD_IMAGE_17_LINK_LENGTH_TOO_LONG - AD_IMAGE_18_LINK_LENGTH_TOO_LONG - AD_IMAGE_19_LINK_LENGTH_TOO_LONG - AD_IMAGE_0_LINK_WARNING - AD_IMAGE_1_LINK_WARNING - AD_IMAGE_2_LINK_WARNING - AD_IMAGE_3_LINK_WARNING - AD_IMAGE_4_LINK_WARNING - AD_IMAGE_5_LINK_WARNING - AD_IMAGE_6_LINK_WARNING - AD_IMAGE_7_LINK_WARNING - AD_IMAGE_8_LINK_WARNING - AD_IMAGE_9_LINK_WARNING - AD_IMAGE_10_LINK_WARNING - AD_IMAGE_11_LINK_WARNING - AD_IMAGE_12_LINK_WARNING - AD_IMAGE_13_LINK_WARNING - AD_IMAGE_14_LINK_WARNING - AD_IMAGE_15_LINK_WARNING - AD_IMAGE_16_LINK_WARNING - AD_IMAGE_17_LINK_WARNING - AD_IMAGE_18_LINK_WARNING - AD_IMAGE_19_LINK_WARNING - AD_IMAGE_0_LINK_REQUIRED - AD_IMAGE_1_LINK_REQUIRED - AD_IMAGE_2_LINK_REQUIRED - AD_IMAGE_3_LINK_REQUIRED - AD_IMAGE_4_LINK_REQUIRED - AD_IMAGE_5_LINK_REQUIRED - AD_IMAGE_6_LINK_REQUIRED - AD_IMAGE_7_LINK_REQUIRED - AD_IMAGE_8_LINK_REQUIRED - AD_IMAGE_9_LINK_REQUIRED - AD_IMAGE_10_LINK_REQUIRED - AD_IMAGE_11_LINK_REQUIRED - AD_IMAGE_12_LINK_REQUIRED - AD_IMAGE_13_LINK_REQUIRED - AD_IMAGE_14_LINK_REQUIRED - AD_IMAGE_15_LINK_REQUIRED - AD_IMAGE_16_LINK_REQUIRED - AD_IMAGE_17_LINK_REQUIRED - AD_IMAGE_18_LINK_REQUIRED - AD_IMAGE_19_LINK_REQUIRED - AD_IMAGE_0_TAG_LENGTH_TOO_LONG - AD_IMAGE_1_TAG_LENGTH_TOO_LONG - AD_IMAGE_2_TAG_LENGTH_TOO_LONG - AD_IMAGE_3_TAG_LENGTH_TOO_LONG - AD_IMAGE_4_TAG_LENGTH_TOO_LONG - AD_IMAGE_5_TAG_LENGTH_TOO_LONG - AD_IMAGE_6_TAG_LENGTH_TOO_LONG - AD_IMAGE_7_TAG_LENGTH_TOO_LONG - AD_IMAGE_8_TAG_LENGTH_TOO_LONG - AD_IMAGE_9_TAG_LENGTH_TOO_LONG - AD_IMAGE_10_TAG_LENGTH_TOO_LONG - AD_IMAGE_11_TAG_LENGTH_TOO_LONG - AD_IMAGE_12_TAG_LENGTH_TOO_LONG - AD_IMAGE_13_TAG_LENGTH_TOO_LONG - AD_IMAGE_14_TAG_LENGTH_TOO_LONG - AD_IMAGE_15_TAG_LENGTH_TOO_LONG - AD_IMAGE_16_TAG_LENGTH_TOO_LONG - AD_IMAGE_17_TAG_LENGTH_TOO_LONG - AD_IMAGE_18_TAG_LENGTH_TOO_LONG - AD_IMAGE_19_TAG_LENGTH_TOO_LONG - AD_IMAGE_0_TAG_REQUIRED - AD_IMAGE_1_TAG_REQUIRED - AD_IMAGE_2_TAG_REQUIRED - AD_IMAGE_3_TAG_REQUIRED - AD_IMAGE_4_TAG_REQUIRED - AD_IMAGE_5_TAG_REQUIRED - AD_IMAGE_6_TAG_REQUIRED - AD_IMAGE_7_TAG_REQUIRED - AD_IMAGE_8_TAG_REQUIRED - AD_IMAGE_9_TAG_REQUIRED - AD_IMAGE_10_TAG_REQUIRED - AD_IMAGE_11_TAG_REQUIRED - AD_IMAGE_12_TAG_REQUIRED - AD_IMAGE_13_TAG_REQUIRED - AD_IMAGE_14_TAG_REQUIRED - AD_IMAGE_15_TAG_REQUIRED - AD_IMAGE_16_TAG_REQUIRED - AD_IMAGE_17_TAG_REQUIRED - AD_IMAGE_18_TAG_REQUIRED - AD_IMAGE_19_TAG_REQUIRED - AD_IMAGE_0_LINK_DUPLICATED - AD_IMAGE_1_LINK_DUPLICATED - AD_IMAGE_2_LINK_DUPLICATED - AD_IMAGE_3_LINK_DUPLICATED - AD_IMAGE_4_LINK_DUPLICATED - AD_IMAGE_5_LINK_DUPLICATED - AD_IMAGE_6_LINK_DUPLICATED - AD_IMAGE_7_LINK_DUPLICATED - AD_IMAGE_8_LINK_DUPLICATED - AD_IMAGE_9_LINK_DUPLICATED - AD_IMAGE_10_LINK_DUPLICATED - AD_IMAGE_11_LINK_DUPLICATED - AD_IMAGE_12_LINK_DUPLICATED - AD_IMAGE_13_LINK_DUPLICATED - AD_IMAGE_14_LINK_DUPLICATED - AD_IMAGE_15_LINK_DUPLICATED - AD_IMAGE_16_LINK_DUPLICATED - AD_IMAGE_17_LINK_DUPLICATED - AD_IMAGE_18_LINK_DUPLICATED - AD_IMAGE_19_LINK_DUPLICATED - AD_IMAGE_0_TAG_DUPLICATED - AD_IMAGE_1_TAG_DUPLICATED - AD_IMAGE_2_TAG_DUPLICATED - AD_IMAGE_3_TAG_DUPLICATED - AD_IMAGE_4_TAG_DUPLICATED - AD_IMAGE_5_TAG_DUPLICATED - AD_IMAGE_6_TAG_DUPLICATED - AD_IMAGE_7_TAG_DUPLICATED - AD_IMAGE_8_TAG_DUPLICATED - AD_IMAGE_9_TAG_DUPLICATED - AD_IMAGE_10_TAG_DUPLICATED - AD_IMAGE_11_TAG_DUPLICATED - AD_IMAGE_12_TAG_DUPLICATED - AD_IMAGE_13_TAG_DUPLICATED - AD_IMAGE_14_TAG_DUPLICATED - AD_IMAGE_15_TAG_DUPLICATED - AD_IMAGE_16_TAG_DUPLICATED - AD_IMAGE_17_TAG_DUPLICATED - AD_IMAGE_18_TAG_DUPLICATED - AD_IMAGE_19_TAG_DUPLICATED - AD_VIDEO_0_LINK_LENGTH_TOO_LONG - AD_VIDEO_1_LINK_LENGTH_TOO_LONG - AD_VIDEO_2_LINK_LENGTH_TOO_LONG - AD_VIDEO_0_LINK_WARNING - AD_VIDEO_1_LINK_WARNING - AD_VIDEO_2_LINK_WARNING - AD_VIDEO_0_LINK_REQUIRED - AD_VIDEO_1_LINK_REQUIRED - AD_VIDEO_2_LINK_REQUIRED - AD_VIDEO_0_LINK_DUPLICATED - AD_VIDEO_1_LINK_DUPLICATED - AD_VIDEO_2_LINK_DUPLICATED - AD_VIDEO_0_TAG_LENGTH_TOO_LONG - AD_VIDEO_1_TAG_LENGTH_TOO_LONG - AD_VIDEO_2_TAG_LENGTH_TOO_LONG - AD_VIDEO_0_TAG_REQUIRED - AD_VIDEO_1_TAG_REQUIRED - AD_VIDEO_2_TAG_REQUIRED - AD_VIDEO_0_TAG_DUPLICATED - AD_VIDEO_1_TAG_DUPLICATED - AD_VIDEO_2_TAG_DUPLICATED - VIDEO_REQUIRED_WHEN_AD_VIDEO_PROVIDED - AD_LINK_FORMAT_WARNING - AD_LINK_SAME_AS_LINK - ADDITIONAL_IMAGE_LINK_LENGTH_TOO_LONG - ADDITIONAL_IMAGE_LINK_WARNING - ADULT_INVALID - ADWORDS_FORMAT_INVALID - ADWORDS_FORMAT_WARNING - ADWORDS_SAME_AS_LINK - AGE_GROUP_INVALID - ANDROID_DEEP_LINK_INVALID - AVAILABILITY_DATE_INVALID - AVAILABILITY_INVALID - BLOCKLISTED_IMAGE_SIGNATURE - COUNTRY_DOES_NOT_MAP_TO_CURRENCY - CUSTOM_LABEL_LENGTH_TOO_LONG - DESCRIPTION_LENGTH_TOO_LONG - DESCRIPTION_MISSING - DUPLICATE_PRODUCTS - EXPIRATION_DATE_INVALID - GENDER_INVALID - GTIN_INVALID - IMAGE_LINK_INVALID - IMAGE_LINK_LENGTH_TOO_LONG - IMAGE_LINK_MISSING - IMAGE_LINK_WARNING - INVALID_DOMAIN - IOS_DEEP_LINK_INVALID - IS_BUNDLE_INVALID - ITEM_ADDITIONAL_IMAGE_DOWNLOAD_FAILURE - ITEM_MAIN_IMAGE_DOWNLOAD_FAILURE - ITEMID_MISSING - LINK_FORMAT_INVALID - LINK_FORMAT_WARNING - LINK_LENGTH_TOO_LONG - LIST_PRICE_INVALID - MAX_ITEMS_PER_ITEM_GROUP_EXCEEDED - MIN_AD_PRICE_INVALID - MPN_INVALID - MULTIPACK_INVALID - OPTIONAL_CONDITION_INVALID - OPTIONAL_CONDITION_MISSING - OPTIONAL_PRODUCT_CATEGORY_INVALID - OPTIONAL_PRODUCT_CATEGORY_MISSING - PARSE_LINE_ERROR - PINJOIN_CONTENT_UNSAFE - PRICE_CANNOT_BE_DETERMINED - PRICE_MISSING - PRODUCT_CATEGORY_DEPTH_WARNING - PRODUCT_LINK_MISSING - PRODUCT_PRICE_INVALID - PRODUCT_TYPE_LENGTH_TOO_LONG - SALE_DATE_INVALID - SALES_PRICE_INVALID - SALES_PRICE_TOO_HIGH - SALES_PRICE_TOO_LOW - SHIPPING_INVALID - SHIPPING_HEIGHT_INVALID - SHIPPING_WEIGHT_INVALID - SHIPPING_WIDTH_INVALID - SIZE_SYSTEM_INVALID - SIZE_TYPE_INVALID - TAX_INVALID - TITLE_LENGTH_TOO_LONG - TITLE_MISSING - TOO_MANY_ADDITIONAL_IMAGE_LINKS - UTM_SOURCE_AUTO_CORRECTED - WEIGHT_UNIT_INVALID CatalogsItemValidationIssues: type: object properties: errors: $ref: '#/components/schemas/CatalogsItemValidationErrors' item_id: description: The merchant-created unique ID that represents the product. type: string example: DS0294-L nullable: true item_number: description: Item number based on order of appearance in the Catalogs Feed. For example, '0' refers to first item found in a feed that was downloaded from a 'location' specified during feed creation. type: integer example: 0 warnings: $ref: '#/components/schemas/CatalogsItemValidationWarnings' required: - item_id - item_number - warnings - errors CatalogsItemValidationWarnings: type: object properties: AD_IMAGE_0_LINK_DUPLICATED: description: ad_image_0_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_0_LINK_LENGTH_TOO_LONG: description: Ad image link 0 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_0_LINK_REQUIRED: description: Ad image link 0 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_0_LINK_WARNING: description: Ad image link 0 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_0_TAG_DUPLICATED: description: ad_image_0_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_0_TAG_LENGTH_TOO_LONG: description: Ad image tag 0 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_0_TAG_REQUIRED: description: Ad image tag 0 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_10_LINK_DUPLICATED: description: ad_image_10_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_10_LINK_LENGTH_TOO_LONG: description: Ad image link 10 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_10_LINK_REQUIRED: description: Ad image link 10 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_10_LINK_WARNING: description: Ad image link 10 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_10_TAG_DUPLICATED: description: ad_image_10_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_10_TAG_LENGTH_TOO_LONG: description: Ad image tag 10 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_10_TAG_REQUIRED: description: Ad image tag 10 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_11_LINK_DUPLICATED: description: ad_image_11_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_11_LINK_LENGTH_TOO_LONG: description: Ad image link 11 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_11_LINK_REQUIRED: description: Ad image link 11 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_11_LINK_WARNING: description: Ad image link 11 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_11_TAG_DUPLICATED: description: ad_image_11_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_11_TAG_LENGTH_TOO_LONG: description: Ad image tag 11 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_11_TAG_REQUIRED: description: Ad image tag 11 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_12_LINK_DUPLICATED: description: ad_image_12_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_12_LINK_LENGTH_TOO_LONG: description: Ad image link 12 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_12_LINK_REQUIRED: description: Ad image link 12 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_12_LINK_WARNING: description: Ad image link 12 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_12_TAG_DUPLICATED: description: ad_image_12_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_12_TAG_LENGTH_TOO_LONG: description: Ad image tag 12 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_12_TAG_REQUIRED: description: Ad image tag 12 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_13_LINK_DUPLICATED: description: ad_image_13_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_13_LINK_LENGTH_TOO_LONG: description: Ad image link 13 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_13_LINK_REQUIRED: description: Ad image link 13 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_13_LINK_WARNING: description: Ad image link 13 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_13_TAG_DUPLICATED: description: ad_image_13_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_13_TAG_LENGTH_TOO_LONG: description: Ad image tag 13 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_13_TAG_REQUIRED: description: Ad image tag 13 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_14_LINK_DUPLICATED: description: ad_image_14_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_14_LINK_LENGTH_TOO_LONG: description: Ad image link 14 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_14_LINK_REQUIRED: description: Ad image link 14 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_14_LINK_WARNING: description: Ad image link 14 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_14_TAG_DUPLICATED: description: ad_image_14_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_14_TAG_LENGTH_TOO_LONG: description: Ad image tag 14 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_14_TAG_REQUIRED: description: Ad image tag 14 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_15_LINK_DUPLICATED: description: ad_image_15_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_15_LINK_LENGTH_TOO_LONG: description: Ad image link 15 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_15_LINK_REQUIRED: description: Ad image link 15 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_15_LINK_WARNING: description: Ad image link 15 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_15_TAG_DUPLICATED: description: ad_image_15_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_15_TAG_LENGTH_TOO_LONG: description: Ad image tag 15 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_15_TAG_REQUIRED: description: Ad image tag 15 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_16_LINK_DUPLICATED: description: ad_image_16_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_16_LINK_LENGTH_TOO_LONG: description: Ad image link 16 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_16_LINK_REQUIRED: description: Ad image link 16 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_16_LINK_WARNING: description: Ad image link 16 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_16_TAG_DUPLICATED: description: ad_image_16_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_16_TAG_LENGTH_TOO_LONG: description: Ad image tag 16 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_16_TAG_REQUIRED: description: Ad image tag 16 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_17_LINK_DUPLICATED: description: ad_image_17_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_17_LINK_LENGTH_TOO_LONG: description: Ad image link 17 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_17_LINK_REQUIRED: description: Ad image link 17 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_17_LINK_WARNING: description: Ad image link 17 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_17_TAG_DUPLICATED: description: ad_image_17_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_17_TAG_LENGTH_TOO_LONG: description: Ad image tag 17 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_17_TAG_REQUIRED: description: Ad image tag 17 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_18_LINK_DUPLICATED: description: ad_image_18_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_18_LINK_LENGTH_TOO_LONG: description: Ad image link 18 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_18_LINK_REQUIRED: description: Ad image link 18 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_18_LINK_WARNING: description: Ad image link 18 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_18_TAG_DUPLICATED: description: ad_image_18_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_18_TAG_LENGTH_TOO_LONG: description: Ad image tag 18 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_18_TAG_REQUIRED: description: Ad image tag 18 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_19_LINK_DUPLICATED: description: ad_image_19_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_19_LINK_LENGTH_TOO_LONG: description: Ad image link 19 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_19_LINK_REQUIRED: description: Ad image link 19 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_19_LINK_WARNING: description: Ad image link 19 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_19_TAG_DUPLICATED: description: ad_image_19_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_19_TAG_LENGTH_TOO_LONG: description: Ad image tag 19 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_19_TAG_REQUIRED: description: Ad image tag 19 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_1_LINK_DUPLICATED: description: ad_image_1_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_1_LINK_LENGTH_TOO_LONG: description: Ad image link 1 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_1_LINK_REQUIRED: description: Ad image link 1 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_1_LINK_WARNING: description: Ad image link 1 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_1_TAG_DUPLICATED: description: ad_image_1_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_1_TAG_LENGTH_TOO_LONG: description: Ad image tag 1 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_1_TAG_REQUIRED: description: Ad image tag 1 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_2_LINK_DUPLICATED: description: ad_image_2_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_2_LINK_LENGTH_TOO_LONG: description: Ad image link 2 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_2_LINK_REQUIRED: description: Ad image link 2 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_2_LINK_WARNING: description: Ad image link 2 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_2_TAG_DUPLICATED: description: ad_image_2_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_2_TAG_LENGTH_TOO_LONG: description: Ad image tag 2 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_2_TAG_REQUIRED: description: Ad image tag 2 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_3_LINK_DUPLICATED: description: ad_image_3_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_3_LINK_LENGTH_TOO_LONG: description: Ad image link 3 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_3_LINK_REQUIRED: description: Ad image link 3 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_3_LINK_WARNING: description: Ad image link 3 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_3_TAG_DUPLICATED: description: ad_image_3_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_3_TAG_LENGTH_TOO_LONG: description: Ad image tag 3 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_3_TAG_REQUIRED: description: Ad image tag 3 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_4_LINK_DUPLICATED: description: ad_image_4_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_4_LINK_LENGTH_TOO_LONG: description: Ad image link 4 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_4_LINK_REQUIRED: description: Ad image link 4 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_4_LINK_WARNING: description: Ad image link 4 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_4_TAG_DUPLICATED: description: ad_image_4_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_4_TAG_LENGTH_TOO_LONG: description: Ad image tag 4 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_4_TAG_REQUIRED: description: Ad image tag 4 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_5_LINK_DUPLICATED: description: ad_image_5_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_5_LINK_LENGTH_TOO_LONG: description: Ad image link 5 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_5_LINK_REQUIRED: description: Ad image link 5 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_5_LINK_WARNING: description: Ad image link 5 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_5_TAG_DUPLICATED: description: ad_image_5_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_5_TAG_LENGTH_TOO_LONG: description: Ad image tag 5 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_5_TAG_REQUIRED: description: Ad image tag 5 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_6_LINK_DUPLICATED: description: ad_image_6_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_6_LINK_LENGTH_TOO_LONG: description: Ad image link 6 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_6_LINK_REQUIRED: description: Ad image link 6 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_6_LINK_WARNING: description: Ad image link 6 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_6_TAG_DUPLICATED: description: ad_image_6_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_6_TAG_LENGTH_TOO_LONG: description: Ad image tag 6 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_6_TAG_REQUIRED: description: Ad image tag 6 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_7_LINK_DUPLICATED: description: ad_image_7_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_7_LINK_LENGTH_TOO_LONG: description: Ad image link 7 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_7_LINK_REQUIRED: description: Ad image link 7 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_7_LINK_WARNING: description: Ad image link 7 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_7_TAG_DUPLICATED: description: ad_image_7_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_7_TAG_LENGTH_TOO_LONG: description: Ad image tag 7 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_7_TAG_REQUIRED: description: Ad image tag 7 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_8_LINK_DUPLICATED: description: ad_image_8_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_8_LINK_LENGTH_TOO_LONG: description: Ad image link 8 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_8_LINK_REQUIRED: description: Ad image link 8 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_8_LINK_WARNING: description: Ad image link 8 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_8_TAG_DUPLICATED: description: ad_image_8_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_8_TAG_LENGTH_TOO_LONG: description: Ad image tag 8 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_8_TAG_REQUIRED: description: Ad image tag 8 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_9_LINK_DUPLICATED: description: ad_image_9_link is duplicated with another ad image link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_9_LINK_LENGTH_TOO_LONG: description: Ad image link 9 length is too long. The maximum length is 2047 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_9_LINK_REQUIRED: description: Ad image link 9 is required because an image tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_9_LINK_WARNING: description: Ad image link 9 format is unsupported. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_9_TAG_DUPLICATED: description: ad_image_9_tag is duplicated with another ad image tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_9_TAG_LENGTH_TOO_LONG: description: Ad image tag 9 length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_IMAGE_9_TAG_REQUIRED: description: Ad image tag 9 is required because an image link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_LINK_FORMAT_WARNING: description: Item has an ad link that is formatted incorrectly. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_LINK_SAME_AS_LINK: description: Item has an ad link URL that is duplicate of the link URL. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_0_LINK_DUPLICATED: description: ad_video_0_link is duplicated with another ad video link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_0_LINK_LENGTH_TOO_LONG: description: ad_video_0_link length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_0_LINK_REQUIRED: description: ad_video_0_link is required for this item because ad_video_0_tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_0_LINK_WARNING: description: ad_video_0_link is formatted incorrectly and will not be published with your items. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_0_TAG_DUPLICATED: description: ad_video_0_tag is duplicated with another ad video tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_0_TAG_LENGTH_TOO_LONG: description: ad_video_0_tag length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_0_TAG_REQUIRED: description: ad_video_0_tag is required because ad_video_0_link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_1_LINK_DUPLICATED: description: ad_video_1_link is duplicated with another ad video link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_1_LINK_LENGTH_TOO_LONG: description: ad_video_1_link length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_1_LINK_REQUIRED: description: ad_video_1_link is required for this item because ad_video_1_tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_1_LINK_WARNING: description: ad_video_1_link is formatted incorrectly and will not be published with your items. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_1_TAG_DUPLICATED: description: ad_video_1_tag is duplicated with another ad video tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_1_TAG_LENGTH_TOO_LONG: description: ad_video_1_tag length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_1_TAG_REQUIRED: description: ad_video_1_tag is required because ad_video_1_link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_2_LINK_DUPLICATED: description: ad_video_2_link is duplicated with another ad video link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_2_LINK_LENGTH_TOO_LONG: description: ad_video_2_link length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_2_LINK_REQUIRED: description: ad_video_2_link is required for this item because ad_video_2_tag was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_2_LINK_WARNING: description: ad_video_2_link is formatted incorrectly and will not be published with your items. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_2_TAG_DUPLICATED: description: ad_video_2_tag is duplicated with another ad video tag. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_2_TAG_LENGTH_TOO_LONG: description: ad_video_2_tag length is too long. The maximum length is 511 characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AD_VIDEO_2_TAG_REQUIRED: description: ad_video_2_tag is required because ad_video_2_link was provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' ADDITIONAL_IMAGE_LINK_LENGTH_TOO_LONG: description: Item has an additional_image_link URL that contains too many characters, so the item will not be published. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' ADDITIONAL_IMAGE_LINK_WARNING: description: Item has additional_image_link URLs that are formatted incorrectly and will not be published with your items. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' ADWORDS_FORMAT_WARNING: description: Item has an adwords_redirect link that is formatted incorrectly. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' ADWORDS_SAME_AS_LINK: description: Item has an adwords_redirect URL that is duplicate of the link URL. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AGE_GROUP_INVALID: description: Item has an age group value that is formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' ANDROID_DEEP_LINK_INVALID: description: Item includes an invalid android_deep_link. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' AVAILABILITY_DATE_INVALID: description: Item has an availability_date value that is formatted incorrectly, this item will be published without an availability date. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' COUNTRY_DOES_NOT_MAP_TO_CURRENCY: description: Item includes a currency that doesn't match the usual currency for the location where the product is sold or shipped. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' CUSTOM_LABEL_LENGTH_TOO_LONG: description: Item has a custom_label value that is too long, this item will be published without that custom label. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' DESCRIPTION_LENGTH_TOO_LONG: description: The description for this item was truncated because it contains too many characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' EXPIRATION_DATE_INVALID: description: Item has an expiration_date value that is formatted incorrectly, this item will be published without an expiration date. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' GENDER_INVALID: description: Item has a gender value that is formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' GTIN_INVALID: description: Item has a GTIN value that is formatted incorrectly. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' IMAGE_LINK_WARNING: description: Item has an image_link URL that is formatted incorrectly and will not be published. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' IOS_DEEP_LINK_INVALID: description: Item includes an invalid ios_deep_link value. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' IS_BUNDLE_INVALID: description: Item has an is_bundle value that is formatted incorrectly, this item will be published without being bundled with other products. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' ITEM_ADDITIONAL_IMAGE_DOWNLOAD_FAILURE: description: Item includes additional_image_links that can't be found. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' LINK_FORMAT_WARNING: description: Item has an invalid product link which contains invalid UTM tracking paramaters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' MIN_AD_PRICE_INVALID: description: Item includes a min_ad_price value that is formatted incorrectly. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' MPN_INVALID: description: Item has a MPN value that is formatted incorrectly. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' MULTIPACK_INVALID: description: Item has an invalid multipack value. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' OPTIONAL_CONDITION_INVALID: description: Item includes a condition value that is formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' OPTIONAL_CONDITION_MISSING: description: Item is missing condition value, which may limit visibility in recommendations, search results and shopping experiences. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' OPTIONAL_PRODUCT_CATEGORY_INVALID: description: Item includes a google_product_category value that is not formatted correctly according to the GPC taxonomy. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' OPTIONAL_PRODUCT_CATEGORY_MISSING: description: Item is missing google_product_category. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' PRODUCT_CATEGORY_DEPTH_WARNING: description: Item only has 1 or 2 levels of google_product_category value, which may limit visibility in recommendations, search results and shopping experiences. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' PRODUCT_TYPE_LENGTH_TOO_LONG: description: Item has a product_type value that is too long, this item will be published without that product type. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' SALE_DATE_INVALID: description: Item has a sale_price_effective_date value that is formatted incorrectly, this item will be published without a sale date. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' SALES_PRICE_INVALID: description: Item has an incorrectly formatted sales price. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' SALES_PRICE_TOO_HIGH: description: Item has a sale price value that is higher than the original price of the item. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' SALES_PRICE_TOO_LOW: description: Item has a sale price value that is discounted very low compared to the price. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' SHIPPING_HEIGHT_INVALID: description: Item has an incorrectly formatted shipping_height value. The value must first contain a numeric value then a valid dimension unit type. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' SHIPPING_INVALID: description: Item has a shipping value that is formatted incorrectly. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' SHIPPING_WEIGHT_INVALID: description: Item has an invalid shipping_weight value. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' SHIPPING_WIDTH_INVALID: description: Item has an incorrectly formatted shipping_width value. The value must first contain a numeric value then a valid dimension unit type. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' SIZE_SYSTEM_INVALID: description: Some items have size system values which are not one of the supported size systems. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' SIZE_TYPE_INVALID: description: Item has a size type value that is formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' TAX_INVALID: description: Item has a tax value that is formatted incorrectly. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' TITLE_LENGTH_TOO_LONG: description: The title for the item was truncated because it contains too many characters. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' TOO_MANY_ADDITIONAL_IMAGE_LINKS: description: Item has a additional_image_link value that exceed the limit for additional images, this item will be published without some of your images. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' UTM_SOURCE_AUTO_CORRECTED: description: Item includes an utm_source value that is formatted incorrectly and has been automatically corrected. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' VIDEO_REQUIRED_WHEN_AD_VIDEO_PROVIDED: description: A video is required in the item when ad_video fields are provided. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' WEIGHT_UNIT_INVALID: description: Item has a weight_unit value that is formatted incorrectly, this item will be published without a weight unit. allOf: - $ref: '#/components/schemas/CatalogsItemValidationDetails' CatalogsItemsBatch: description: Object describing the catalogs items batch type: object discriminator: propertyName: catalog_type mapping: RETAIL: '#/components/schemas/CatalogsRetailItemsBatch' HOTEL: '#/components/schemas/CatalogsHotelItemsBatch' CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsItemsBatch' oneOf: - $ref: '#/components/schemas/CatalogsRetailItemsBatch' - $ref: '#/components/schemas/CatalogsHotelItemsBatch' - $ref: '#/components/schemas/CatalogsCreativeAssetsItemsBatch' CatalogsItemsBatchPostRequest: oneOf: - $ref: '#/components/schemas/CatalogsVerticalBatchRequest' - $ref: '#/components/schemas/CatalogsItemsBatchRequest' CatalogsItemsBatchRequest: description: Request object of catalogs items batch type: object discriminator: propertyName: operation mapping: UPDATE: '#/components/schemas/CatalogsItemsUpdateBatchRequest' UPSERT: '#/components/schemas/CatalogsItemsUpsertBatchRequest' CREATE: '#/components/schemas/CatalogsItemsCreateBatchRequest' DELETE_DISCONTINUED: '#/components/schemas/CatalogsItemsDeleteDiscontinuedBatchRequest' DELETE: '#/components/schemas/CatalogsItemsDeleteBatchRequest' oneOf: - $ref: '#/components/schemas/CatalogsItemsUpdateBatchRequest' - $ref: '#/components/schemas/CatalogsItemsUpsertBatchRequest' - $ref: '#/components/schemas/CatalogsItemsCreateBatchRequest' - $ref: '#/components/schemas/CatalogsItemsDeleteDiscontinuedBatchRequest' - $ref: '#/components/schemas/CatalogsItemsDeleteBatchRequest' title: legacy_retail_only CatalogsItemsCreateBatchRequest: description: Request object to create catalogs items type: object properties: country: $ref: '#/components/schemas/Country' items: description: Array with catalogs items type: array items: $ref: '#/components/schemas/ItemCreateBatchRecord' maxItems: 1000 minItems: 1 language: description: We recommend using the CatalogsLocale values. anyOf: - $ref: '#/components/schemas/CatalogsLocale' - $ref: '#/components/schemas/Language' operation: type: string enum: - CREATE required: - country - items - language - operation CatalogsItemsDeleteBatchRequest: description: Request object to delete catalogs items type: object properties: country: $ref: '#/components/schemas/Country' items: description: Array with catalogs items type: array items: $ref: '#/components/schemas/ItemDeleteBatchRecord' language: description: We recommend using the CatalogsLocale values. anyOf: - $ref: '#/components/schemas/CatalogsLocale' - $ref: '#/components/schemas/Language' operation: type: string enum: - DELETE required: - country - items - language - operation CatalogsItemsDeleteDiscontinuedBatchRequest: description: Request object to discontinue catalogs items type: object properties: country: $ref: '#/components/schemas/Country' items: description: Array with catalogs items type: array items: $ref: '#/components/schemas/ItemDeleteDiscontinuedBatchRecord' language: description: We recommend using the CatalogsLocale values. anyOf: - $ref: '#/components/schemas/CatalogsLocale' - $ref: '#/components/schemas/Language' operation: type: string enum: - DELETE_DISCONTINUED required: - country - items - language - operation CatalogsItemsPostFilters: type: object discriminator: propertyName: catalog_type mapping: RETAIL: '#/components/schemas/CatalogsRetailItemsPostFilter' HOTEL: '#/components/schemas/CatalogsHotelItemsPostFilter' CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsItemsPostFilter' oneOf: - $ref: '#/components/schemas/CatalogsRetailItemsPostFilter' - $ref: '#/components/schemas/CatalogsHotelItemsPostFilter' - $ref: '#/components/schemas/CatalogsCreativeAssetsItemsPostFilter' CatalogsItemsRequest: description: Request object of catalogs items type: object properties: country: $ref: '#/components/schemas/Country' filters: $ref: '#/components/schemas/CatalogsItemsPostFilters' language: description: We recommend using the CatalogsLocale values. anyOf: - $ref: '#/components/schemas/CatalogsLocale' - $ref: '#/components/schemas/Language' additionalProperties: false required: - country - filters - language title: catalogs_items_request CatalogsItemsUpdateBatchRequest: description: Request object to update catalogs items type: object properties: country: $ref: '#/components/schemas/Country' items: description: Array with catalogs items type: array items: $ref: '#/components/schemas/ItemUpdateBatchRecord' maxItems: 1000 minItems: 1 language: description: We recommend using the CatalogsLocale values. anyOf: - $ref: '#/components/schemas/CatalogsLocale' - $ref: '#/components/schemas/Language' operation: type: string enum: - UPDATE required: - country - items - language - operation CatalogsItemsUpsertBatchRequest: description: Request object to upsert catalogs items type: object properties: country: $ref: '#/components/schemas/Country' items: description: Array with catalogs items type: array items: $ref: '#/components/schemas/ItemUpsertBatchRecord' maxItems: 1000 minItems: 1 language: description: We recommend using the CatalogsLocale values. anyOf: - $ref: '#/components/schemas/CatalogsLocale' - $ref: '#/components/schemas/Language' operation: type: string enum: - UPSERT required: - country - items - language - operation CatalogsListProductsByFeedBasedFilter: description: Request object to list products for a given feed_id and product group filter. type: object properties: feed_id: description: Catalog Feed id pertaining to the catalog product group filter. type: string example: '2680059592705' pattern: ^\d+$ filters: $ref: '#/components/schemas/CatalogsProductGroupFilters' additionalProperties: false required: - feed_id - filters title: feed based product group CatalogsListProductsByFilterRequest: description: Request object to list products for a given product group filter. oneOf: - $ref: '#/components/schemas/CatalogsListProductsByFeedBasedFilter' - $ref: '#/components/schemas/CatalogsVerticalsListProductsByCatalogBasedFilterRequest' CatalogsLocale: type: string enum: - af-ZA - ar-SA - bg-BG - bn-IN - cs-CZ - da-DK - de - el-GR - en-AU - en-CA - en-GB - en-IN - en-US - es-419 - es-AR - es-ES - es-MX - fi-FI - fr - fr-CA - he-IL - hi-IN - hr-HR - hu-HU - id-ID - it - ja - ko-KR - ms-MY - nb-NO - nl - pl-PL - pt-BR - pt-PT - ro-RO - ru-RU - sk-SK - sv-SE - te-IN - th-TH - tl-PH - tr - uk-UA - vi-VN - zh-CN - zh-TW CatalogsProduct: type: object discriminator: propertyName: catalog_type mapping: RETAIL: '#/components/schemas/CatalogsRetailProduct' HOTEL: '#/components/schemas/CatalogsHotelProduct' CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsProduct' oneOf: - $ref: '#/components/schemas/CatalogsRetailProduct' - $ref: '#/components/schemas/CatalogsHotelProduct' - $ref: '#/components/schemas/CatalogsCreativeAssetsProduct' CatalogsProductGroupCreateRequest: description: Request object for creating a product group. type: object properties: description: type: string nullable: true feed_id: description: Catalog Feed id pertaining to the catalog product group. type: string example: '2680059592705' pattern: ^\d+$ filters: $ref: '#/components/schemas/CatalogsProductGroupFiltersRequest' is_featured: description: boolean indicator of whether the product group is being featured or not type: boolean deprecated: true name: type: string required: - feed_id - filters - name title: retail feed based CatalogsProductGroupCurrencyCriteria: description: A currency filter. This filter cannot be negated type: object properties: negated: type: boolean enum: - false values: $ref: '#/components/schemas/NonNullableCatalogsCurrency' additionalProperties: false required: - values title: catalogs_product_group_currency_criteria CatalogsProductGroupFilterKeys: anyOf: - $ref: '#/components/schemas/CatalogsBaseFilterKeys' - $ref: '#/components/schemas/ProductGroupReferenceFilter' title: catalogs_product_group_keys CatalogsProductGroupFilterOperatorTypeCriteria: type: object properties: filter_operator_type: $ref: '#/components/schemas/FilterOperatorType' negated: type: boolean values: type: array items: type: string additionalProperties: false required: - values title: catalogs_product_group_filter_operator_type_criteria CatalogsProductGroupFilters: description: Object holding a group of filters for a catalog product group anyOf: - $ref: '#/components/schemas/CatalogsProductGroupFiltersAnyOf' - $ref: '#/components/schemas/CatalogsProductGroupFiltersAllOf' title: catalogs_product_group_filters CatalogsProductGroupFiltersAllOf: type: object properties: all_of: type: array items: $ref: '#/components/schemas/CatalogsProductGroupFilterKeys' additionalProperties: false required: - all_of title: all_of CatalogsProductGroupFiltersAnyOf: type: object properties: any_of: type: array items: $ref: '#/components/schemas/CatalogsProductGroupFilterKeys' additionalProperties: false required: - any_of title: any_of CatalogsProductGroupFiltersRequest: description: |- Object holding a group of filters for request on catalog product group. This is a distinct schema. It is not possible to create or update a Product Group with empty filters. But some automatically generated Product Groups might have empty filters. anyOf: - $ref: '#/components/schemas/CatalogsProductGroupFiltersRequestAnyOfItems0' - $ref: '#/components/schemas/CatalogsProductGroupFiltersRequestAnyOfItems1' title: catalogs_product_group_filters CatalogsProductGroupFiltersRequestAnyOfItems0: type: object properties: any_of: type: array items: $ref: '#/components/schemas/CatalogsProductGroupFilterKeys' minItems: 1 required: - any_of title: any_of CatalogsProductGroupFiltersRequestAnyOfItems1: type: object properties: all_of: type: array items: $ref: '#/components/schemas/CatalogsProductGroupFilterKeys' minItems: 1 required: - all_of title: all_of CatalogsProductGroupMultipleCountriesCriteria: type: object properties: negated: type: boolean values: type: array items: $ref: '#/components/schemas/Country' additionalProperties: false required: - values title: catalogs_product_group_multiple_country_criteria CatalogsProductGroupMultipleGenderCriteria: type: object properties: negated: type: boolean values: type: array items: $ref: '#/components/schemas/Gender' additionalProperties: false required: - values title: catalogs_product_group_multiple_gender_criteria CatalogsProductGroupMultipleMediaTypesCriteria: type: object properties: negated: type: boolean values: type: array items: $ref: '#/components/schemas/MediaType' additionalProperties: false required: - values title: catalogs_product_group_multiple_media_type_criteria CatalogsProductGroupMultiplePinterestProductCategoryCriteria: type: object properties: negated: type: boolean values: type: array items: $ref: '#/components/schemas/ProductCategoryEnum' additionalProperties: false required: - values title: catalogs_product_group_multiple_pinterest_product_category_criteria CatalogsProductGroupMultipleStringCriteria: type: object properties: negated: type: boolean values: type: array items: type: string additionalProperties: false required: - values title: catalogs_product_group_multiple_string_criteria CatalogsProductGroupMultipleStringListCriteria: type: object properties: negated: type: boolean values: type: array items: $ref: '#/components/schemas/CatalogsProductGroupMultipleStringListCriteriaValuesItemsItem' additionalProperties: false required: - values title: catalogs_product_group_multiple_string_list_criteria CatalogsProductGroupMultipleStringListCriteriaValuesItemsItem: type: array items: type: string CatalogsProductGroupPricingCriteria: type: object properties: inclusion: type: boolean default: true negated: type: boolean values: type: number minimum: 0 additionalProperties: false required: - values title: catalogs_product_group_pricing_criteria CatalogsProductGroupProductCountsVertical: description: Product counts for a CatalogsProductGroup type: object discriminator: propertyName: catalog_type mapping: RETAIL: '#/components/schemas/CatalogsRetailProductGroupProductCounts' HOTEL: '#/components/schemas/CatalogsHotelProductGroupProductCounts' CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsProductGroupProductCounts' oneOf: - $ref: '#/components/schemas/CatalogsRetailProductGroupProductCounts' - $ref: '#/components/schemas/CatalogsHotelProductGroupProductCounts' - $ref: '#/components/schemas/CatalogsCreativeAssetsProductGroupProductCounts' CatalogsProductGroupStatus: type: string enum: - ACTIVE - INACTIVE CatalogsProductGroupType: description: |- Catalog product group type - **MERCHANT_CREATED**: Product groups created by merchants. - **ALL_PRODUCTS**: Consists of every product in your latest successful feed upload. - **BEST_DEALS**: Consists of products with the deepest drop in price. - **PINNER_FAVORITES**: Consists of products that are resonating most with people on Pinterest, based on engagement. - **TOP_SELLERS**: Consists of products with the highest conversion rate, if you have the conversion tag installed. - **BACK_IN_STOCK**: Consists of products that were previously out of stock and are now in stock. - **NEW_ARRIVALS**: Consists of products that are new to your Catalog. - **SHOPIFY_COLLECTIONS**: Product groups created based on Shopify Product Collections. - **I2PC**: Product groups created based on predicted product category. - **CATALOG_EXPANSION**: Consists of high-potential, recommended products from your catalog. type: string example: TOP_SELLERS enum: - MERCHANT_CREATED - ALL_PRODUCTS - BEST_DEALS - PINNER_FAVORITES - TOP_SELLERS - BACK_IN_STOCK - NEW_ARRIVALS - SHOPIFY_COLLECTIONS - I2PC - CATALOG_EXPANSION title: product_group_type CatalogsProductGroupUint32Criteria: type: object properties: negated: type: boolean operator: $ref: '#/components/schemas/NumericFilterOperatorType' value: type: integer maximum: 4294967295 minimum: 0 additionalProperties: false required: - operator - value title: catalogs_product_group_uint32_criteria CatalogsProductGroupUpdateManyRequestItems: oneOf: - $ref: '#/components/schemas/CatalogsProductGroupUpdateManyRequestItemsOneOfItems0' CatalogsProductGroupUpdateManyRequestItemsOneOfItems0: type: object properties: id: description: ID of the product group. type: string pattern: ^\d+$ allOf: - $ref: '#/components/schemas/CatalogsProductGroupUpdateRequest' required: - id title: retail feed based CatalogsProductGroupUpdateRequest: description: Request object for updating a product group. type: object properties: description: type: string nullable: true filters: $ref: '#/components/schemas/CatalogsProductGroupFiltersRequest' is_featured: description: boolean indicator of whether the product group is being featured or not type: boolean deprecated: true name: type: string additionalProperties: false title: retail feed based CatalogsProductGroupsCreateManyRequestItems: oneOf: - $ref: '#/components/schemas/CatalogsProductGroupCreateRequest' - $ref: '#/components/schemas/CatalogsVerticalProductGroupCreateRequest' CatalogsProductGroupsCreateManyRequestSchema: type: array items: $ref: '#/components/schemas/CatalogsProductGroupsCreateManyRequestItems' maxItems: 1000 minItems: 1 title: multiple product groups CatalogsProductGroupsCreateManyResponse201Items: description: ID of a created catalog product group. type: string pattern: ^\d+$ CatalogsProductGroupsCreateRequestSchema: oneOf: - $ref: '#/components/schemas/CatalogsProductGroupCreateRequest' - $ref: '#/components/schemas/CatalogsVerticalProductGroupCreateRequest' CatalogsProductGroupsUpdateRequestSchema: oneOf: - $ref: '#/components/schemas/CatalogsProductGroupUpdateRequest' - $ref: '#/components/schemas/CatalogsVerticalProductGroupUpdateRequest' CatalogsReport: type: object properties: report_status: type: string enum: - FINISHED - IN_PROGRESS size: description: Size of the report in bytes type: number nullable: true url: description: URL to download the report type: string nullable: true CatalogsReportDistributionIssueFilter: type: object properties: catalog_id: description: Unique identifier of a catalog. If not given, oldest catalog will be used type: string pattern: ^\d+$ report_type: type: string enum: - DISTRIBUTION_ISSUES required: - report_type CatalogsReportDistributionStats: type: object properties: catalog_id: description: ID of the catalog entity. type: string pattern: ^\d+$ code: description: The event code that a diagnostics aggregated number references type: integer code_label: description: A human-friendly label for the event code (e.g, 'SPAM') type: string example: SPAM ineligible_for_ads: description: Indicates if issue makes items ineligible for ads distribution type: boolean example: true ineligible_for_organic: description: Indicates if issue makes items ineligible for organic distribution type: boolean example: true message: description: Title message describing the diagnostic issue type: string occurrences: description: Number of occurrences of the issue type: integer example: 10 report_type: type: string enum: - DISTRIBUTION_ISSUES CatalogsReportFeedIngestionFilter: type: object properties: feed_id: description: ID of the feed entity. type: string pattern: ^\d+$ processing_result_id: description: Unique identifier of a feed processing result. It can be acquired from the "id" field of the "items" array within the response of the [List processing results for a given feed](/docs/api/v5/#operation/feed_processing_results/list). If not provided, default to most recent completed processing result. type: string pattern: ^\d+$ report_type: type: string enum: - FEED_INGESTION_ISSUES required: - feed_id - report_type CatalogsReportFeedIngestionStats: type: object properties: catalog_id: description: ID of the catalog entity. type: string pattern: ^\d+$ code: description: The event code that a diagnostics aggregated number references type: integer example: 112 code_label: description: A human-friendly label for the event code (e.g, 'AVAILABILITY_INVALID') type: string example: AVAILABILITY_INVALID message: description: Title message describing the diagnostic issue type: string occurrences: description: Number of occurrences of the issue type: integer example: 10 report_type: type: string enum: - FEED_INGESTION_ISSUES severity: description: An ERROR means that items have been dropped, while a WARN denotes that items have been ingested despite an issue type: string enum: - WARN - ERROR CatalogsReportParameters: description: Report parameters type: object discriminator: propertyName: catalog_type mapping: RETAIL: '#/components/schemas/CatalogsRetailReportParameters' HOTEL: '#/components/schemas/CatalogsHotelReportParameters' oneOf: - $ref: '#/components/schemas/CatalogsRetailReportParameters' - $ref: '#/components/schemas/CatalogsHotelReportParameters' CatalogsReportStats: description: Diagnostics aggregated numbers type: object discriminator: propertyName: report_type mapping: FEED_INGESTION_ISSUES: '#/components/schemas/CatalogsReportFeedIngestionStats' DISTRIBUTION_ISSUES: '#/components/schemas/CatalogsReportDistributionStats' oneOf: - $ref: '#/components/schemas/CatalogsReportFeedIngestionStats' - $ref: '#/components/schemas/CatalogsReportDistributionStats' CatalogsReportStatsParameters: description: Report stats parameters type: object discriminator: propertyName: catalog_type mapping: RETAIL: '#/components/schemas/CatalogsRetailReportStatsParameters' HOTEL: '#/components/schemas/CatalogsHotelReportStatsParameters' oneOf: - $ref: '#/components/schemas/CatalogsRetailReportStatsParameters' - $ref: '#/components/schemas/CatalogsHotelReportStatsParameters' CatalogsRetailAvailableFilterValues: type: object properties: catalog_type: type: string enum: - RETAIL filter_values: $ref: '#/components/schemas/CatalogsRetailFilterValuesMap' required: - catalog_type - filter_values title: catalogs_retail_available_filter_values CatalogsRetailBatchRequest: description: A request object that can have multiple operations on a single retail batch type: object properties: catalog_id: description: Catalog id pertaining to the retail item. If not provided, default to oldest retail catalog example: '2680059592705' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' catalog_type: type: string enum: - RETAIL country: $ref: '#/components/schemas/Country' items: description: Array with catalogs item operations type: array items: $ref: '#/components/schemas/CatalogsRetailBatchRequestItemsItems' maxItems: 1000 minItems: 1 language: description: We recommend using the CatalogsLocale values. anyOf: - $ref: '#/components/schemas/CatalogsLocale' - $ref: '#/components/schemas/Language' required: - catalog_type - country - items - language CatalogsRetailBatchRequestItemsItems: type: object discriminator: propertyName: operation mapping: CREATE: '#/components/schemas/CatalogsCreateRetailItem' UPDATE: '#/components/schemas/CatalogsUpdateRetailItem' UPSERT: '#/components/schemas/CatalogsUpsertRetailItem' DELETE: '#/components/schemas/CatalogsDeleteRetailItem' oneOf: - $ref: '#/components/schemas/CatalogsCreateRetailItem' - $ref: '#/components/schemas/CatalogsUpdateRetailItem' - $ref: '#/components/schemas/CatalogsUpsertRetailItem' - $ref: '#/components/schemas/CatalogsDeleteRetailItem' CatalogsRetailFeed: description: Catalogs Retail Feed object type: object properties: catalog_type: type: string enum: - RETAIL created_at: type: string format: date-time readOnly: true credentials: $ref: '#/components/schemas/CatalogsFeedCredentials' default_availability: $ref: '#/components/schemas/ProductAvailabilityType' default_country: $ref: '#/components/schemas/Country' default_currency: $ref: '#/components/schemas/NullableCurrency' default_locale: description: The locale used within a feed for product descriptions. type: string format: $ref: '#/components/schemas/CatalogsFormat' id: description: ID of the feed entity. type: string example: '864344156814050986' pattern: ^\d+$ readOnly: true location: description: The URL where a feed is available for download. This URL is what Pinterest will use to download a feed for processing. type: string pattern: ^(http|https|ftp|sftp):// name: description: A human-friendly name associated to a given feed. This value is currently nullable due to historical reasons. It is expected to become non-nullable in the future. type: string nullable: true preferred_processing_schedule: $ref: '#/components/schemas/CatalogsFeedProcessingSchedule' status: $ref: '#/components/schemas/CatalogsStatus' updated_at: type: string format: date-time readOnly: true required: - id - default_locale - location - name - created_at - updated_at - format - status - catalog_type - default_country title: catalogs_retail_feed CatalogsRetailFeedsCreateRequest: description: Request object for creating a retail feed. type: object properties: catalog_id: description: Catalog id pertaining to the feed. If not provided, feed will use a default catalog based on type. type: string pattern: ^\d+$ catalog_type: type: string enum: - RETAIL credentials: $ref: '#/components/schemas/CatalogsFeedCredentials' default_availability: $ref: '#/components/schemas/ProductAvailabilityType' default_country: $ref: '#/components/schemas/Country' default_currency: $ref: '#/components/schemas/NullableCurrency' default_locale: description: The locale used within a feed for product descriptions. anyOf: - $ref: '#/components/schemas/CatalogsLocale' - $ref: '#/components/schemas/DeprecatedCatalogFeedsCreateRequestDefaultLocale' format: $ref: '#/components/schemas/CatalogsFormat' location: $ref: '#/components/schemas/FeedLocation' name: $ref: '#/components/schemas/FeedDisplayName' preferred_processing_schedule: $ref: '#/components/schemas/CatalogsFeedProcessingSchedule' status: default: ACTIVE allOf: - $ref: '#/components/schemas/CatalogsStatus' additionalProperties: false required: - default_locale - format - location - name - catalog_type - default_country title: feeds_retail_create_request CatalogsRetailFeedsUpdateRequest: description: Request object for updating a feed. type: object properties: catalog_type: type: string enum: - RETAIL credentials: $ref: '#/components/schemas/CatalogsFeedCredentials' default_availability: $ref: '#/components/schemas/ProductAvailabilityType' default_currency: $ref: '#/components/schemas/NullableCurrency' format: $ref: '#/components/schemas/CatalogsFormat' location: $ref: '#/components/schemas/FeedLocation' name: $ref: '#/components/schemas/FeedDisplayName' preferred_processing_schedule: $ref: '#/components/schemas/CatalogsFeedProcessingSchedule' status: $ref: '#/components/schemas/CatalogsStatus' additionalProperties: false required: - catalog_type title: catalogs_feeds_update_request CatalogsRetailFilterValuesMap: description: A map of filter attributes to their available values. type: object properties: ad_image_tags: type: array items: type: string ad_video_tags: type: array items: type: string availability: type: array items: $ref: '#/components/schemas/ProductAvailability' brand: type: array items: type: string condition: type: array items: $ref: '#/components/schemas/ProductCondition' custom_label_0: type: array items: type: string custom_label_1: type: array items: type: string custom_label_2: type: array items: type: string custom_label_3: type: array items: type: string custom_label_4: type: array items: type: string gender: type: array items: $ref: '#/components/schemas/Gender' google_product_category_0: type: array items: type: string google_product_category_1: type: array items: type: string google_product_category_2: type: array items: type: string google_product_category_3: type: array items: type: string google_product_category_4: type: array items: type: string google_product_category_5: type: array items: type: string google_product_category_6: type: array items: type: string media_type: type: array items: $ref: '#/components/schemas/MediaType' product_type_0: type: array items: type: string product_type_1: type: array items: type: string product_type_2: type: array items: type: string product_type_3: type: array items: type: string product_type_4: type: array items: type: string title: catalogs_retail_filter_values_map CatalogsRetailItemErrorResponse: description: Object describing a retail item error type: object properties: catalog_type: type: string enum: - RETAIL errors: description: Array with the errors for the item id requested type: array items: $ref: '#/components/schemas/ItemValidationEvent' item_id: description: The catalog item id in the merchant namespace type: string example: DS0294-M item_response_kind: description: Discriminator literal identifying this leaf inside an `ItemResponse` payload. type: string enum: - retail_item_error additionalProperties: false required: - catalog_type - item_response_kind - errors title: catalogs_retail_item_error_response CatalogsRetailItemResponse: description: Object describing a retail item record type: object properties: attributes: $ref: '#/components/schemas/ItemAttributes' catalog_type: type: string enum: - RETAIL item_id: description: The catalog retail item id in the merchant namespace type: string example: DS0294-M item_response_kind: description: Discriminator literal identifying this leaf inside an `ItemResponse` payload. type: string enum: - retail_item pins: description: The pins mapped to the item type: array items: $ref: '#/components/schemas/Pin' maxItems: 11 nullable: true additionalProperties: false required: - catalog_type - item_response_kind title: catalogs_retail_item_response CatalogsRetailItemsBatch: description: Object describing the catalogs retail items batch type: object properties: batch_id: description: Id of the catalogs items batch example: '595953100599279259' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' catalog_type: type: string enum: - RETAIL completed_time: description: "Date and time (UTC) of the batch completion: YYYY-MM-DD'T'hh:mm:ss" type: string format: date-time example: 2024-01-01T20:20:00Z nullable: true created_time: description: "Date and time (UTC) of the batch creation: YYYY-MM-DD'T'hh:mm:ss. If null, batch creation was skipped due to a recent duplicate ingestion." type: string format: date-time example: 2024-01-01T20:10:40Z nullable: true items: description: Array with the catalogs items processing records part of the catalogs items batch type: array items: $ref: '#/components/schemas/ItemProcessingRecord' status: $ref: '#/components/schemas/BatchOperationStatus' required: - catalog_type - created_time CatalogsRetailItemsPostFilter: type: object properties: catalog_id: description: Catalog id pertaining to the retail item. If not provided, default to oldest retail catalog type: string pattern: ^\d+$ catalog_type: type: string enum: - RETAIL item_ids: type: array items: type: string maxItems: 1000 minItems: 1 required: - catalog_type - item_ids CatalogsRetailListProductsByCatalogBasedFilterRequest: description: Request object to list products for a given retail catalog_id and product group filter. type: object properties: catalog_id: description: Catalog ID pertaining to the product group. example: '2680059592705' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' catalog_type: description: |- Retail catalog based product group is available only for selected partners at the moment. If you are not eligible, please use feed based one. type: string enum: - RETAIL country: $ref: '#/components/schemas/Country' filters: $ref: '#/components/schemas/CatalogsProductGroupFilters' locale: $ref: '#/components/schemas/CatalogsLocale' additionalProperties: false required: - catalog_id - catalog_type - country - filters - locale title: retail_list_products_by_catalog_based_filter_request CatalogsRetailProduct: type: object properties: catalog_type: type: string enum: - RETAIL metadata: $ref: '#/components/schemas/CatalogsRetailProductMetadata' pin: $ref: '#/components/schemas/Pin' required: - catalog_type - metadata - pin CatalogsRetailProductGroup: type: object properties: catalog_id: description: Catalog ID pertaining to the product group. example: '2680059592705' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' catalog_type: type: string enum: - RETAIL country: type: string nullable: true created_at: description: Unix timestamp in seconds of when catalog product group was created. type: integer example: 1621350033000 description: type: string nullable: true feed_id: description: id of the catalogs feed belonging to this catalog product group type: string example: '2680059592705' nullable: true pattern: ^\d+$ filters: $ref: '#/components/schemas/CatalogsProductGroupFilters' id: description: ID of the catalog product group. example: '443727193917' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' is_featured: description: boolean indicator of whether the product group is being featured or not type: boolean deprecated: true locale: type: string nullable: true name: description: Name of catalog product group type: string example: Most Popular status: $ref: '#/components/schemas/CatalogsProductGroupStatus' type: $ref: '#/components/schemas/CatalogsProductGroupType' updated_at: description: Unix timestamp in seconds of last time catalog product group was updated. type: integer example: 1622742155000 required: - catalog_id - id - catalog_type - feed_id - filters - type title: retail_product_group CatalogsRetailProductGroupCreateRequest: description: Request object for creating a product group. type: object properties: catalog_id: description: Catalog ID pertaining to the product group. example: '2680059592705' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' catalog_type: description: |- Retail catalog based product group is available only for selected partners at the moment. If you are not eligible, please use feed based one. type: string enum: - RETAIL country: $ref: '#/components/schemas/Country' description: type: string nullable: true filters: $ref: '#/components/schemas/CatalogsProductGroupFiltersRequest' locale: $ref: '#/components/schemas/CatalogsLocale' name: type: string additionalProperties: false required: - catalog_id - name - catalog_type - filters title: retail_product_groups_create_request CatalogsRetailProductGroupProductCounts: description: Product counts for a Retail CatalogsProductGroup type: object properties: catalog_type: type: string enum: - RETAIL in_stock: type: number minimum: 0 out_of_stock: type: number minimum: 0 preorder: type: number minimum: 0 total: type: number minimum: 0 videos: type: number minimum: 0 required: - catalog_type - in_stock - out_of_stock - preorder - total title: catalogs_retail_product_group_product_counts CatalogsRetailProductGroupUpdateRequest: description: Request object for updating a retail product group. type: object properties: catalog_type: description: |- Retail catalog based product group is available only for selected partners at the moment. If you are not eligible, please use feed based one. type: string enum: - RETAIL country: $ref: '#/components/schemas/Country' description: type: string nullable: true filters: $ref: '#/components/schemas/CatalogsProductGroupFiltersRequest' locale: $ref: '#/components/schemas/CatalogsLocale' name: description: Name of catalog product group type: string example: Most Popular additionalProperties: false title: retail_product_groups_update_request CatalogsRetailProductMetadata: description: Retail product metadata entity type: object properties: availability: $ref: '#/components/schemas/ProductAvailability' currency: $ref: '#/components/schemas/NonNullableCatalogsCurrency' item_group_id: description: The parent ID of the product. type: string example: DS0294 nullable: true item_id: description: The user-created unique ID that represents the product. type: string example: DS0294-L price: description: The price of the product. type: number example: 24.99 sale_price: description: The discounted price of the product. type: number example: 14.99 nullable: true required: - availability - currency - item_group_id - item_id - price - sale_price CatalogsRetailReportAllItemsFilter: description: ALL_ITEMS filter for retail catalogs. Optional product_group_id scopes the report to items in that product group. If omitted, all items are included. type: object properties: catalog_id: description: Unique identifier of a catalog. If not given, oldest catalog will be used type: string pattern: ^\d+$ product_group_id: description: Optional product group ID. If omitted, all items are included. This feature is only available for allowlisted merchants. Please contact your account manager to enable this feature. type: string pattern: ^\d+$ report_type: type: string enum: - ALL_ITEMS required: - report_type CatalogsRetailReportParameters: description: Parameters for retail report type: object properties: catalog_type: type: string enum: - RETAIL report: $ref: '#/components/schemas/CatalogsRetailReportParametersReport' required: - catalog_type - report CatalogsRetailReportParametersReport: type: object discriminator: propertyName: report_type mapping: FEED_INGESTION_ISSUES: '#/components/schemas/CatalogsReportFeedIngestionFilter' DISTRIBUTION_ISSUES: '#/components/schemas/CatalogsReportDistributionIssueFilter' ALL_ITEMS: '#/components/schemas/CatalogsRetailReportAllItemsFilter' oneOf: - $ref: '#/components/schemas/CatalogsReportFeedIngestionFilter' - $ref: '#/components/schemas/CatalogsReportDistributionIssueFilter' - $ref: '#/components/schemas/CatalogsRetailReportAllItemsFilter' CatalogsRetailReportStatsParameters: description: Parameters for retail report type: object properties: catalog_type: type: string enum: - RETAIL report: $ref: '#/components/schemas/CatalogsRetailReportStatsParametersReport' required: - catalog_type - report CatalogsRetailReportStatsParametersReport: type: object discriminator: propertyName: report_type mapping: FEED_INGESTION_ISSUES: '#/components/schemas/CatalogsReportFeedIngestionFilter' DISTRIBUTION_ISSUES: '#/components/schemas/CatalogsReportDistributionIssueFilter' oneOf: - $ref: '#/components/schemas/CatalogsReportFeedIngestionFilter' - $ref: '#/components/schemas/CatalogsReportDistributionIssueFilter' CatalogsStatus: description: Status for catalogs entities. Present in catalogs_feed values. When a feed is deleted, the response will inform DELETED as status. type: string enum: - ACTIVE - INACTIVE CatalogsType: description: Type of the catalog entity. type: string enum: - RETAIL - HOTEL - CREATIVE_ASSETS CatalogsUpdatableCreativeAssetsAttributes: type: object properties: android_deep_link: description: Link to the creative assets page. type: string nullable: true custom_label_0: description: Custom grouping of creative assets. type: string nullable: true custom_label_1: description: Custom grouping of creative assets. type: string nullable: true custom_label_2: description: Custom grouping of creative assets. type: string nullable: true custom_label_3: description: Custom grouping of creative assets. type: string nullable: true custom_label_4: description: Custom grouping of creative assets. type: string nullable: true description: description: Brief description of the creative assets. type: string google_product_category: description: The categorization of the product based on the standardized Google Product Taxonomy. This is a set taxonomy. Both the text values and numeric codes are accepted. type: string nullable: true ios_deep_link: description: IOS deep link to the creative assets page. type: string nullable: true link: description: Link to the creative assets page. type: string title: description: The name of the creative assets. type: string visibility: description: "Visibility of the creative assets. Must be one of the following values (upper or lowercase): 'visible', 'hidden'." type: string nullable: true CatalogsUpdatableHotelAttributes: type: object properties: address: description: Hotel address allOf: - $ref: '#/components/schemas/CatalogsHotelAddress' base_price: description: Base price of the hotel room per night followed by the ISO currency code type: string example: 100 USD nullable: true brand: description: The brand to which this hotel belongs to. type: string nullable: true category: description: The type of property. The category can be any type of internal description desired. type: string nullable: true custom_label_0: description: Custom grouping of hotels type: string nullable: true custom_label_1: description: Custom grouping of hotels type: string nullable: true custom_label_2: description: Custom grouping of hotels type: string nullable: true custom_label_3: description: Custom grouping of hotels type: string nullable: true custom_label_4: description: Custom grouping of hotels type: string nullable: true description: description: Brief description of the hotel. type: string nullable: true guest_ratings: description: If specified, you must provide all properties allOf: - $ref: '#/components/schemas/CatalogsHotelGuestRatings' latitude: description: Latitude of the hotel. type: number link: description: Link to the product page type: string nullable: true longitude: description: Longitude of the hotel. type: number nullable: true name: description: The hotel's name. type: string nullable: true neighborhood: description: A list of neighborhoods where the hotel is located type: array items: type: string nullable: true sale_price: description: Sale price of a hotel room per night. Used to advertise discounts off the regular price of the hotel. type: string example: 90 USD nullable: true CatalogsUpdateCreativeAssetsItem: description: A creative assets item to be updated. type: object properties: attributes: $ref: '#/components/schemas/CatalogsUpdatableCreativeAssetsAttributes' creative_assets_id: description: The catalog creative assets item id in the merchant namespace type: string example: DS0294-M operation: type: string enum: - UPDATE required: - attributes - creative_assets_id - operation CatalogsUpdateHotelItem: description: Object describing an hotel item batch record type: object properties: attributes: $ref: '#/components/schemas/CatalogsUpdatableHotelAttributes' hotel_id: description: The catalog hotel item id in the merchant namespace type: string example: DS0294-M operation: type: string enum: - UPDATE required: - attributes - hotel_id - operation CatalogsUpdateRetailItem: description: An item to be updated type: object properties: attributes: $ref: '#/components/schemas/UpdatableItemAttributes' item_id: description: The catalog item id in the merchant namespace type: string example: DS0294-M operation: type: string enum: - UPDATE update_mask: description: The list of product attributes to be updated. Attributes specified in the update mask without a value specified in the body will be deleted from the product item. type: array items: $ref: '#/components/schemas/UpdateMaskFieldType' example: - ad_link - adult - age_group - availability - average_review_rating - brand - checkout_enabled - color - condition - custom_label_0 - custom_label_1 - custom_label_2 - custom_label_3 - custom_label_4 - description - free_shipping_label - free_shipping_limit - gender - google_product_category - gtin - item_group_id - last_updated_time - link - material - min_ad_price - mpn - number_of_ratings - number_of_reviews - pattern - price - product_type - sale_price - shipping - shipping_height - shipping_weight - shipping_width - size - size_system - size_type - tax - title - variant_names - variant_values - promotion_id nullable: true required: - attributes - item_id - operation CatalogsUpsertCreativeAssetsItem: description: A creative assets item to be upserted. type: object properties: attributes: $ref: '#/components/schemas/CatalogsCreativeAssetsAttributes' creative_assets_id: description: The catalog creative assets id in the merchant namespace type: string example: DS0294-M operation: type: string enum: - UPSERT required: - attributes - creative_assets_id - operation CatalogsUpsertHotelItem: description: A hotel item to be upserted. type: object properties: attributes: $ref: '#/components/schemas/CatalogsHotelAttributes' hotel_id: description: The catalog hotel id in the merchant namespace type: string example: DS0294-M operation: type: string enum: - UPSERT required: - attributes - hotel_id - operation CatalogsUpsertRetailItem: description: An item to be upserted type: object properties: attributes: $ref: '#/components/schemas/ItemAttributesRequest' item_id: description: The catalog item id in the merchant namespace type: string example: DS0294-M operation: type: string enum: - UPSERT required: - attributes - item_id - operation CatalogsVerticalBatchRequest: description: A request object that can have multiple operations on a single batch type: object discriminator: propertyName: catalog_type mapping: RETAIL: '#/components/schemas/CatalogsRetailBatchRequest' HOTEL: '#/components/schemas/CatalogsHotelBatchRequest' CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsBatchRequest' oneOf: - $ref: '#/components/schemas/CatalogsRetailBatchRequest' - $ref: '#/components/schemas/CatalogsHotelBatchRequest' - $ref: '#/components/schemas/CatalogsCreativeAssetsBatchRequest' title: operate on item batch CatalogsVerticalFeedsCreateRequest: description: Request object for creating a feed. type: object discriminator: propertyName: catalog_type mapping: RETAIL: '#/components/schemas/CatalogsRetailFeedsCreateRequest' HOTEL: '#/components/schemas/CatalogsHotelFeedsCreateRequest' CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsFeedsCreateRequest' oneOf: - $ref: '#/components/schemas/CatalogsRetailFeedsCreateRequest' - $ref: '#/components/schemas/CatalogsHotelFeedsCreateRequest' - $ref: '#/components/schemas/CatalogsCreativeAssetsFeedsCreateRequest' title: feeds_create_request CatalogsVerticalFeedsUpdateRequest: description: Request object for updating a feed. type: object discriminator: propertyName: catalog_type mapping: RETAIL: '#/components/schemas/CatalogsRetailFeedsUpdateRequest' HOTEL: '#/components/schemas/CatalogsHotelFeedsUpdateRequest' CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsFeedsUpdateRequest' oneOf: - $ref: '#/components/schemas/CatalogsRetailFeedsUpdateRequest' - $ref: '#/components/schemas/CatalogsHotelFeedsUpdateRequest' - $ref: '#/components/schemas/CatalogsCreativeAssetsFeedsUpdateRequest' title: feeds_update_request CatalogsVerticalProductGroup: type: object discriminator: propertyName: catalog_type mapping: RETAIL: '#/components/schemas/CatalogsRetailProductGroup' HOTEL: '#/components/schemas/CatalogsHotelProductGroup' CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsProductGroup' oneOf: - $ref: '#/components/schemas/CatalogsRetailProductGroup' - $ref: '#/components/schemas/CatalogsHotelProductGroup' - $ref: '#/components/schemas/CatalogsCreativeAssetsProductGroup' title: product_group CatalogsVerticalProductGroupCreateRequest: description: Request object for creating a catalog based product group. type: object discriminator: propertyName: catalog_type mapping: RETAIL: '#/components/schemas/CatalogsRetailProductGroupCreateRequest' HOTEL: '#/components/schemas/CatalogsHotelProductGroupCreateRequest' CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsProductGroupCreateRequest' oneOf: - $ref: '#/components/schemas/CatalogsRetailProductGroupCreateRequest' - $ref: '#/components/schemas/CatalogsHotelProductGroupCreateRequest' - $ref: '#/components/schemas/CatalogsCreativeAssetsProductGroupCreateRequest' title: catalog based CatalogsVerticalProductGroupUpdateRequest: description: Request object for updating a catalog based product group. type: object discriminator: propertyName: catalog_type mapping: RETAIL: '#/components/schemas/CatalogsRetailProductGroupUpdateRequest' HOTEL: '#/components/schemas/CatalogsHotelProductGroupUpdateRequest' CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsProductGroupUpdateRequest' oneOf: - $ref: '#/components/schemas/CatalogsRetailProductGroupUpdateRequest' - $ref: '#/components/schemas/CatalogsHotelProductGroupUpdateRequest' - $ref: '#/components/schemas/CatalogsCreativeAssetsProductGroupUpdateRequest' title: catalog based CatalogsVerticalsListProductsByCatalogBasedFilterRequest: description: Request object to list products for a given catalog_id and product group filter. type: object discriminator: propertyName: catalog_type mapping: RETAIL: '#/components/schemas/CatalogsRetailListProductsByCatalogBasedFilterRequest' HOTEL: '#/components/schemas/CatalogsHotelListProductsByCatalogBasedFilterRequest' CREATIVE_ASSETS: '#/components/schemas/CatalogsCreativeAssetsListProductsByCatalogBasedFilterRequest' oneOf: - $ref: '#/components/schemas/CatalogsRetailListProductsByCatalogBasedFilterRequest' - $ref: '#/components/schemas/CatalogsHotelListProductsByCatalogBasedFilterRequest' - $ref: '#/components/schemas/CatalogsCreativeAssetsListProductsByCatalogBasedFilterRequest' title: catalog based product group ChangeHistoryDataType: type: string enum: - STRING - NUMERIC - MICROCURRENCY - DATE - BOOL - GENDER_LIST - AGE_BUCKET_LIST - APPTYPE_LIST - COUNTRY_LIST - LOCALE_LIST ChangeHistoryOperationType: type: string enum: - CREATE - UPDATE - DELETE CollectionsHeaderType: description: Collections ad header type type: string example: SHOP_THIS_COLLECTION enum: - SHOP_THIS_COLLECTION - EXPLORE_THIS_COLLECTION - NO_HEADER - ON_SALE - GET_DEAL - null nullable: true ConditionFilter: type: object properties: CONDITION: $ref: '#/components/schemas/CatalogsProductGroupMultipleStringCriteria' additionalProperties: false required: - CONDITION title: CONDITION ContentType: type: string enum: - image/jpeg - image/png ConversionAccessToken: description: A successful conversion access token response. type: object properties: access_token: type: string token_type: type: string default: conversion required: - access_token title: Conversion access token response ConversionApiResponseEventsItems: type: object properties: error_message: description: Error message containing more information about why the event failed to be processed. type: string example: '' nullable: true status: description: Whether the event was processed successfully. example: processed allOf: - $ref: '#/components/schemas/EventProcessingStatus' warning_message: description: Warning messages about any fields in the event which are not standard. These are not critical to event processing. type: string example: '' nullable: true required: - status ConversionAttributionWindowDays: type: number enum: - 0 - 1 - 7 - 14 - 30 - 60 ConversionDeletionRequest: description: Conversion deletion request type: object properties: created_time: description: Timestamp when the conversion deletion request was succesfully created. type: string format: date readOnly: true processed_time: description: Timestamp when the conversion deletion request was processed. type: string format: date nullable: true readOnly: true request_id: description: Unique identifier of the conversion deletion request type: string maxLength: 18 pattern: ^\d+$ status: description: |- Represents the status of the conversion deletion request. "PENDING" or "SUBMITTED". "PENDING" meaning the Advertiser can cancel the request. The advertiser has a 7 day time window after the conversion deletion request was submitted to cancel it. "SUBMITTED" meaning that the Data Deletion process has begun and can no longer be canceled. allOf: - $ref: '#/components/schemas/ConversionDeletionRequestStatus' readOnly: true required: - request_id - status - created_time ConversionDeletionRequestCreate: description: Resource create operation model. type: object properties: deletion_targets: description: Object containing the targets of the conversion deletion request. Users can be identified with user_emails, epiks, or both within the same request. allOf: - $ref: '#/components/schemas/ConversionDeletionRequestTargets' required: - deletion_targets ConversionDeletionRequestEPIKTargets: type: object properties: epiks: description: Array of EPIKs (Encrypted Pinterest ID Keys). An EPIK is a user match type that utilizes 3P browser localStorage (similar to a third-party cookie). type: array items: type: string minItems: 1 required: - epiks ConversionDeletionRequestStatus: description: |- Represents the status of the conversion deletion request. "PENDING" or "SUBMITTED". "PENDING" meaning the Advertiser can cancel the request. The advertiser has a 7 day time window after the conversion deletion request was submitted to cancel it. "SUBMITTED" meaning that the Data Deletion process has begun and can no longer be canceled. type: string enum: - PENDING - SUBMITTED - CANCELLED ConversionDeletionRequestTargets: anyOf: - $ref: '#/components/schemas/ConversionDeletionRequestUserEmailTargets' - $ref: '#/components/schemas/ConversionDeletionRequestEPIKTargets' ConversionDeletionRequestUserEmailTargets: type: object properties: user_emails: description: Array of plain text user emails. type: array items: type: string minItems: 1 required: - user_emails ConversionEvent: type: string enum: - PAGE_VISIT - SIGNUP - CHECKOUT - CUSTOM - VIEW_CATEGORY - SEARCH - ADD_TO_CART - WATCH_VIDEO - LEAD - APP_INSTALL ConversionEventAppInfo: description: Object containing information about the application where event occurred. type: object properties: app_id: description: App ID in Google Play Store, AppStore or other stores. type: string example: '429047995' maxLength: 200 app_name: description: Name of the app. Primarily used for Mobile Apps. type: string example: MyAwesomeApp maxLength: 200 app_package_name: description: App package name type: string example: com.company.myawesomeapp maxLength: 200 app_store: description: |- The name of the app distributor or store from which the app was installed. Some options: Samsung Galaxy Store, Google Play Store, Amazon Store, Apple App Store, F-Droid, Aptoide, Obtanium, Huawei AppGallery, Xiaomi Mi GetApps type: string example: Google Play Store maxLength: 100 app_version: description: App version. Primarily used for mobile apps type: string example: '7.9' maxLength: 100 install_time: description: App install time. Unix timestamp in seconds type: integer example: 1739222269 minimum: 0 user_agent: description: User Agent request header. Primarily used for Web events type: string example: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 maxLength: 16384 window_height: description: Inner height of the window or viewport. type: integer example: 900 maximum: 30720 minimum: 0 window_width: description: Inner width of the window or viewport. type: integer example: 1678 maximum: 30720 minimum: 0 ConversionEventDeviceInfo: description: Object containing information about the device where event occurred. type: object properties: battery_level: description: Battery charge level percentage type: integer example: 78 maximum: 100 minimum: 0 brand: description: Device brand type: string example: Apple, Samsung, Motorola maxLength: 100 carrier: description: User device's mobile carrier. type: string example: T-Mobile maxLength: 100 cpu_cores: description: Number of CPU cores type: integer example: 8 maximum: 1152 minimum: 0 external_storage_free_space: description: External storage size in GB type: integer example: 126 maximum: 1048576 minimum: 0 external_storage_size: description: External storage size in GB type: integer example: 512 maximum: 1048576 minimum: 0 form_factor: description: Device form factor example: cellphone allOf: - $ref: '#/components/schemas/FormFactor' kernel_version: description: |- Kernel version. Examples: Linux: 6.15. Obtain by running: uname -r MacOS: 24.3.0. Obtain by running: sysctl kern.version Android: 6.6. Obtain from OS.uname().release type: string example: '6.15' maxLength: 100 languages: description: List of user installed languages. ISO 639-1 format type: array items: type: string example: - en - de - lt maxItems: 100 minItems: 0 locale: description: Device locale BCP-47 format type: string example: en-us maxLength: 35 model: description: Device model name type: string maxLength: 100 network_type: description: |- Network type: 4G, 5G, ethernet, wifi In Android: NetworkCapabilities.getNetworkCapabilities() example: wifi allOf: - $ref: '#/components/schemas/NetworkType' os_family: description: OS Family example: ios allOf: - $ref: '#/components/schemas/OsFamily' os_name: description: |- Short name of the OS. This value if specific to os family. Examples: Windows: 10, 11; Android: 16; iOS: 18; MacOS: 15; Linux: Debian, Ubuntu, Arch type: string example: '10' maxLength: 100 os_release_name: description: |- Marketing name for the release version iOS: Dawn Android: Baklava MacOS: Sequoia Ubuntu Linux: Plucky Puffin type: string example: '18.3' maxLength: 100 os_version: description: |- Full name of the version. Examples: iOS: 18.3 Android: 16.1 MacOS: 15.5 Windows: 24H2 Ubuntu Linux: 25.04 type: string example: '18.3' maxLength: 100 screen_density: description: Screen density, PPI type: integer example: 460 maximum: 100000 minimum: 0 screen_height: description: Screen height in pixels type: integer example: 2868 maximum: 30720 minimum: 0 screen_width: description: Screen width in pixels type: integer example: 1320 maximum: 30720 minimum: 0 storage_free_space: description: Internal storage size in GB type: integer example: 184 maximum: 1048576 minimum: 0 storage_size: description: Internal storage size in GB type: integer example: 256 maximum: 1048576 minimum: 0 timezone: description: Device timezone type: string example: USA/New York maxLength: 40 timezone_abbr: description: Timezone abbreviation type: string example: PDT maxLength: 5 type: description: Device type type: string example: iPhone, Android maxLength: 100 ConversionEventIngestionSource: description: The source of conversion events ingestion type: string example: CONVERSIONS_API enum: - TAG - MMP - FILE_UPLOAD - CONVERSIONS_API - NATIVE ConversionEventResponse: type: object properties: ad_account_id: description: Id of the ad account. type: string example: '549757463328' pattern: ^\d+$ title: ad_account_id conversion_event: $ref: '#/components/schemas/ConversionTagType' conversion_tag_id: description: Id of the tag. type: string example: '2614324385652' pattern: ^\d+$ title: conversion_tag_id created_time: description: Creation date in epoch format. type: integer example: 1564768710 title: created_time reporting_conversion_event: description: For advertiser-defined events, the reporting event label shown in optimization UIs. type: string example: GET_QUOTE title: reporting_conversion_event title: ConversionEventResponse ConversionEvents: description: Conversion events. type: object properties: events: description: Specific messages for each event received. The order will match the order in which the events were received in the request. type: array items: $ref: '#/components/schemas/ConversionApiResponseEventsItems' readOnly: true num_events_processed: description: Number of events that were successfully processed from the events. type: integer example: 1 readOnly: true num_events_received: description: Total number of events received in the request. type: integer example: 1 readOnly: true required: - events - num_events_processed - num_events_received ConversionEventsCreate: description: Conversion events. type: object properties: data: description: A list of events (one or more) encapsulated by a data object. type: array items: $ref: '#/components/schemas/ConversionEventsDataItems' example: - event_name: checkout action_source: app_ios event_time: 1769818893 event_id: eventId0001 event_source_url: https://www.my-clothing-shop.org/ opt_out: false advertiser_tracking_enabled: true partner_name: ss-partnername user_data: em: - 411e44ce1261728ffd2c0686e44e3fffe413c0e2c5adc498bc7da883d476b9c8 - 09831ea51bd1b7b32a836683a00a9ccaf3d05f59499f42d9883412ed79289969 hashed_maids: - 0192518eb84137ccfe82c8b6322d29631dae7e28ed9d0f6dd5f245d73a58c5f1 - 837b850ac46d62b2272a71de73c27801ff011ac1e36c5432620c8755cf90db46 client_ip_address: 216.3.128.12 client_user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/67.0.3396.87 Safari/537.36 ph: - 45df139772a81b6011bdc1c9cc3d1cb408fc0b10ec0c5cb9d4d4e107f0ddc49d ge: - 0d248e82c62c9386878327d491c762a002152d42ab2c391a31c44d9f62675ddf db: - d4426a0086d10f12ad265539ae8d54221dc67786053d511407204b76e99d7739 ln: - 7e546b3aa43f989dd359672e6c3409d4f9d4e8f155ae1e9b90ee060985468c19 fn: - ec1e6a072231703f1bc41429052fff8c00a7e0c6aaec2e7107241ca8f3ceb6b2 ct: - 4ac01a129bfd10385c9278c2cf2c46fac5ab57350841234f587c8522a2e4ce36 st: - 49a6d05b8e4b516656e464271d9dd38d0a7e0142f7f49546f4dabd2720cafc34 zp: - fd5f56b40a79a385708428e7b32ab996a681080a166a2206e750eb4819186145 country: - 9b202ecbc6d45c6d8901d989a918878397a3eb9d00e8f48022fc051b19d21a1d external_id: - 6a7a73766627eb611720883d5a11cc62b5bfee237b00a6658d78c50032ec4aee click_id: dj0yJnU9b2JDcFFHekV4SHJNcmVrbFBkUEdqakh0akdUT1VjVVUmcD0yJm49cnNBQ3F2Q2dOVDBXWWhkWklrUGxBUSZ0PUFBQUFBR1BaY3Bv partner_id: BUJrTlRRzGJmWhRXFZdkioV6wKPBve7Lom__GU9J74hq2NIQj4O3nOZJrp3mcUr5MptkXsI14juMOIM9mNZnM4zEUFT2JLVaFhcOfuuWz3IWEDtBf6I0DPc custom_data: currency: USD value: '66.95' content_ids: - product-id-001 - product-id-002 content_name: pinterest-themed-clothing content_category: shirts content_brand: pinterest-brand contents: - id: product-id-001 item_price: '14.99' quantity: 3 item_name: pinterest-shirt-girl item_category: pinterest-clothing-shirts item_brand: pinterest - id: product-id-002 item_price: '10.99' quantity: 2 item_name: pinterest-shirt-men item_category: pinterest-clothing-shirts item_brand: pinterest num_items: 5 order_id: my_order_id search_string: sample string opt_out_type: LDP predicted_ltv: '2794.82' app_id: '429047995' app_name: Pinterest app_version: '7.9' device_brand: Apple device_carrier: T-Mobile device_model: iPhone X device_type: iPhone os_version: 12.1.4 wifi: false language: en device_info: brand: Apple, Samsung, Motorola type: iPhone, Android model: 16 Pro, Galaxy S25 Ultra form_factor: cellphone os_family: ios os_name: '10' os_version: '18.3' os_release_name: '18.3' kernel_version: '6.15' carrier: T-Mobile screen_width: 1320 screen_height: 2868 screen_density: 460 cpu_cores: 8 storage_size: 256 storage_free_space: 184 external_storage_size: 512 external_storage_free_space: 126 locale: en-us languages: - en - de - lt timezone: USA/New York timezone_abbr: PDT network_type: wifi battery_level: 78 app_info: app_name: MyAwesomeApp app_package_name: com.company.myawesomeapp app_id: '429047995' app_version: '7.9' app_store: Google Play Store window_width: 1678 window_height: 900 install_time: 1739222269 user_agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/131.0.0.0 Safari/537.36 maxItems: 1000 minItems: 1 required: - data ConversionEventsDataItems: type: object properties: action_source: description: |- The source indicating where the conversion event occurred. - `app_android` - `app_ios` - `web` - `offline` type: string app_id: description: The app store app ID. type: string nullable: true app_info: $ref: '#/components/schemas/ConversionEventAppInfo' app_name: description: Name of the app. type: string nullable: true app_version: description: Version of the app. type: string nullable: true custom_data: $ref: '#/components/schemas/ConversionEventsDataItemsCustomData' device_brand: description: Brand of the user device. type: string nullable: true device_carrier: description: User device's mobile carrier. type: string nullable: true device_info: $ref: '#/components/schemas/ConversionEventDeviceInfo' device_model: description: Model of the user device. type: string nullable: true device_type: description: Type of the user device. type: string nullable: true event_id: description: A unique id string that identifies this event and can be used for deduping between events ingested via both the conversion API and Pinterest tracking. Without this, event's data is likely to be double counted and will cause report metric inflation. Third-party vendors make sure this field is updated on both Pinterest tag and Conversions API side before rolling out template for Conversions API. type: string event_name: description: |- The type of the user event. Please use the right event_name; otherwise the event will not be accepted and show up correctly in reports. - `add_payment_info` - `add_to_cart` - `add_to_wishlist` - `app_install` - `app_open` - `checkout` - `contact` - `custom` - `customize_product` - `find_location` - `initiate_checkout` - `lead` - `page_visit` - `schedule` - `search` - `signup` - `start_trial` - `submit_application` - `subscribe` - `view_category` - `view_content` - `watch_video` type: string event_source_url: description: URL of the web conversion event. type: string nullable: true event_time: description: The time when the event happened. Unix timestamp in seconds. type: integer format: int64 language: description: Two-character ISO-639-1 language code indicating the user's language. type: string nullable: true opt_out: description: When action_source is web or offline, it defines whether the user has opted out of tracking for web conversion events. While when action_source is app_android or app_ios, it defines whether the user has enabled Limit Ad Tracking on their iOS device, or opted out of Ads Personalization on their Android device. type: boolean os_version: description: Version of the device operating system. type: string nullable: true partner_name: description: The third party partner name responsible to send the event to Conversions API on behalf of the advertiser. The naming convention is "ss-partnername" lowercase. E.g 'ss-shopify' type: string nullable: true user_data: description: Object containing customer information data. Note, It is required at least one of 1) em, 2) hashed_maids or 3) pair client_ip_address + client_user_agent. allOf: - $ref: '#/components/schemas/ConversionEventsUserDataProperties' wifi: description: Whether the event occurred when the user device was connected to wifi. type: boolean required: - action_source - event_id - event_name - event_time - user_data ConversionEventsDataItemsCustomData: description: Object containing other custom data. type: object properties: content_brand: description: The brand of the content associated with the event. type: string nullable: true content_category: description: The category of the content associated with the event. type: string nullable: true content_ids: description: List of products IDs. We recommend using this if you are a merchant for PageVisit, AddToCart and Checkouts. For detail, please check [here](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs) (Install the Pinterest tag section). type: array items: type: string content_name: description: The name of the page or product associated with the event. type: string nullable: true contents: description: A list of objects containing information about products, such as price and quantity. We recommend using this if you are a merchant for PageVisit, AddToCart and Checkouts. For detail, please check [here](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs) (Install the Pinterest tag section). type: array items: $ref: '#/components/schemas/ConversionEventsDataItemsCustomDataContentsItems' currency: description: The ISO-4217 currency code. If not provided, we will default to the advertiser's currency set during account creation. Your campaign performance needs this field to report right ROAS/CPA. type: string nullable: true external_measurement_id: description: Only use when instructed. type: string nullable: true external_measurement_vendor_id: description: Only use when instructed. type: integer nullable: true np: description: Named partner. Not required, this is for Pinterest internal use only. Please do not use this unless specifically guided. type: string nullable: true num_items: description: Total number of products of the event. For example, the total number of items purchased in a checkout event. We recommend using this if you are a merchant for AddToCart and Checkouts. For detail, please check [here](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs) (Install the Pinterest tag section). type: integer format: int64 opt_out_type: description: Flags for different privacy rights laws to opt out users of sharing personal information. Separate values with commas. See the Help Center article about [limited data processing](https://help.pinterest.com/en/business/article/limited-data-processing) and the developer's guide for [tracking conversion events](/docs/track-conversions/track-conversions-in-the-api/#whether-the-user-has-opted-out-of-web-or-offline-conversion-events) for help with using this parameter. type: string nullable: true order_id: description: The order ID. We recommend sending order_id to help us deduplicate events when necessary. This also helps to run other measurement products at Pinterest. type: string nullable: true predicted_ltv: description: Predicted lifetime value of user associated with the event. Accepted as a string in the request; it will be parsed into a double. type: string nullable: true search_string: description: The search string related to the user conversion event. type: string nullable: true value: description: Total value of the event. Accepted as a string in the request; it will be parsed into a double. For example, if there are two items in a checkout event, the value should be the total price. We recommend to use pre-tax, pre-shipping final value. type: string nullable: true ConversionEventsDataItemsCustomDataContentsItems: type: object properties: id: description: The id of a product. We recommend using this if you are a merchant for AddToCart and Checkouts. For detail, please check [here](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs) (Install the Pinterest tag section). type: string item_brand: description: The brand of a product. type: string item_brand_id: description: The brand ID of a product. type: string maxLength: 64 item_category: description: The category of a product. type: string item_name: description: The name of a product. type: string item_price: description: The price of a product. Accepted as a string in the request; it will be parsed into a double. This is the original item value before any discount. We recommend using this if you are a merchant for PageVisit, AddToCart and Checkouts. For detail, please check [here](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs) (Install the Pinterest tag section). type: string quantity: description: The amount of a product. We recommend using this if you are a merchant for AddToCart and Checkouts. For detail, please check [here](https://help.pinterest.com/en/business/article/before-you-get-started-with-catalogs) (Install the Pinterest tag section). type: integer format: int64 ConversionEventsUserDataProperties: type: object properties: click_id: description: The unique identifier stored in _epik cookie on your domain or &epik= query parameter in the URL. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA. type: string example: dj0yJnU9b2JDcFFHekV4SHJNcmVrbFBkUEdqakh0akdUT1VjVVUmcD0yJm49cnNBQ3F2Q2dOVDBXWWhkWklrUGxBUSZ0PUFBQUFBR1BaY3Bv nullable: true client_ip_address: description: The user's IP address, which can be either in IPv4 or IPv6 format. Used for matching. We highly recommend this for all events. It may improve reporting performance such as ROAS/CPA. type: string example: 216.3.128.12 client_user_agent: description: The user agent string of the user's web browser. We highly recommend this for all events. It may improve reporting performance such as ROAS/CPA. type: string country: description: Sha256 hashes of two-character ISO-3166 country code indicating the user's country, in lowercase. The string should be in the UTF-8 format. type: array items: type: string example: - 9b202ecbc6d45c6d8901d989a918878397a3eb9d00e8f48022fc051b19d21a1d ct: description: Sha256 hashes of user's city, in lowercase, and without spaces or punctuation. User residency city (mostly billing). The string should be in the UTF-8 format. type: array items: type: string example: - 4ac01a129bfd10385c9278c2cf2c46fac5ab57350841234f587c8522a2e4ce36 db: description: Sha256 hashes of user's date of birthday, given as year, month, and day. The string should be in the UTF-8 format. type: array items: type: string example: - d4426a0086d10f12ad265539ae8d54221dc67786053d511407204b76e99d7739 em: description: Sha256 hashes of lowercase version of user's email addresses. Used for matching. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA. The string should be in the UTF-8 format. type: array items: type: string example: - 411e44ce1261728ffd2c0686e44e3fffe413c0e2c5adc498bc7da883d476b9c8 - 09831ea51bd1b7b32a836683a00a9ccaf3d05f59499f42d9883412ed79289969 external_id: description: Sha256 hashes of the unique id from the advertiser that identifies a user in their space, e.g. user id, loyalty id, etc. We highly recommend this on all events. It may improve reporting performance such as ROAS/CPA. The string should be in the UTF-8 format. type: array items: type: string example: - 6a7a73766627eb611720883d5a11cc62b5bfee237b00a6658d78c50032ec4aee fn: description: Sha256 hashes of user's first name, in lowercase. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA. The string should be in the UTF-8 format. type: array items: type: string ge: description: Sha256 hashes of user's gender, in lowercase. Either "f" or "m" or "n" for non-binary gender. The string should be in the UTF-8 format. type: array items: type: string example: - 0d248e82c62c9386878327d491c762a002152d42ab2c391a31c44d9f62675ddf hashed_maids: description: Sha256 hashes of user's "Google Advertising IDs" (GAIDs) or "Apple's Identifier for Advertisers" (IDFAs). Used for matching. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA. The string should be in the UTF-8 format. type: array items: type: string example: - 0192518eb84137ccfe82c8b6322d29631dae7e28ed9d0f6dd5f245d73a58c5f1 - 837b850ac46d62b2272a71de73c27801ff011ac1e36c5432620c8755cf90db46 ln: description: Sha256 hashes of user's last name, in lowercase. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA. The string should be in the UTF-8 format. type: array items: type: string example: - 7e546b3aa43f989dd359672e6c3409d4f9d4e8f155ae1e9b90ee060985468c19 partner_id: description: A unique identifier of visitors' information defined by third party partners. e.g RampID type: string example: BUJrTlRRzGJmWhRXFZdkioV6wKPBve7Lom__GU9J74hq2NIQj4O3nOZJrp3mcUr5MptkXsI14juMOIM9mNZnM4zEUFT2JLVaFhcOfuuWz3IWEDtBf6I0DPc nullable: true ph: description: Sha256 hashes of user's phone numbers, only digits with country code, area code, and number. Remove any symbols, letters, spaces and leading zeros. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA. The string should be in the UTF-8 format. type: array items: type: string example: - 45df139772a81b6011bdc1c9cc3d1cb408fc0b10ec0c5cb9d4d4e107f0ddc49d st: description: Sha256 hashes of user's state, given as a two-letter code in lowercase. User residency state (mostly billing). The string should be in the UTF-8 format. type: array items: type: string example: - 49a6d05b8e4b516656e464271d9dd38d0a7e0142f7f49546f4dabd2720cafc34 zp: description: Sha256 hashes of user's zipcode, only digits. User residency zipcode (mostly billing). The string should be in the UTF-8 format. type: array items: type: string example: - fd5f56b40a79a385708428e7b32ab996a681080a166a2206e750eb4819186145 ConversionHealthSelectionItem: description: User selection of conversion health criteria for a single feature type: object properties: conversionType: description: Status for conversion types type: object criteria: description: Status for criteria type: object ingestionSource: description: Status for ingestion sources type: object status: description: Overall status for this selection item example: conversionType: type_1: status: SELECTED criteria: criteria_1: status: DISMISSED ingestionSource: source_1: status: SELECTED status: SELECTED required: - status ConversionLearningModeType: description: oCPM learn mode. type: string enum: - NOT_ACTIVE - ACTIVE - null nullable: true ConversionMSOTEvents: description: Object containing the MSOT conversion events. type: object title: Conversion MSOT Events ConversionMSOTEventsCreate: description: Resource create operation model. type: object properties: action_timestamps: description: Timestamp(s) when the ad action(s) happened. Unix timestamp in seconds. type: array items: type: integer format: int64 example: - 1451410040 ad_group_id: description: The ID of the ad group that was attributed to the conversion event. example: '2680060704746' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' attribution_model: description: The attribution model used to attribute the conversion event. example: multi_touch allOf: - $ref: '#/components/schemas/AttributionModel' attribution_scope: description: Ad event type. example: click allOf: - $ref: '#/components/schemas/AttributionScope' attribution_score: description: Credit given to the attributed ad actions. Allowed values are > 0 and <= 1. type: number format: double example: 0.5 exclusiveMinimum: true maximum: 1 minimum: 0 campaign_id: description: The ID of the campaign that was attributed to the conversion event. example: '626736533506' allOf: - $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' click_window: description: Click window used for attribution (for example, `1d`, `7d`, `30d`, `lifetime`). type: string currency: description: Currency code for the `value` field, required if `value` is present. Currency Codes should be in ISO 4217 standard. allOf: - $ref: '#/components/schemas/Currency' event_id: description: |- A unique id string that identifies this event. If you are already sending us events through Conversions API, then this id should match the event_id sent through Conversions API. type: string example: eventId0001 maxLength: 256 event_name: description: Type of user event. example: add_to_cart allOf: - $ref: '#/components/schemas/MsotEventName' event_timestamp: description: The time when the event occurred. Unix timestamp in seconds. type: integer format: int64 example: 1451431341 total_event_touchpoints: description: Total number of ad events including other non-Pinterest ad platforms. type: integer example: 2 minimum: 1 total_events: description: |- Deprecated: use `total_events_fractional` instead to avoid rounding errors. Total number of conversion events that are reported in one API call. If you are sending one API request for one attributed conversion event then this value should be 1. If you are sending multiple attributed conversion events in one API request then this value should be the total number of attributed conversion events in the request. type: integer example: 2 deprecated: true minimum: 1 total_events_fractional: description: |- Total number of conversion events that are reported in one API call. Use this field instead of `total_events` to send precise fractional values. If you are sending one API request for one attributed conversion event with full credit, this value should be 1.0. For partial attribution, send the exact fractional value (e.g., 0.5 for half credit). type: number format: double exclusiveMinimum: true minimum: 0 value: description: Order value of the conversion event. Required if `event_name` is `add_to_cart` or `checkout`. type: number format: double example: 123.45 view_window: description: View window used for attribution (for example, `1d`, `7d`, `30d`). type: string required: - ad_group_id - event_id - event_name - event_timestamp ConversionObjectiveType: description: |- Intended result of the campaign. You can only update objectives for draft campaigns. `WEB_SESSIONS` and `VIDEO_VIEW` objectives are deprecated. We recommend using `VIDEO_COMPLETION` as an alternative for the latter. type: string enum: - AWARENESS - CONSIDERATION - WEB_CONVERSION - CATALOG_SALES - VIDEO_COMPLETION - APP_INSTALL - SALES - LEADS - CTV_CONSIDERATION ConversionProductAttributionType: description: Conversion product attribution level type: string enum: - DEFAULT - BRAND_ATTRIBUTION ConversionProductReport: type: object properties: message: description: Message returned from the create report request type: string readOnly: true report_status: description: Async report status allOf: - $ref: '#/components/schemas/BulkReportingJobStatus' readOnly: true size: description: Size of the report in bytes type: number readOnly: true token: description: Token returned from the create report request type: string readOnly: true url: description: URL of the report type: string readOnly: true ConversionProductReportBreakdownType: type: string enum: - PRODUCT_BRAND - PRODUCT_CATEGORY - PRODUCT_BRAND_AND_CATEGORY - PRODUCT_SKU - PRODUCT_SKU_GROUP ConversionProductReportCreate: description: Resource create operation model. type: object properties: ad_group_ids: description: |2- List of ad group ids. Only support ad_group_ids field when level of the report is AD_GROUP. type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' example: - '12345678' maxItems: 500 minItems: 1 campaign_ids: description: |2- List of campaign ids. Only support campaign_ids field when level of the report is CAMPAIGN. type: array items: $ref: '#/components/schemas/Pinterest.Lib.IntegerFormatType' example: - '12345678' maxItems: 500 minItems: 1 campaign_objective_types: description: List of values for filtering. Default is ['CONSIDERATION','AWARENESS','WEB_CONVERSION','VIDEO_COMPLETION']. type: array items: $ref: '#/components/schemas/ConversionObjectiveType' maxItems: 7 minItems: 1 click_window_days: description: Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days. default: 30 allOf: - $ref: '#/components/schemas/ConversionAttributionWindowDays' columns: description: Metric and entity columns type: array items: $ref: '#/components/schemas/ConversionProductReportingColumn' conversion_product_attribution_type: description: |2- Required attribution type of the B/C/S report. When the attribution type is BRAND_ATTRIBUTION, start_date for the report must be after 2025-04-01. default: DEFAULT allOf: - $ref: '#/components/schemas/ConversionProductAttributionType' conversion_product_breakdown: description: Report breakdown type. This is used to specify the breakdown of the report by brand, category, or SKU. default: PRODUCT_BRAND allOf: - $ref: '#/components/schemas/ConversionProductReportBreakdownType' conversion_report_time: description: 'The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event.' default: TIME_OF_AD_ACTION allOf: - $ref: '#/components/schemas/ConversionReportTimeType' end_date: description: |2- Metric report end date (UTC). Format: YYYY-MM-DD. A max of 1 year is allowed between the start and end date for reports. type: string example: 2024-04-23 pattern: ^\d{4}-\d{2}-\d{2}$ granularity: description: Report granularity for time-based metric aggregation allOf: - $ref: '#/components/schemas/ConversionProductReportGranularity' level: description: Level of the report allOf: - $ref: '#/components/schemas/ConversionProductReportLevel' product_sku_ids: description: |2- List of SKU ids. Only support product_sku_ids field when report breakdown type is PRODUCT_SKU_GROUP. type: array items: $ref: '#/components/schemas/Pinterest.Lib.AlphaNumericFormatType' example: - WBC45678 - WBC45679 maxItems: 30000 minItems: 2 report_name: description: Name of the conversion product report type: string start_date: description: |2- Metric report start date (UTC). Format: YYYY-MM-DD. Start date must be after 2024-03-16. 7 day minimum time window for report is required. type: string example: 2024-04-17 pattern: ^\d{4}-\d{2}-\d{2}$ view_window_days: description: Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `1` day. default: 30 allOf: - $ref: '#/components/schemas/ConversionAttributionWindowDays' required: - columns - end_date - granularity - level - report_name - start_date ConversionProductReportGranularity: description: |- Report granularity for time-based aggregation: - TOTAL: Metrics are aggregated over the specified date range - WEEK: Metrics are broken down weekly - MONTH: Metrics are broken down monthly type: string enum: - TOTAL - WEEK - MONTH ConversionProductReportLevel: description: Level of the report type: string enum: - ADVERTISER - CAMPAIGN - AD_GROUP ConversionProductReportingColumn: description: Conversion Product Reporting columns type: string example: AD_GROUP_ID enum: - CAMPAIGN_NAME - CAMPAIGN_ID - ADVERTISER_ID - AD_GROUP_ID - CAMPAIGN_OBJECTIVE_TYPE - AD_GROUP_NAME - CONVERSION_PRODUCT_ID - CONVERSION_PRODUCT_BRAND - CONVERSION_PRODUCT_CATEGORY - CONVERSION_PRODUCT_ID_GROUP - TOTAL_CONVERSION_PRODUCT_QUANTITY - TOTAL_WEB_CONVERSION_PRODUCT_QUANTITY - TOTAL_INAPP_CONVERSION_PRODUCT_QUANTITY - TOTAL_OFFLINE_CONVERSION_PRODUCT_QUANTITY - TOTAL_CONVERSION_PRODUCT_VALUE - TOTAL_WEB_CONVERSION_PRODUCT_VALUE - TOTAL_INAPP_CONVERSION_PRODUCT_VALUE - TOTAL_OFFLINE_CONVERSION_PRODUCT_VALUE - TOTAL_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WEB_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_INAPP_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_OFFLINE_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_CHECKOUT_CONVERSION_PRODUCT_QUANTITY - TOTAL_CHECKOUT_CONVERSION_PRODUCT_VALUE - TOTAL_CHECKOUT_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WEB_CHECKOUT_CONVERSION_PRODUCT_QUANTITY - TOTAL_WEB_CHECKOUT_CONVERSION_PRODUCT_VALUE - TOTAL_WEB_CHECKOUT_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_INAPP_CHECKOUT_CONVERSION_PRODUCT_QUANTITY - TOTAL_INAPP_CHECKOUT_CONVERSION_PRODUCT_VALUE - TOTAL_INAPP_CHECKOUT_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_OFFLINE_CHECKOUT_CONVERSION_PRODUCT_QUANTITY - TOTAL_OFFLINE_CHECKOUT_CONVERSION_PRODUCT_VALUE - TOTAL_OFFLINE_CHECKOUT_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_ADD_TO_CART_CONVERSION_PRODUCT_QUANTITY - TOTAL_ADD_TO_CART_CONVERSION_PRODUCT_VALUE - TOTAL_ADD_TO_CART_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WEB_ADD_TO_CART_CONVERSION_PRODUCT_QUANTITY - TOTAL_WEB_ADD_TO_CART_CONVERSION_PRODUCT_VALUE - TOTAL_WEB_ADD_TO_CART_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_INAPP_ADD_TO_CART_CONVERSION_PRODUCT_QUANTITY - TOTAL_INAPP_ADD_TO_CART_CONVERSION_PRODUCT_VALUE - TOTAL_INAPP_ADD_TO_CART_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_PAGE_VISIT_CONVERSION_PRODUCT_QUANTITY - TOTAL_PAGE_VISIT_CONVERSION_PRODUCT_VALUE - TOTAL_PAGE_VISIT_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WEB_PAGE_VISIT_CONVERSION_PRODUCT_QUANTITY - TOTAL_WEB_PAGE_VISIT_CONVERSION_PRODUCT_VALUE - TOTAL_WEB_PAGE_VISIT_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_SIGNUP_CONVERSION_PRODUCT_QUANTITY - TOTAL_SIGNUP_CONVERSION_PRODUCT_VALUE - TOTAL_SIGNUP_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WEB_SIGNUP_CONVERSION_PRODUCT_QUANTITY - TOTAL_WEB_SIGNUP_CONVERSION_PRODUCT_VALUE - TOTAL_WEB_SIGNUP_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_INAPP_SIGNUP_CONVERSION_PRODUCT_QUANTITY - TOTAL_INAPP_SIGNUP_CONVERSION_PRODUCT_VALUE - TOTAL_INAPP_SIGNUP_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_OFFLINE_SIGNUP_CONVERSION_PRODUCT_QUANTITY - TOTAL_OFFLINE_SIGNUP_CONVERSION_PRODUCT_VALUE - TOTAL_OFFLINE_SIGNUP_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WATCH_VIDEO_CONVERSION_PRODUCT_QUANTITY - TOTAL_WATCH_VIDEO_CONVERSION_PRODUCT_VALUE - TOTAL_WATCH_VIDEO_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WEB_WATCH_VIDEO_CONVERSION_PRODUCT_QUANTITY - TOTAL_WEB_WATCH_VIDEO_CONVERSION_PRODUCT_VALUE - TOTAL_WEB_WATCH_VIDEO_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_LEAD_CONVERSION_PRODUCT_QUANTITY - TOTAL_LEAD_CONVERSION_PRODUCT_VALUE - TOTAL_LEAD_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WEB_LEAD_CONVERSION_PRODUCT_QUANTITY - TOTAL_WEB_LEAD_CONVERSION_PRODUCT_VALUE - TOTAL_WEB_LEAD_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_OFFLINE_LEAD_CONVERSION_PRODUCT_QUANTITY - TOTAL_OFFLINE_LEAD_CONVERSION_PRODUCT_VALUE - TOTAL_OFFLINE_LEAD_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_SEARCH_CONVERSION_PRODUCT_QUANTITY - TOTAL_SEARCH_CONVERSION_PRODUCT_VALUE - TOTAL_SEARCH_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WEB_SEARCH_CONVERSION_PRODUCT_QUANTITY - TOTAL_WEB_SEARCH_CONVERSION_PRODUCT_VALUE - TOTAL_WEB_SEARCH_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_INAPP_SEARCH_CONVERSION_PRODUCT_QUANTITY - TOTAL_INAPP_SEARCH_CONVERSION_PRODUCT_VALUE - TOTAL_INAPP_SEARCH_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_VIEW_CATEGORY_CONVERSION_PRODUCT_QUANTITY - TOTAL_VIEW_CATEGORY_CONVERSION_PRODUCT_VALUE - TOTAL_VIEW_CATEGORY_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WEB_VIEW_CATEGORY_CONVERSION_PRODUCT_QUANTITY - TOTAL_WEB_VIEW_CATEGORY_CONVERSION_PRODUCT_VALUE - TOTAL_WEB_VIEW_CATEGORY_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_CUSTOM_CONVERSION_PRODUCT_QUANTITY - TOTAL_CUSTOM_CONVERSION_PRODUCT_VALUE - TOTAL_CUSTOM_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WEB_CUSTOM_CONVERSION_PRODUCT_QUANTITY - TOTAL_WEB_CUSTOM_CONVERSION_PRODUCT_VALUE - TOTAL_WEB_CUSTOM_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_OFFLINE_CUSTOM_CONVERSION_PRODUCT_QUANTITY - TOTAL_OFFLINE_CUSTOM_CONVERSION_PRODUCT_VALUE - TOTAL_OFFLINE_CUSTOM_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_UNKNOWN_CONVERSION_PRODUCT_QUANTITY - TOTAL_UNKNOWN_CONVERSION_PRODUCT_VALUE - TOTAL_UNKNOWN_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WEB_UNKNOWN_CONVERSION_PRODUCT_QUANTITY - TOTAL_WEB_UNKNOWN_CONVERSION_PRODUCT_VALUE - TOTAL_WEB_UNKNOWN_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_INAPP_UNKNOWN_CONVERSION_PRODUCT_QUANTITY - TOTAL_INAPP_UNKNOWN_CONVERSION_PRODUCT_VALUE - TOTAL_INAPP_UNKNOWN_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_OFFLINE_UNKNOWN_CONVERSION_PRODUCT_QUANTITY - TOTAL_OFFLINE_UNKNOWN_CONVERSION_PRODUCT_VALUE - TOTAL_OFFLINE_UNKNOWN_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_ADD_PAYMENT_INFO_CONVERSION_PRODUCT_QUANTITY - TOTAL_ADD_PAYMENT_INFO_CONVERSION_PRODUCT_VALUE - TOTAL_ADD_PAYMENT_INFO_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WEB_ADD_PAYMENT_INFO_CONVERSION_PRODUCT_QUANTITY - TOTAL_WEB_ADD_PAYMENT_INFO_CONVERSION_PRODUCT_VALUE - TOTAL_WEB_ADD_PAYMENT_INFO_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_INAPP_ADD_PAYMENT_INFO_CONVERSION_PRODUCT_QUANTITY - TOTAL_INAPP_ADD_PAYMENT_INFO_CONVERSION_PRODUCT_VALUE - TOTAL_INAPP_ADD_PAYMENT_INFO_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_OFFLINE_ADD_PAYMENT_INFO_CONVERSION_PRODUCT_QUANTITY - TOTAL_OFFLINE_ADD_PAYMENT_INFO_CONVERSION_PRODUCT_VALUE - TOTAL_OFFLINE_ADD_PAYMENT_INFO_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_ADD_TO_WISHLIST_CONVERSION_PRODUCT_QUANTITY - TOTAL_ADD_TO_WISHLIST_CONVERSION_PRODUCT_VALUE - TOTAL_ADD_TO_WISHLIST_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WEB_ADD_TO_WISHLIST_CONVERSION_PRODUCT_QUANTITY - TOTAL_WEB_ADD_TO_WISHLIST_CONVERSION_PRODUCT_VALUE - TOTAL_WEB_ADD_TO_WISHLIST_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_INAPP_ADD_TO_WISHLIST_CONVERSION_PRODUCT_QUANTITY - TOTAL_INAPP_ADD_TO_WISHLIST_CONVERSION_PRODUCT_VALUE - TOTAL_INAPP_ADD_TO_WISHLIST_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_OFFLINE_ADD_TO_WISHLIST_CONVERSION_PRODUCT_QUANTITY - TOTAL_OFFLINE_ADD_TO_WISHLIST_CONVERSION_PRODUCT_VALUE - TOTAL_OFFLINE_ADD_TO_WISHLIST_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_INITIATE_CHECKOUT_CONVERSION_PRODUCT_QUANTITY - TOTAL_INITIATE_CHECKOUT_CONVERSION_PRODUCT_VALUE - TOTAL_INITIATE_CHECKOUT_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WEB_INITIATE_CHECKOUT_CONVERSION_PRODUCT_QUANTITY - TOTAL_WEB_INITIATE_CHECKOUT_CONVERSION_PRODUCT_VALUE - TOTAL_WEB_INITIATE_CHECKOUT_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_INAPP_INITIATE_CHECKOUT_CONVERSION_PRODUCT_QUANTITY - TOTAL_INAPP_INITIATE_CHECKOUT_CONVERSION_PRODUCT_VALUE - TOTAL_INAPP_INITIATE_CHECKOUT_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_OFFLINE_INITIATE_CHECKOUT_CONVERSION_PRODUCT_QUANTITY - TOTAL_OFFLINE_INITIATE_CHECKOUT_CONVERSION_PRODUCT_VALUE - TOTAL_OFFLINE_INITIATE_CHECKOUT_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_SUBSCRIBE_CONVERSION_PRODUCT_QUANTITY - TOTAL_SUBSCRIBE_CONVERSION_PRODUCT_VALUE - TOTAL_SUBSCRIBE_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WEB_SUBSCRIBE_CONVERSION_PRODUCT_QUANTITY - TOTAL_WEB_SUBSCRIBE_CONVERSION_PRODUCT_VALUE - TOTAL_WEB_SUBSCRIBE_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_INAPP_SUBSCRIBE_CONVERSION_PRODUCT_QUANTITY - TOTAL_INAPP_SUBSCRIBE_CONVERSION_PRODUCT_VALUE - TOTAL_INAPP_SUBSCRIBE_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_OFFLINE_SUBSCRIBE_CONVERSION_PRODUCT_QUANTITY - TOTAL_OFFLINE_SUBSCRIBE_CONVERSION_PRODUCT_VALUE - TOTAL_OFFLINE_SUBSCRIBE_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_VIEW_CONTENT_CONVERSION_PRODUCT_QUANTITY - TOTAL_VIEW_CONTENT_CONVERSION_PRODUCT_VALUE - TOTAL_VIEW_CONTENT_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_WEB_VIEW_CONTENT_CONVERSION_PRODUCT_QUANTITY - TOTAL_WEB_VIEW_CONTENT_CONVERSION_PRODUCT_VALUE - TOTAL_WEB_VIEW_CONTENT_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_INAPP_VIEW_CONTENT_CONVERSION_PRODUCT_QUANTITY - TOTAL_INAPP_VIEW_CONTENT_CONVERSION_PRODUCT_VALUE - TOTAL_INAPP_VIEW_CONTENT_CONVERSION_PRODUCT_VALUE_IN_USD - TOTAL_OFFLINE_VIEW_CONTENT_CONVERSION_PRODUCT_QUANTITY - TOTAL_OFFLINE_VIEW_CONTENT_CONVERSION_PRODUCT_VALUE - TOTAL_OFFLINE_VIEW_CONTENT_CONVERSION_PRODUCT_VALUE_IN_USD ConversionReportAttributionType: description: Attribution type. Refers to the Pinterest Tag endpoints type: string example: INDIVIDUAL enum: - INDIVIDUAL - HOUSEHOLD ConversionReportTimeType: description: Conversion report time type type: string example: TIME_OF_AD_ACTION enum: - TIME_OF_AD_ACTION - TIME_OF_CONVERSION ConversionTag: type: object properties: ad_account_id: description: Ad account ID. type: string example: '549755885175' readOnly: true status: allOf: - $ref: '#/components/schemas/EntityStatus' readOnly: true allOf: - $ref: '#/components/schemas/ConversionTagCommon' required: - ad_account_id ConversionTagCommon: type: object properties: code_snippet: description: Tag code snippet. type: string example: