{ "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.\n - 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.\nAn 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.\n\nYou can set up up to 50 ad accounts per user. (The user must have a business account to create an ad account.)\nFor 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).\n**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).\n\nFor more information, [click here](https://help.pinterest.com/en/business/article/campaign-structure).\n\n**Notes:**\n- `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.\n\nMicrocurrency 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.\n\n**Equivalency equations**, using dollars as an example currency:\n- $1 = 1,000,000 microdollars\n- 1 microdollar = $0.000001\n\n**To convert between currency and microcurrency**, using dollars as an example currency:\n- To convert dollars to microdollars, multiply dollars by 1,000,000\n- To convert microdollars to dollars, divide microdollars by 1,000,000\n\n- 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.\n- 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.\n- 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.\n\n- 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.\n- 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.\n- 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.\nPotential audience size estimates the number of people you may be able to reach per month with your campaign.\nIt is based on historical advertising data and the targeting criteria you select.\nIt 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\").\n\n- 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.\n- 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.\n- 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.\n\nIf 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).)\n\nYou 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:\n - Listed campaign ids or ad group ids or ad ids\n - Listed entity statuses\n\nIf no filter is provided, all ads in the ad account are returned.\n\n**Note:**\nProvide only `campaign_id` or `ad_group_id` or `ad_id`. Do not provide more than one type.\n\nReview status is provided for each ad; if `review_status` is `REJECTED`, the `rejected_reasons` field will contain additional information.\n\nFor 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": " Get analytics for the specified ads in the specified `ad_account_id`, filtered by the specified options.\n - 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.\n - The request must contain either ad_ids or both campaign_ids and pin_ids.\n - 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.\n - 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\").\n\n* 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.\n* 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.\n* 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\ncontain additional information from the Ad Review process.\nFor 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.\n\n**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.\n\n**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": " Get analytics for the specified `ad_account_id`, filtered by the specified options.\n\n - 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.\n\n - 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.\n\n - 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.\n\n[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.\n\nThis 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.\n\nThis 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.\n\nMicrocurrency is used to track very small transactions, based on the currency set in the advertiser's profile.\n\nA microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser's profile.\n\n**Equivalency equations**, using dollars as an example currency:\n\n* $1 = 1,000,000 microdollars\n* 1 microdollar = $0.000001\n\n**To convert between currency and microcurrency**, using dollars as an example currency:\n\n* To convert dollars to microdollars, mutiply dollars by 1,000,000\n* To convert microdollars to dollars, divide microdollars by 1,000,000\n\nFor 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.\n\n**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,\nkeywords, schedules,and/or labels; can filter by campaigns. Though the entities may be active, archived, or paused,\nonly 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.\nNote that this request will be processed asynchronously; the response will include a request_id\nthat 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\nnew 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.\nEach 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.\nReturns 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.\nAll 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.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary\nroles 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\nand houses one or more ad groups, which contain one or more ads.\n\nFor more, see [Set up your campaign](https://help.pinterest.com/en/business/article/set-up-your-campaign/).\n\n**Note:**\n- 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).\n\nMicrocurrency is used to track very small transactions, based on the currency set in the advertiser's profile.\n\nA microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser's profile.\n\n**Equivalency equations**, using dollars as an example currency:\n\n- $1 = 1,000,000 microdollars\n- 1 microdollar = $0.000001\n\n**To convert between currency and microcurrency**, using dollars as an example currency:\n\n- To convert dollars to microdollars, multiply dollars by 1,000,000\n- 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.\n\n**Note:**\n- 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).\n\nMicrocurrency is used to track very small transactions, based on the currency set in the advertiser's profile.\n\nA microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser's profile.\n\n**Equivalency equations**, using dollars as an example currency:\n\n- $1 = 1,000,000 microdollars\n- 1 microdollar = $0.000001\n\n**To convert between currency and microcurrency**, using dollars as an example currency:\n\n- To convert dollars to microdollars, multiply dollars by 1,000,000\n- 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.\n- 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.\n- 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.\n- 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\n\n**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\").\n\n* 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.\n* 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.\n* 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.**\n[Learn more](/docs/key-concepts/using-beta-and-restricted-features/).\nGet 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.**\n[Learn more](/docs/key-concepts/using-beta-and-restricted-features/).\nCreate a request to delete conversion data for a list of user emails and/or EPIKs, limited to the specified `ad_account_id`.\nAfter 72 hours the request is processed and submitted to our deletion process. Then the deletion process ensures deletion\nwithin 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.**\n[Learn more](/docs/key-concepts/using-beta-and-restricted-features/).\nGet 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.**\n[Learn more](/docs/key-concepts/using-beta-and-restricted-features/).\nDelete a conversion deletion request from `ad_account_id` with `request_id`.\nThis will cancel the request and prevent it from being processed. This can only be\ndone 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.\n\n[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.\n\nThe 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.\n\nFor more information, see:\n\n[Set up the Pinterest tag](https://help.pinterest.com/en/business/article/set-up-the-pinterest-tag)\n\n[Pinterest Tag](/docs/track-conversions/pinterest-tag/)\n\n[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.\n\n(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).\n\nA 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.\n\n**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.**\n \nWhen 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.\n \nTo 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.)\n\nWhen 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.\n\nFor 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.\n\nNote: Each part must be at least 5mb; however the last part can be any size greater than 0.\nClients with smaller files can request a single part count. This minimal part size restriction is defined by the AWS S3 API.\n\n**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.\n- 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 `).\n- 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.)\n- This endpoint has a rate limit of 5,000 calls per minute per ad account.\n- 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": " 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`.\n\n For more information, see [Keyword targeting](https://help.pinterest.com/en/business/article/keyword-targeting).\n\n **Notes:**\n - Advertisers and campaigns can only be assigned keywords with excluding (`_NEGATIVE`).\n - All keyword match types are available for ad groups.\n\n For more information on match types, see [match type enums](/docs/api-features/targeting-overview/).\n\n **Returns:**\n - A successful call returns an object containing an array of new keyword objects and an empty `errors` object array.\n - An unsuccessful call returns an empty keywords array, and instead, inserts the entire object with nulled/negated properties into the `errors` object array:\n ```json\n {\n \"keywords\": [],\n \"errors\": [\n {\n \"data\": {\n \"archived\": null,\n \"match_type\": \"EXACT\",\n \"parent_type\": null,\n \"value\": \"foobar\",\n \"parent_id\": null,\n \"type\": \"keyword\",\n \"id\": null\n },\n \"error_messages\": [\n \"Advertisers and Campaigns only accept excluded targeting attributes.\"\n ]\n }\n ]\n }", "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": " 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).\n\n **Notes:**\n - Advertisers and campaigns can only be assigned keywords with excluding (`_NEGATIVE`).\n - All keyword match types are available for ad groups.\n\n For more information on match types, see [match type enums](/docs/api-features/targeting-overview/).\n\n **Returns:**\n - A successful call returns an object containing an array of new keyword objects and an empty `errors` object array.\n - An unsuccessful call returns an empty keywords array, and instead, inserts the entire object with nulled/negated properties into the `errors` object array:\n ```json\n {\n \"keywords\": [],\n \"errors\": [\n {\n \"data\": {\n \"archived\": null,\n \"match_type\": \"EXACT\",\n \"parent_type\": null,\n \"value\": \"foobar\",\n \"parent_id\": null,\n \"type\": \"keyword\",\n \"id\": null\n },\n \"error_messages\": [\n \"Advertisers and Campaigns only accept excluded targeting attributes.\"\n ]\n }\n ]\n }", "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": " Update one or more keywords' bid and archived fields. Archiving\n a keyword effectively deletes it - keywords no longer receive metrics and\n 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": " See keyword metrics for a specified country, aggregated across all of Pinterest.\n (Definitions are available from the \"Get delivery metrics definitions\"\n [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/)\n\nSee a list of labels for assets that your account owns, and filter the list by different criteria.\nIf 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/)\n\nApply one or more labels to a campaign.\nFuture releases may support labels for other [entities](/docs/key-concepts/pinterest-entities/).\nCurrently, you can apply brand and custom labels. Future releases will provide more options.\n\n**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/)\n\nChange 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": " [Closed beta](/docs/getting-started/using-beta-and-restricted-features/)\n\n Apply a label to one or more campaigns.\n Future releases may support labels for other [entities](/docs/key-concepts/pinterest-entities/) in addition to campaigns.\n Currently, you can apply **brand** and **custom** labels. Future releases will provide more options.\n\n **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": " [Closed beta](/docs/getting-started/using-beta-and-restricted-features/)\n\n 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.**\n\nList lead forms associated with an ad account ID.\n\nFor 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.**\n\nCreate 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.\n\nFor 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.**\n\nUpdate 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.\n\nFor 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.**\n\nGets a lead form given it's ID. It must also be associated with the provided ad account ID.\n\nFor 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.\n- 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.\nSubscriptions 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.\n - Only requests for the OWNER or ADMIN of the ad_account will be allowed.\n - Advertisers can set up multiple integrations using ad_account_id + lead_form_id but only one integration per unique records.\n - 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.\n - 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.\n - 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.**\n\nCreate 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.\n\nNote: Lead ad data will be available up to 30 days after the lead has been submitted.\n\nFor 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.**\n\nGet 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.\n\nNote: Lead ad data will be available up to 30 days after the lead has been submitted.\n\nFor 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": " Get an mmm report for an ad account. This returns a URL to an\n 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": " This creates an asynchronous mmm report based on the given request.\n It returns a token that you can use to download the report when it is\n ready. NOTE: An additional limit of 5 queries per minute per advertiser\n applies to this endpoint while it's in beta release.\n For the ADVERTISER_PAID_SPEND_IN_DOLLAR,\n ADVERTISER_PAID_ECPC_IN_DOLLAR, and ADVERTISER_PAID_ECPM_IN_DOLLAR\n columns: if you receive bonus media, this value still includes that spend, and it will\n need to be removed manually with support from your Pinterest account team for a\n fully netted value. Over time, we'll also subtract bonus media and other incentives as\n 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.**\nIf you are interested in joining the beta, reach out to your Pinterest account manager.\n\nAdvertisers or their measurement partners can send attributed MSOT conversion events to Pinterest\nbased on their `ad_account_id`. The request body should be a JSON object.\n\n- 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.\n- 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.\n- 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.\n- 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.\n\nInclude either ad_group_id or product_group_promotion_ids in your request.\n\n**Note:** ad_group_ids and product_group_promotion_ids are mutually exclusive parameters.\nOnly 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.\n\n- 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.\n- 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.\n- 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\napplied to an ad group. Can be either internally-saved promotions or external\npromotions 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": " This returns a URL to an analytics report given a token returned from the post request report creation call.\n You can use the URL to download the report. The link is valid for five minutes and the report is valid for one hour.\n - 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": " This returns a token that you can use to download the report when it is ready.\n 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.\n - 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.\n - 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.\n - 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.\n - 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.\n - 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": " [Restricted](/docs/getting-started/using-beta-and-restricted-features/)\n 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": " [Restricted](/docs/getting-started/using-beta-and-restricted-features/)\n 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.\nA string message is returned indicating the status of the delete operation.\n\nNote: This endpoint is only allowed in the Pinterest API Sandbox (https://api-sandbox.pinterest.com/v5).\nGo 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": " Get Salesforce account details including bill-to information to be used in insertion orders process for `ad_account_id`.\n - 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": " Create insertion order through SSIO for `ad_account_id`.\n - 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": " Edit insertion order through SSIO for `ad_account_id`.\n - 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": " Get insertion order status for `ad_account_id`.\n - 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": " Get insertion order status for `pin_order_id`.\n - 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": " Get Salesforce order lines for account id `ad_account_id`.\n - 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.\nFor the requested account and metrics, the response will include the requested metric information\n(e.g. SPEND_IN_DOLLAR) for the requested target type (e.g. \"age_bucket\") for applicable values (e.g. \"45-49\").

\n\n* 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.\n* 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.\n* 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.\n\nTemplates 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": " This takes a template ID and an optional custom timeframe and\n constructs an asynchronous report based on the template. It returns\n 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.\n\nThe 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.\n\nOptional: 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`.\n\nThis 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`.\n\nThe 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.\n\nOptional: 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`.\n\nThis 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\".\nOptional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\".\n* 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\nOptional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\".\nOptional: Specify a privacy type (public, protected, or secret) to indicate which boards to return.\n* 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.\n* Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\".\n* 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\".\n* Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\".\n* 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\".\n* Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\".\n* 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.\n- Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\".\n- 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.\nOptional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\".\n- 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.\nOptional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\".\n- 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.\nOptional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\".\n- 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.\nOptional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\".\n- 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.\nOptional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\".\n- 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.\n- 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.\nNote: If the asset has been shared with you, an empty array will be returned. This is because an asset shared with\nyou 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.\n\n- If the business is the owner of the audience, it can share with any ad account within the same business hierarchy.\n- If the business is the recipient of the audience, it can share with any of its owned ad accounts.\n\nThis 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.\n\nThis 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.\n- Invite members to join the business. This would required specifying the following:\n - invite_type=\"MEMBER_INVITE\"\n - business_role=\"EMPLOYEE\" OR business_role=\"BIZ_ADMIN\" (To learn more about business roles, visit\n https://help.pinterest.com/en/business/article/profile-permissions-in-business-access.)\n - members\n- Invite partners to access your business assets. This would require specifying the following:\n - invite_type=\"PARTNER_INVITE\"\n - business_role=\"PARTNER\"\n - partners\n- Request to be a partner so you can access their assets. This would require specifying the following:\n - invite_type=\"PARTNER_REQUEST\"\n - business_role=\"PARTNER\"\n - 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:\n- Request access to a partner's asset. Note: This is only for when no existing partnership exists. If an existing\n partnership exists, use \"Create a request to access an existing partner's assets\" to request access to your\n partner's assets.\n - invite_type=\"PARTNER_REQUEST\"\n- Invite a partner to access your business assets. Note: This is only for when there is no existing partnership.\n If there is an existing partnership, use \"Assign/Update partner asset permissions\" to assign a partner access to\n new assets.\n - invite_type=\"PARTNER_INVITE\"\n- Invite a member to access your business assets. Note: This is only for when there is no existing membership.\n If there is an existing membership, use \"Assign/Update member asset permissions\" to assign a member access to new\n assets.\n - invite_type=\"MEMBER_INVITE\"\n\nTo 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.\nNote: 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:\n- get all assets, regardless of asset type or\n- get assets of one asset type by using the asset_type query.\nThe 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.\n\nIf the assets_summary=TRUE and:\n- partner_type=INTERNAL, the business assets returned are your business assets the partner has access to.\n- partner_type=EXTERNAL, the business assets returned are your partner's business assets the partner has granted you\n 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.\nNote: 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.\nIf your partner already had permissions on the asset, they will be overriden with the new permissions you assign to them.\nTo learn more about permission levels, visit https://help.pinterest.com/en/business/article/business-manager-overview\n\nNote: Not all listed permissions are applicable to each asset type. For example, PROFILE_PUBLISHER would not be\napplicable to an asset of type AD_ACCOUNT. The permission level PROFILE_PUBLISHER is only available to an asset of\nthe 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\n- partner_type=INTERNAL: You will terminate a partner's asset access to your business assets.\n- 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\ngranted your partner access to. If you specify:\n- partner_type=INTERNAL, you will retrieve your business assets that the partner has access to.\n- 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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\n[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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\n[Learn more](/docs/api-features/shopping-overview/)\n\nNote: 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\".\n- By default, the \"operation user_account\" is the token user_account.\n- `country`, `language`, and `feed_id` are only used in retail catalogs.\n- 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.\n\nOptional: 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.\n\n[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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nFor 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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nPlease, be aware that \"default_country\"\nand \"default_locale\" are not required in the spec for forward compatibility\nbut for now the API will not accept requests without those fields.\n\nOptional: 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.\n\nFor 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/).\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf 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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nFor 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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nFor 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/).\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf 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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nFor 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\".\n\nOptional: 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.\n\n[Learn more](/docs/api-features/shopping-overview/)\n\nNote: 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.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\n[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)\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf 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/)\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nNote:\n- Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf you require access, please reach out to your partner manager.\n- 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)\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nNote: 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.\n\n[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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\n[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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\"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.\n[Learn more](/docs/api-features/shopping-overview/)\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf 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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\n[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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\n[Learn more](/docs/api-features/shopping-overview/)\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf 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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\n[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.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\"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.\n[Learn more](/docs/api-features/shopping-overview/)\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf 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.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\n[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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\n[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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\n[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.\n- This endpoint has been implemented in POST to allow for complex filters. This specific POST endpoint is designed to be idempotent.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nNote: This endpoint only supports RETAIL catalog at the moment.\n\n[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.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\nNote: 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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\nUp to 1000 items per request to match catalogs/items.\n\n- Must provide both item_id and store_code to identify a local inventory item.\n\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\n[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\".\n\n- Must provide an array of {item_id, store_code} pairs in item filters to identify local inventory items.\n\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\n[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\".\n- By default, the \"operation user_account\" is the token user_account.\n- Supports optional filtering by store codes.\n\nOptional: 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.\n\n[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\".\n- By default, the \"operation user_account\" is the token user_account.\n- Supports optional filtering by store codes.\n\nOptional: 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.\n\n[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": " Update a local store for a catalog owned by the \"operation user_account\".\n - By default, the \"operation user_account\" is the token user_account.\n - Supports optional filtering by store codes.\n\n 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.\n\n [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": " Delete multiple local stores for a catalog owned by the \"operation user_account\".\n - By default, the \"operation user_account\" is the token user_account.\n - Supports optional filtering by store codes.\n\n 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.\n\n [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.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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.\n\n[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.\nNote: 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.\nNote: 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.\nNote: 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.\n\n**[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.\n\nThe response includes all of the information needed to upload the media to Pinterest.\n\nTo 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`.\n\n**[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.\n\n**[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.\n\nFollow the complete steps for [requesting and refreshing tokens](/docs/getting-started/set-up-authentication-and-authorization/).\n\n**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).\n\nDisregard this note if your app was activated on or after September 25, 2025. You are automatically using the continuous refresh token.\n\nUse [Token Debugger](/docs/developer-tools/token-debugger/) to validate and inspect your access token.\n", "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": " Create a Pin on a board or board section owned by the \"operation user_account\".\n\n 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&...).\n\n- 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/).\n\n**[Learn more](/docs/api-features/creating-boards-and-pins/#creating-video-pins)** about video Pin creation.\n\n**[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": " Get a list of the Pins owned by the \"operation user_account\".\n - By default, the \"operation user_account\" is the token user_account.\n - All Pins owned by the \"operation user_account\" are included, regardless of who owns the board they are on.\n\n Optional: Business Access: Specify an `ad_account_id` to use the owner of that ad_account as the \"operation user_account\".\n\n Disclaimer: There are known performance issues when filtering by field `creative_type` and including protected pins.\n 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/).**\n\nGet analytics for multiple pins owned by the \"operation user_account\" - or on a group board that has been shared with this account.\n- The maximum number of pins supported in a single request is 100.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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:\n\n- For Pins on public or protected boards: Admin, Analyst.\n- For Pins on secret boards: Admin.\n\nIf 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": " Get a Pin owned by the \"operation user_account\" - or on a group board that has been shared with this account.\n - By default, the \"operation user_account\" is the token user_account.\n\n 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:\n\n - For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager.\n - 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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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:\n\n- For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager.\n- For Pins on secret boards: Owner, Admin.\n\n**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": " Delete a Pins owned by the \"operation user_account\" - or on a group board that has been shared with this account.\n - By default, the \"operation user_account\" is the token user_account.\n\n 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:\n\n - For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager.\n - 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.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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:\n\n- For Pins on public or protected boards: Admin, Analyst.\n- For Pins on secret boards: Admin.\n\nIf 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.\n- Maximum 24 product tags can be added in a single request.\n- Duplicate pin_ids in the request will result in an error.\n- If any product tag fails eligibility check, the entire request fails (all-or-nothing).\n- 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.\n- 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.\n- 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\".\n- By default, the \"operation user_account\" is the token user_account.\nOptional: 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:\n\n- For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager.\n- For Pins on secret boards: Owner, Admin.\n\n- Any Pin type can be saved: image Pin, video Pin, Idea Pin, product Pin, etc.\n- 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\n\nfrom pinterest.organic.pins import Pin\n# Pin information can be fetched from profile page or from create/list pin method here:\n# /docs/api/v5/#operation/pins/list\nPIN_ID=\"\"\n\n# Board information can be fetched from profile page or from list board method here:\n# /docs/api/v5/#operation/boards/list\nNEW_BOARD_ID=\"\"\n\npin_save = Pin(pin_id=PIN_ID)\npin_save.save(board_id=NEW_BOARD_ID)\nprint(\"Pin Id: %s, Board Id:%s\" %(pin_save.id, pin_save.board_id))\n" }, { "label": "curl", "lang": "cURL", "source": "# Pin and Board information can be fetched from profile page or from create/list pin method here:\n# /docs/api/v5/#operation/pins/list\n# /docs/api/v5/#operation/boards/list\n\ncurl --request DELETE 'https://api.pinterest.com/v5/pins//save' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"board_id\": \n}'\n" }, { "label": "curl (Sandbox)", "lang": "cURL", "source": "# Pin and Board information can be fetched from profile page or from create/list pin method here:\n# /docs/api/v5/#operation/pins/list\n# /docs/api/v5/#operation/boards/list\n\ncurl --request DELETE 'https://api-sandbox.pinterest.com/v5/pins//save' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"board_id\": \n}'\n" } ], "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.\nThe `display_name` attribute will match how the metric is named in our native tools like Ads Manager.\nSee [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.\n\n**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.\n\nClick [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": " You can use targeting values in ads placement to define your intended audience.\n\n Targeting metrics are organized around targeting specifications.\n\n For more information on ads targeting, see [Audience targeting](https://help.pinterest.com/en/business/article/audience-targeting).\n\n **Sample return:**\n\n ```\n [{\"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\",...}]\n ```", "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.\n- By default, the \"operation user_account\" is the token user_account.\n\nIf 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/).**\n\nGet 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' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json'\n" } ], "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\".\n- By default, the \"operation user_account\" is the token user_account.\n\nIf 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.\n\nExample: 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.\n\nExample: '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.\n\nTrending keywords can be used to inform ad targeting, budget strategy, and creative decisions about which products and Pins will resonate with your audience.\n\nGeographic, 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.\n\nFor 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\"\n- By default, the \"operation user_account\" is the token user_account.\n\n[Understanding Business Access]: https://developers.pinterest.com/docs/getting-started/using-business-access/ \"Understanding Business Access\"\nIf 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\"\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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).\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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).\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: 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/).**\n\nUse 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.\nWarning: 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\nand 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": " The geographic region of interest. Only top trends within the specified region will be returned.\n\n The `region` parameter is formatted as ISO 3166-2 country codes delimited by `+`, corresponding to the following geographic areas:\n - `US` - United States\n - `CA` - Canada\n - `DE` - Germany\n - `FR` - France\n - `ES` - Spain\n - `IT` - Italy\n - `DE+AT+CH` - Germanic countries\n - `GB+IE` - Great Britain & Ireland\n - `IT+ES+PT+GR+MT` - Southern Europe\n - `PL+RO+HU+SK+CZ` - Eastern Europe\n - `SE+DK+FI+NO` - Nordic countries\n - `NL+BE+LU` - Benelux\n - `AR` - Argentina\n - `BR` - Brazil\n - `CO` - Colombia\n - `MX` - Mexico\n - `MX+AR+CO+CL` - Hispanic LatAm\n - `AU+NZ` - Australasia", "schema": { "$ref": "#/components/schemas/TrendsSupportedRegion" } }, "path_trend_type": { "name": "trend_type", "in": "path", "required": true, "description": " The methodology used to rank how trendy a keyword is.\n - `growing` trends have high upward growth in search volume over the last quarter\n - `monthly` trends have high search volume in the last month\n - `yearly` trends have high search volume in the last year\n - `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.\nSee 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.\nNote 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.\nSee 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\nrange(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.\n\nThe assets summary returns a dictionary representing a summary of the assets\nfor the business user ID, with information like the ad accounts and profiles\nthe 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.\n\nThe assets summary returns a dictionary representing a summary of the assets\nfor the business user ID, with information like the ad accounts and profiles\nthe 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.\n\nIf partner_type=INTERNAL, the asset being queried is for accesses the partner has to your business assets.\n\nIf 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.\n\nFor 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).\n\nIf 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.\nValues are joined comma-separated on the wire\n(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.\nWhen 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\nspecified gender(s). If unset, trends among all genders will be returned.\nThe `unknown` group includes users with unspecified or customized gender\nprofile settings.", "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TrendsGenderFilter" } } }, "query_granularity": { "name": "granularity", "in": "query", "required": true, "description": " TOTAL - metrics are aggregated over the specified date range.\n\n DAY - metrics are broken down daily.\n\n HOUR - metrics are broken down hourly.\n\n WEEK - metrics are broken down weekly.\n\n MONTH - metrics are broken down monthly", "schema": { "$ref": "#/components/schemas/Granularity" } }, "query_granularity_async": { "name": "granularity", "in": "query", "required": false, "description": " TOTAL - metrics are aggregated over the specified date range.\n\n DAY - metrics are broken down daily.\n\n HOUR - metrics are broken down hourly.\n\n WEEK - metrics are broken down weekly.\n\n 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\n(`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": " The list of supported interests is:\n - `animals` - Animals\n - `architecture` - Architecture\n - `art` - Art\n - `beauty` - Beauty\n - `childrens_fashion` - Children's Fashion\n - `design` - Design\n - `diy_and_crafts` - DIY & Crafts\n - `education` - Education\n - `electronics` - Electronics\n - `entertainment` - Entertainment\n - `event_planning` - Event Planning\n - `finance` - Finance\n - `food_and_drinks` - Food & Drink\n - `gardening` - Gardening\n - `health` - Health\n - `home_decor` - Home Decor\n - `mens_fashion` - Men's Fashion\n - `parenting` - Parenting\n - `quotes` - Quotes\n - `sport` - Sports\n - `travel` - Travel\n - `vehicles` - Vehicles\n - `wedding` - Wedding\n - `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\nthe 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": " Governs how the resulting time series data will be normalized to a [0-100] scale.\n\n 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.\n\n 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.\nIf partner_type=INTERNAL, the asset being queried is for accesses the partner has to your business assets.\nIf 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\nand total reactions are only available with lifetime Pin metrics. If Pin was\ncreated before `2023-03-20` lifetime metrics will only be available\nfor Video and Idea Pin formats. Lifetime metrics are available for all Pin\nformats 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": " The geographic region of interest. Only top product categories within the specified region will be returned.\n The `region` parameter is formatted as ISO 3166-2 country codes delimited by `+`.\n\n - `US` - United States\n - `GB+IE` - Great Britain & Ireland\n - `CA` - Canada", "schema": { "$ref": "#/components/schemas/ProductCategoryRegion" } }, "query_product_category_engagement_type": { "name": "engagement_type", "in": "query", "required": false, "description": " Type of engagement metric to analyze.\n- `ENGAGEMENT` - Overall engagement metric\n- `OUTBOUND_CLICK` - Number of outbound clicks\n- `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": " 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.\n - `90` - Last 90 days (3 months)\n - `180` - Last 180 days (6 months)\n - `365` - Last 365 days (1 year)\n - `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\npin 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\nare returned in trend-ranked order, so a `limit` of 50 will return the\ntop 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.\nDefault 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": " User account board count.\n **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:\\\n\"field\": The column name\\\n\"operator\": The operator. Allowed operators: [\"=\", \"!=\", \"in\", \"not_in\", \"~\", \">\", \"<\", \"contains_substring\"]\\\n\"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:\nCUSTOMER_LIST: { \"customer_list_id\": \"\"}\nACTALIKE: { \"seed_id\": [\"\"], \"country\": \"US\", \"percentage\": \"10\" }\n(Valid countries include: \"US\", \"CA\", and \"GB\". Percentage should be 1-10.\nThe targeted audience should be this % size across Pinterest.)\nVISITOR: { \"visitor_source_id\": [\"\"], \"retention_days\": \"180\", \"event_source\": {\"=\": [\"web\", \"mobile\"]}, \"ingestion_source\": {\"=\": [\"tag\"]}}\n(Retention days should be 1-540. Retention applies to specific customers.)\nENGAGEMENT: {\"engagement_domain\": [\"www.example.com\"], \"engager_type\": 1}\nLearn 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`.\nFor ENGAGEMENT, it is the engaged pin's URL.\nFor VISITOR, you can use it as a string or a {operator: value} object for filtering visitors based on conversion tag event URLs.\nSupported operators are [ =, !=, contains, not_contains].\nExample 1: \"url\": \"http://www.myonlinestore123.com/view_item/shoe\"\nExample 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). \nFor certain organizations ([Closed beta](https://help.pinterest.com/en/business/article/beta-features)): Supported for campaigns with Campaign Budget Optimization (CBO). \nFor 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). \nFor certain organizations ([Closed beta](https://help.pinterest.com/en/business/article/beta-features)): Supported for campaigns with Campaign Budget Optimization (CBO). \nFor 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.\nFor certain organizations (Closed beta): Supported for campaigns with Campaign Budget Optimization (CBO).\nFor 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.\nFor certain organizations (Closed beta): Supported for campaigns with Campaign Budget Optimization (CBO).\nFor 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": "Open beta\nBid multiplier for ad group. This value is a double between 0.1\nand 10.0. Enter 0 to remove the bid multiplier.\n- Make sure the `bid_strategy` type for your ad group is set to `AUTOMATIC_BID`.\n- Not currently supported for 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": "Open beta\nBid multiplier for ad group. This value is a double between 0.1\nand 10.0. Enter 0 to remove the bid multiplier.\n- Make sure the `bid_strategy` type for your ad group is set to `AUTOMATIC_BID`.\n- Not currently supported for 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": " Third-party tracking URLs. Up to three tracking URLs - with a max length of 2,000 - are supported for\n each event type. Tracking URLs set at the ad group or ad level can override\n 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). \nFor certain organizations ([Closed beta](https://help.pinterest.com/en/business/article/beta-features)): Supported for campaigns with Campaign Budget Optimization (CBO). \nFor 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.\nFor certain organizations (Closed beta): Supported for campaigns with Campaign Budget Optimization (CBO).\nFor 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.\nFor certain organizations (Closed beta): Supported for campaigns with Campaign Budget Optimization (CBO).\nFor 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": "Open beta\nBid multiplier for ad group. This value is a double between 0.1\nand 10.0. Enter 0 to remove the bid multiplier.\n- Make sure the `bid_strategy` type for your ad group is set to `AUTOMATIC_BID`.\n- Not currently supported for 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.
\n
\n
NOTE: The targeting_spec and targeting_spec_operations cannot be sent at the same time.
\n
\n
The supported operations are:
\n\n
Note the following:
\n", "type": "array", "items": { "$ref": "#/components/schemas/TargetingSpecOperations" } } } } ], "title": "AdGroupUpdateRequest" }, "AdGroupUpdateRequestAllOf1": { "type": "object", "properties": { "bid_multiplier": { "description": "Open beta\nBid multiplier for ad group. This value is a double between 0.1\nand 10.0. Enter 0 to remove the bid multiplier.\n- Make sure the `bid_strategy` type for your ad group is set to `AUTOMATIC_BID`.\n- Not currently supported for 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.
\n
\n
NOTE: The targeting_spec and targeting_spec_operations cannot be sent at the same time.
\n
\n
The supported operations are:
\n\n
Note the following:
\n", "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.\nFor example: https://ads.pinterest.com/ad-preview/74667c814dd2b19/\nThe 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": " TOTAL - metrics are aggregated over the specified date range.\n DAY - metrics are broken down daily.\n HOUR - metrics are broken down hourly.\n WEEKLY - metrics are broken down weekly.\n 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.\nRestricted 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.\n\nMultiplier 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.\n\nMultiplier 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\npermissions on various assets. If accepting an invite or request, this object would be used to grant\nasset 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:\n\nCUSTOMER_LIST: { \"customer_list_id\": \"<customer list ID>\"}\n\nACTALIKE: { \"seed_id\": [\"<audience ID>\"], \"country\": \"US\", \"percentage\": \"10\" }\n(Valid countries include: \"US\", \"CA\", and \"GB\". Percentage should be 1-10.\nThe targeted audience should be this % size across Pinterest.)\n\nVISITOR: { \"visitor_source_id\": [\"<conversion tag ID>\"], \"retention_days\": \"180\", \"event_source\": {\"=\": [\"web\", \"mobile\"]}, \"ingestion_source\": {\"=\": [\"tag\"]}}\n(Retention days should be 1-540. Retention applies to specific customers.)\n\nENGAGEMENT: {\"engagement_domain\": [\"www.example.com\"], \"engager_type\": 1}\nLearn 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.\nYou can only update objectives for draft campaigns.\n`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.\n\nValues 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.\n\nValues 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\n\nValues 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.\n\nValues 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.\n\nValues 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": " Privacy setting for a board. Learn more about [secret](https://help.pinterest.com/en/article/secret-boards)\n boards and [protected](https://help.pinterest.com/en/business/article/protected-boards) boards.\n\n **Note:** If you create an ad-only board by setting `is_ads_only`\n 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": " Name of the board.\n\n **Note:** If you create an ad-only board by setting `is_ads_only`\n 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": " Name of the board.\n\n **Note:** If you create an ad-only board by setting `is_ads_only`\n to `true`, the board name automatically becomes \"Ad-only Pins\".", "type": "string", "example": "Summer recipes" }, "privacy": { "description": " Privacy setting for a board. Learn more about [secret](https://help.pinterest.com/en/article/secret-boards)\n boards and [protected](https://help.pinterest.com/en/business/article/protected-boards) boards.\n\n **Note:** If you create an ad-only board by setting `is_ads_only`\n 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": " Name of the board.\n\n **Note:** If you create an ad-only board by setting `is_ads_only`\n 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.\n- EMPLOYEE: Can only view and access assets you assign them to. They cannot see details about other employees, partners, or other assets.\n- BIZ_ADMIN: Have full control of roles and can add employees and partners as well as grant asset access.\n- 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.\n- EMPLOYEE: Can only view and access assets you assign to them. They cannot see details about other employees, partners, or other assets.\n- 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.\n- EMPLOYEE: Can only view and access assets you assign to them. They cannot see details about other employees, partners, or other assets.\n- 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/)\n\nObject 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.\nFor campaign budget optimization, a daily or lifetime spend cap must be set, but not both.\nFor 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.\nTimestamp 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).\nDifferent end times can be set for the campaign's child ad groups, but they cannot occur after an `end_time` specified for the campaign.\n- 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.\n- 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.\nSpecifies whether the campaign was created in the automated campaign flow.\nWhen using Automated Campaigns, a daily spend cap must be set, and Pinterest Performance+ may not be used.\nThe following objective types are supported:\n- CONSIDERATION\n- WEB\\_CONVERSION\n- SALES\n- LEADS\n- 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.\nDetermines if a campaign automatically generates ad-group level budgets given a campaign budget to maximize campaign outcome.\nWhen 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\".\nFlexible 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.\nYou can only use this feature with the following objectives:\n- CONSIDERATION\n- WEB\\_CONVERSION\n- SALES\n- LEADS\n- CATALOG\\_SALES\n- APP\\_INSTALL\nEnable 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.\n [Restricted](/docs/getting-started/using-beta-and-restricted-features/)\n Have your ads and content appear at the top of search result lists in Pinterest.\n You can only use this feature with the following objectives:\n - CONSIDERATION\n - WEB\\_CONVERSION\n - SALES\n - LEADS\n - CATALOG\\_SALES\n 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.\nFor campaign budget optimization, a daily or lifetime spend cap must be set, but not both.\nFor 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.\nOrder 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).\nDifferent start times can be set for the campaign's child ad groups, but they cannot occur before a `start_time` specified for the campaign.\n- 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.\n- 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.\n\nMultiplier 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/)\n\nObject 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.\nFor campaign budget optimization, a daily or lifetime spend cap must be set, but not both.\nFor 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.\nTimestamp 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).\nDifferent end times can be set for the campaign's child ad groups, but they cannot occur after an `end_time` specified for the campaign.\n- 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.\n- 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.\nSpecifies whether the campaign was created in the automated campaign flow.\nWhen using Automated Campaigns, a daily spend cap must be set, and Pinterest Performance+ may not be used.\nThe following objective types are supported:\n- CONSIDERATION\n- WEB\\_CONVERSION\n- SALES\n- LEADS\n- 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.\nDetermines if a campaign automatically generates ad-group level budgets given a campaign budget to maximize campaign outcome.\nWhen 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\".\nFlexible 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.\nYou can only use this feature with the following objectives:\n- CONSIDERATION\n- WEB\\_CONVERSION\n- SALES\n- LEADS\n- CATALOG\\_SALES\n- APP\\_INSTALL\nEnable 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.\n [Restricted](/docs/getting-started/using-beta-and-restricted-features/)\n Have your ads and content appear at the top of search result lists in Pinterest.\n You can only use this feature with the following objectives:\n - CONSIDERATION\n - WEB\\_CONVERSION\n - SALES\n - LEADS\n - CATALOG\\_SALES\n 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.\nFor campaign budget optimization, a daily or lifetime spend cap must be set, but not both.\nFor 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.\nOrder 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).\nDifferent start times can be set for the campaign's child ad groups, but they cannot occur before a `start_time` specified for the campaign.\n- 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.\n- 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/)\n\nThe 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/)\n\nPlatform 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.\nFor campaign budget optimization, a daily or lifetime spend cap must be set, but not both.\nFor 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.\nTimestamp 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).\nDifferent end times can be set for the campaign's child ad groups, but they cannot occur after an `end_time` specified for the campaign.\n- 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.\n- 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.\nSpecifies whether the campaign was created in the automated campaign flow.\nWhen using Automated Campaigns, a daily spend cap must be set, and Pinterest Performance+ may not be used.\nThe following objective types are supported:\n- CONSIDERATION\n- WEB\\_CONVERSION\n- SALES\n- LEADS\n- 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.\nDetermines if a campaign automatically generates ad-group level budgets given a campaign budget to maximize campaign outcome.\nWhen 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\".\nFlexible 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.\nYou can only use this feature with the following objectives:\n- CONSIDERATION\n- WEB\\_CONVERSION\n- SALES\n- LEADS\n- CATALOG\\_SALES\n- APP\\_INSTALL\nEnable 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.\n [Restricted](/docs/getting-started/using-beta-and-restricted-features/)\n Have your ads and content appear at the top of search result lists in Pinterest.\n You can only use this feature with the following objectives:\n - CONSIDERATION\n - WEB\\_CONVERSION\n - SALES\n - LEADS\n - CATALOG\\_SALES\n 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.\nFor campaign budget optimization, a daily or lifetime spend cap must be set, but not both.\nFor 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.\nOrder 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).\nDifferent start times can be set for the campaign's child ad groups, but they cannot occur before a `start_time` specified for the campaign.\n- 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.\n- 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/)\n\nThe 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/)\n\nPlatform 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/)\n\nObject 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.\nFor campaign budget optimization, a daily or lifetime spend cap must be set, but not both.\nFor 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.\nTimestamp 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).\nDifferent end times can be set for the campaign's child ad groups, but they cannot occur after an `end_time` specified for the campaign.\n- 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.\n- 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.\nSpecifies whether the campaign was created in the automated campaign flow.\nWhen using Automated Campaigns, a daily spend cap must be set, and Pinterest Performance+ may not be used.\nThe following objective types are supported:\n- CONSIDERATION\n- WEB\\_CONVERSION\n- SALES\n- LEADS\n- 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.\nDetermines if a campaign automatically generates ad-group level budgets given a campaign budget to maximize campaign outcome.\nWhen 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\".\nFlexible 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.\nYou can only use this feature with the following objectives:\n- CONSIDERATION\n- WEB\\_CONVERSION\n- SALES\n- LEADS\n- CATALOG\\_SALES\n- APP\\_INSTALL\nEnable 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.\n [Restricted](/docs/getting-started/using-beta-and-restricted-features/)\n Have your ads and content appear at the top of search result lists in Pinterest.\n You can only use this feature with the following objectives:\n - CONSIDERATION\n - WEB\\_CONVERSION\n - SALES\n - LEADS\n - CATALOG\\_SALES\n 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.\nFor campaign budget optimization, a daily or lifetime spend cap must be set, but not both.\nFor 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.\nOrder 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).\nDifferent start times can be set for the campaign's child ad groups, but they cannot occur before a `start_time` specified for the campaign.\n- 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.\n- 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.\nDifferent end times can be set for the campaign's child ad groups, but they cannot occur after an `end_time` specified for the campaign.\n- 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.\n- 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.\nDifferent start times can be set for the campaign's child ad groups, but they cannot occur before a `start_time` specified for the campaign.\n- 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.\n- 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\n\nHave your ads and content appear at the top of search result lists in Pinterest.\n\nYou can only use this feature with the following objectives:\n`CONSIDERATION`\n`WEB_CONVERSION`\n`CATALOG_SALES`\n\nYou cannot use this feature with Pinterest Performance+ or Premiere Spotlight enabled.\n\nYou 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\n\nHave your ads and content appear at the top of search result lists in Pinterest.\n\nYou can only use this feature with the following objectives:\n`CONSIDERATION`\n`WEB_CONVERSION`\n`CATALOG_SALES`\n\nYou cannot use this feature with Pinterest Performance+ or Premiere Spotlight enabled.\n\nYou 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.\nSpecifies whether the campaign was created in the automated campaign flow.\nWhen using Automated Campaigns, a daily spend cap must be set, and Pinterest Performance+ may not be used.\nThe following objective types are supported:\n- CONSIDERATION\n- WEB\\_CONVERSION\n- SALES\n- CATALOG\\_SALES", "type": "boolean", "nullable": true }, "CampaignIsCampaignBudgetOptimization": { "description": "Note: This field is immutable unless the campaign is in draft status.\nDetermines if a campaign automatically generates ad-group level budgets given a campaign budget to maximize campaign outcome.\nWhen 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\".\nFlexible 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.\nDifferent end times can be set for the campaign's child ad groups, but they cannot occur after an `end_time` specified for the campaign.\n- 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.\n- 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.\nDifferent start times can be set for the campaign's child ad groups, but they cannot occur before a `start_time` specified for the campaign.\n- 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.\n- 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.\n\nThis is a distinct schema. It is not possible to create or update a Product Group with\nempty 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\n\n- **MERCHANT_CREATED**: Product groups created by merchants.\n- **ALL_PRODUCTS**: Consists of every product in your latest successful feed upload.\n- **BEST_DEALS**: Consists of products with the deepest drop in price.\n- **PINNER_FAVORITES**: Consists of products that are resonating most with people on Pinterest, based on engagement.\n- **TOP_SELLERS**: Consists of products with the highest conversion rate, if you have the conversion tag installed.\n- **BACK_IN_STOCK**: Consists of products that were previously out of stock and are now in stock.\n- **NEW_ARRIVALS**: Consists of products that are new to your Catalog.\n- **SHOPIFY_COLLECTIONS**: Product groups created based on Shopify Product Collections.\n- **I2PC**: Product groups created based on predicted product category.\n- **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.\nIf 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.\nIf 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.\nIf 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.\nThe advertiser has a 7 day time window after the conversion deletion request was submitted to cancel it. \"SUBMITTED\" meaning that the Data Deletion\nprocess 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.\nThe advertiser has a 7 day time window after the conversion deletion request was submitted to cancel it. \"SUBMITTED\" meaning that the Data Deletion\nprocess 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.\nSome 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:\nLinux: 6.15. Obtain by running: uname -r\nMacOS: 24.3.0. Obtain by running: sysctl kern.version\nAndroid: 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\nIn 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.\nThis value if specific to os family. Examples:\nWindows: 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\niOS: Dawn\nAndroid: Baklava\nMacOS: Sequoia\nUbuntu Linux: Plucky Puffin", "type": "string", "example": "18.3", "maxLength": 100 }, "os_version": { "description": "Full name of the version. Examples:\niOS: 18.3\nAndroid: 16.1\nMacOS: 15.5\nWindows: 24H2\nUbuntu 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.\n- `app_android`\n- `app_ios`\n- `web`\n- `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.\n\n- `add_payment_info`\n- `add_to_cart`\n- `add_to_wishlist`\n- `app_install`\n- `app_open`\n- `checkout`\n- `contact`\n- `custom`\n- `customize_product`\n- `find_location`\n- `initiate_checkout`\n- `lead`\n- `page_visit`\n- `schedule`\n- `search`\n- `signup`\n- `start_trial`\n- `submit_application`\n- `subscribe`\n- `view_category`\n- `view_content`\n- `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,\nthen 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.\nTotal number of conversion events that are reported in one API call.\n\nIf you are sending one API request for one attributed conversion event then this value should be 1.\nIf you are sending multiple attributed conversion events in one API request then this value should be\nthe 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\n`total_events` to send precise fractional values.\n\nIf you are sending one API request for one attributed conversion event with full credit, this value should be 1.0.\nFor 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.\nYou can only update objectives for draft campaigns.\n`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": " List of ad group ids.\n 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": " List of campaign ids.\n 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": " Required attribution type of the B/C/S report.\n 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": " Metric report end date (UTC). Format: YYYY-MM-DD.\n 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": " List of SKU ids.\n 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": " Metric report start date (UTC). Format: YYYY-MM-DD.\n 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:\n- TOTAL: Metrics are aggregated over the specified date range\n- WEEK: Metrics are broken down weekly\n- 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": "