{ "openapi": "3.0.3", "info": { "version": "5.12.0", "title": "Pinterest REST API", "description": "Pinterest's REST API", "contact": { "name": "Pinterest, Inc.", "url": "https://developers.pinterest.com/" }, "license": { "name": "MIT", "url": "https://spdx.org/licenses/MIT" }, "termsOfService": "https://developers.pinterest.com/terms/" }, "servers": [ { "url": "https://api.pinterest.com/v5" } ], "tags": [ { "name": "ad_accounts", "description": "View analytical information about advertising.\n\n\nNote: If the current operation_user_account (defined by the access token)\nhas access to another user's Ad Accounts via\nPinterest Business Access,\nyou can modify your request to use the current operation_user_account's\npermissions to those Ad Accounts by including the ad_account_id in the path\nparameters for the request (e.g. .../?ad_account_id=12345&...)." }, { "name": "ad_groups", "description": "View, create or update ad groups." }, { "name": "ads", "description": "View, create or update ads." }, { "name": "audience_insights", "description": "View audience insights." }, { "name": "audiences", "description": "View, create, or update audiences." }, { "name": "billing", "description": "View, create, or update information related to billing." }, { "name": "boards", "description": "View, create, update, or delete information about boards." }, { "name": "bulk", "description": "Create, update, or download ads-related entities in bulk." }, { "name": "campaigns", "description": "View, create or update campaigns." }, { "name": "catalogs", "description": "Manage information about shopping product catalogs and items." }, { "name": "conversion_events", "description": "Submit conversion events via the Pinterest API." }, { "name": "conversion_tags", "description": "View, create, or update conversion tags." }, { "name": "customer_lists", "description": "View, create, or update customer lists." }, { "name": "integrations", "description": "View, create, or update commerce integrations." }, { "name": "keywords", "description": "View, create or update keywords." }, { "name": "lead_ads", "description": "View, create, or update lead ads." }, { "name": "lead_forms", "description": "View lead forms." }, { "name": "media", "description": "Register and manage media uploads." }, { "name": "oauth", "description": "Generate and refresh OAuth access tokens." }, { "name": "order_lines", "description": "View order lines." }, { "name": "pins", "description": "View, create, update, or delete information about Pins." }, { "name": "product_group_promotions", "description": "View, create, update, or delete information about promoted product groups." }, { "name": "product_groups", "description": "View, create, update, or delete information about product groups." }, { "name": "resources", "description": "View metadata about available metrics and targeting options in the Pinterest API." }, { "name": "search", "description": "Search for Pins and boards owned by the current user." }, { "name": "terms", "description": "View related and suggested terms for ads targeting." }, { "name": "terms_of_service", "description": "View Advertising Terms Of Service." }, { "name": "user_account", "description": "View user accounts associated with a given access token." } ], "paths": { "/ad_accounts": { "get": { "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.", "tags": [ "ad_accounts" ], "operationId": "ad_accounts/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_include_shared_accounts" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Ad accounts", "items": { "$ref": "#/components/schemas/AdAccount" } } } } ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "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.

\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.", "tags": [ "ad_accounts" ], "operationId": "ad_accounts/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdAccountCreateRequest" } } }, "description": "Ad account to create.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdAccount" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } } } }, "/ad_accounts/{ad_account_id}": { "get": { "summary": "Get ad account", "description": "Get an ad account", "operationId": "ad_accounts/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdAccount" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "ad_accounts" ] } }, "/ad_accounts/{ad_account_id}/ad_groups": { "get": { "summary": "List ad groups", "description": "List ad groups based on provided campaign IDs or ad group IDs.(campaign_ids or ad_group_ids).

\nNote:

\nProvide only campaign_id or ad_group_id. Do not provide both.", "operationId": "ad_groups/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_campaign_ids" }, { "$ref": "#/components/parameters/query_ad_group_ids" }, { "$ref": "#/components/parameters/query_entity_statuses" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_translate_interests_to_names" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdGroupResponse" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid ad account group parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account group parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_groups" ] }, "post": { "summary": "Create ad groups", "description": "Create multiple new ad groups. All ads in a given ad group will have the same budget, bid, run dates, targeting, and placement (search, browse, other). For more information, click here.

\nNote:\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

Microcurrency is used to track very small transactions, based on the currency set in the advertiser’s profile.

\n

A microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser’s profile.

\n

Equivalency equations, using dollars as an example currency:

\n\n

To convert between currency and microcurrency, using dollars as an example currency:

\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- Start and end time cannot be set for ad groups that belong to CBO campaigns. Currently, campaigns with the following objective types: TRAFFIC, AWARENESS, WEB_CONVERSIONS, and CATALOG_SALES will default to CBO.", "operationId": "ad_groups/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AdGroupCreateRequest" }, "maxItems": 30, "minItems": 1, "type": "array" } } }, "description": "List of ad groups to create, size limit [1, 30].", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroupArrayResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "ad_groups" ] }, "patch": { "summary": "Update ad groups", "description": "Update multiple existing ad groups.", "operationId": "ad_groups/update", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AdGroupUpdateRequest" }, "maxItems": 30, "minItems": 1, "type": "array" } } }, "description": "List of ad groups to update, size limit [1, 30].", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroupArrayResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "ad_groups" ] } }, "/ad_accounts/{ad_account_id}/ad_groups/analytics": { "get": { "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- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.\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.", "operationId": "ad_groups/analytics", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$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" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroupsAnalyticsResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account group analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account group analytics parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_groups" ] } }, "/ad_accounts/{ad_account_id}/ad_groups/targeting_analytics": { "get": { "summary": "Get targeting analytics for ad groups", "description": "Get targeting analytics for one or more ad groups.\nFor the requested ad group(s) 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- The token's user_account must either be the Owner of the specified ad account, or have one\nof the necessary roles granted to them via\nBusiness Access: 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.", "operationId": "ad_groups_targeting_analytics/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_ad_group_ids_required" }, { "$ref": "#/components/parameters/query_start_date" }, { "$ref": "#/components/parameters/query_end_date" }, { "$ref": "#/components/parameters/query_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" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsResponse" } } }, "description": "Success" }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_groups" ] } }, "/ad_accounts/{ad_account_id}/ad_groups/audience_sizing": { "get": { "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.", "operationId": "ad_groups/audience_sizing", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroupAudienceSizingRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroupAudienceSizingResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad group audience sizing parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad group audience sizing parameters." } } } }, "403": { "description": "No access to requested audience list or product group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "You don't have access to the requested audience list or product group." } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "ad_groups" ] } }, "/ad_accounts/{ad_account_id}/ad_groups/{ad_group_id}": { "get": { "summary": "Get ad group", "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.", "operationId": "ad_groups/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_ad_group_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdGroupResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "ad_groups" ] } }, "/ad_accounts/{ad_account_id}/ad_previews": { "post": { "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.

\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.)

\nYou can view the returned preview URL on a webpage or iframe for 7 days, after which the URL expires.", "tags": [ "ads" ], "operationId": "ad_previews/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "description": "Create ad preview with pin or image.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdPreviewRequest" } } } }, "responses": { "200": { "description": "Successful ad preview creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdPreviewURLResponse" } } } }, "400": { "description": "Invalid Pin parameters response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidPinUrl": { "value": { "code": 1, "message": "Whoops! It looks like you entered an invalid URL. Try creating a Pin again with a valid URL." } } } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ad_accounts/{ad_account_id}/ads": { "get": { "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

\nIf no filter is provided, all ads in the ad account are returned.

\nNote:

\nProvide only campaign_id or ad_group_id or ad_id. Do not provide more than one type.

\nReview status is provided for each ad; if review_status is REJECTED, the rejected_reasons field will contain additional information.\nFor more, see Pinterest advertising standards.", "operationId": "ads/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$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" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdResponse" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid ad account ads parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account ads parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ads" ] }, "post": { "description": "Create multiple new ads. Request must contain ad_group_id, creative_type, and the source Pin pin_id.", "operationId": "ads/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AdCreateRequest" }, "maxItems": 30, "minItems": 1, "type": "array" } } }, "description": "List of ads to create, size limit [1, 30].", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdArrayResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Create ads", "tags": [ "ads" ] }, "patch": { "description": "Update multiple existing ads", "operationId": "ads/update", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/AdUpdateRequest" }, "maxItems": 30, "minItems": 1, "type": "array" } } }, "description": "List of ads to update, size limit [1, 30]", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdArrayResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Update ads", "tags": [ "ads" ] } }, "/ad_accounts/{ad_account_id}/ads/analytics": { "get": { "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: 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.", "operationId": "ads/analytics", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_start_date" }, { "$ref": "#/components/parameters/query_end_date" }, { "$ref": "#/components/parameters/query_ad_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" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsAnalyticsResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account ads analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account ads analytics parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ads" ] } }, "/ad_accounts/{ad_account_id}/ads_credit/discounts": { "get": { "summary": "Get ads credit discounts", "description": "Returns the list of discounts applied to the account.\n\nThis endpoint might not be available to all apps. Learn more.", "operationId": "ads_credits_discounts/get", "security": [ { "pinterest_oauth2": [ "ads:read", "billing:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "tags": [ "billing" ], "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdsCreditDiscountsResponse" } } } } ] } } }, "description": "Success" }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ad_accounts/{ad_account_id}/ads_credit/redeem": { "post": { "summary": "Redeem ad credits", "description": "Redeem ads credit on behalf of the ad account id and apply it towards billing.\n\nThis endpoint might not be available to all apps. Learn more.", "tags": [ "billing" ], "operationId": "ads_credit/redeem", "security": [ { "pinterest_oauth2": [ "ads:write", "billing:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "description": "Redeem ad credits request.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsCreditRedeemRequest" } } } }, "responses": { "200": { "description": "Successfully redeemed ad credits.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsCreditRedeemResponse" } } } }, "400": { "description": "Error thrown when unable to redeem offer code.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ValidationError": { "value": { "code": 15, "message": "Unable to redeem offer code. Try again later." } } } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ad_accounts/{ad_account_id}/ads/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,\nthe response will include the requested metric information (e.g. SPEND_IN_DOLLAR) for the requested target type\n(e.g. \"age_bucket\") for applicable values (e.g. \"45-49\").

\n- The token's user_account must either be the Owner of the specified ad account, or have one\nof the necessary roles granted to them via\nBusiness Access: 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.", "operationId": "ad_targeting_analytics/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_ad_ids_required" }, { "$ref": "#/components/parameters/query_start_date" }, { "$ref": "#/components/parameters/query_end_date" }, { "$ref": "#/components/parameters/query_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" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "ads" ] } }, "/ad_accounts/{ad_account_id}/ads/{ad_id}": { "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.", "operationId": "ads/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_ad_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "ads" ] } }, "/ad_accounts/{ad_account_id}/analytics": { "get": { "summary": "Get ad account analytics", "description": "Get analytics for 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: 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.", "operationId": "ad_account/analytics", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$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" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdAccountAnalyticsResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account analytics parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] } }, "/ad_accounts/{ad_account_id}/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\nad account's engaged audience on Pinterest, the ad account's total audience on Pinterest and Pinterest's\ntotal audience.

\nLearn more about Audience Insights.", "operationId": "audience_insights/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_audience_insight_type" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceInsightsResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "audience_insights" ] } }, "/ad_accounts/{ad_account_id}/audiences": { "get": { "summary": "List audiences", "description": "Get list of audiences for the ad account.", "operationId": "audiences/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "description": "The order in which to sort the items returned: “ASCENDING” or “DESCENDING” by ID.\nFor received audiences, it is sorted by sharing event time.\nNote that higher-value IDs are associated with more-recently added items.", "in": "query", "name": "order", "required": false, "schema": { "type": "string", "example": "ASCENDING", "enum": [ "ASCENDING", "DESCENDING" ] } }, { "$ref": "#/components/parameters/query_page_size" }, { "description": "This feature is currently in beta and not available to all apps.\nFilter audiences by ownership type.", "in": "query", "name": "ownership_type", "required": false, "example": "OWNED", "schema": { "type": "string", "default": "OWNED", "enum": [ "OWNED", "RECEIVED" ] } } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Audience" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid ad account audience parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account audience parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "audiences" ] }, "post": { "description": "Create an audience you can use in targeting for specific ad groups. Targeting combines customer information with\nthe ways users interact with Pinterest to help you reach specific groups of users; you can include or exclude\nspecific audience_ids when you create an ad group.

\nFor more, see Audience targeting.", "operationId": "audiences/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceCreateRequest" } } }, "description": "List of ads to create, size limit [1, 30]", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Create audience", "tags": [ "audiences" ] } }, "/ad_accounts/{ad_account_id}/audiences/custom": { "post": { "summary": "Create custom audience", "description": "Create a custom audience and find the audiences you want your ads to reach.", "operationId": "audiences/create_custom", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "description": "Custom audience to create.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceCreateCustomRequest" } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "audiences" ] } }, "/ad_accounts/{ad_account_id}/audiences/{audience_id}": { "get": { "summary": "Get audience", "description": "Get a specific audience given the audience ID.", "operationId": "audiences/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_audience_id" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" } } } }, "404": { "description": "Audience not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "audiences" ] }, "patch": { "summary": "Update audience", "description": "Update (edit or remove) an existing targeting audience.", "operationId": "audiences/update", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_audience_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceUpdateRequest" } } }, "description": "The audience to be updated." }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Audience" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "audiences" ] } }, "/ad_accounts/{ad_account_id}/bid_floor": { "post": { "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

Microcurrency is used to track very small transactions, based on the currency set in the advertiser’s profile.

\n

A microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser’s profile.

\n

Equivalency equations, using dollars as an example currency:

\n\n

To convert between currency and microcurrency, using dollars as an example currency:

\n\nFor more on bid floors see Set your bid.", "operationId": "ad_groups_bid_floor/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BidFloorRequest" } } }, "description": "Parameters to get bid_floor info", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BidFloor" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Get bid floors", "tags": [ "ad_groups" ] } }, "/ad_accounts/{ad_account_id}/billing_profiles": { "get": { "summary": "Get billing profiles", "description": "Get billing profiles in the advertiser account.\n\nThis endpoint might not be available to all apps. Learn more.", "operationId": "billing_profiles/get", "security": [ { "pinterest_oauth2": [ "ads:read", "billing:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "tags": [ "billing" ], "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "description": "Return active billing profiles, if false return all billing profiles.", "in": "query", "name": "is_active", "required": true, "schema": { "type": "boolean" } }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/BillingProfilesResponse" } } } } ] } } }, "description": "Success" }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ad_accounts/{ad_account_id}/bulk/download": { "post": { "summary": "Get advertiser entities in bulk", "description": "Create an asynchronous report that may include information on campaigns, ad groups, product groups, ads,\nand/or keywords; can filter by campaigns. Though the entities may be active, archived, or paused,\nonly active entities will return data.", "operationId": "bulk_download/create", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDownloadRequest" } } }, "description": "Parameters to get ad entities in bulk", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDownloadResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "bulk" ] } }, "/ad_accounts/{ad_account_id}/bulk/upsert": { "post": { "description": "Either create or update any combination of campaigns, ad groups, product groups, ads, or keywords.\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.", "operationId": "bulk_upsert/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpsertRequest" } } }, "description": "Parameters to get create/update ad entities in bulk", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpsertResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Create/update ad entities in bulk", "tags": [ "bulk" ] } }, "/ad_accounts/{ad_account_id}/bulk/{bulk_request_id}": { "get": { "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, or keywords).", "operationId": "bulk_request/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_bulk_request_id" }, { "$ref": "#/components/parameters/include_details" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpsertStatusResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Download advertiser entities in bulk", "tags": [ "bulk" ] } }, "/ad_accounts/{ad_account_id}/campaigns": { "get": { "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 roles granted to them via Business Access: Admin, Analyst, Campaign Manager.", "operationId": "campaigns/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_campaign_ids" }, { "$ref": "#/components/parameters/query_entity_statuses" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignResponse" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid ad account campaign parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account campaign parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "campaigns" ] }, "post": { "summary": "Create campaigns", "description": "Create multiple new campaigns. Every campaign has its own campaign_id and houses one or more ad groups, which contain one or more ads.\nFor more, see Set up your campaign.

\nNote:\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

Microcurrency is used to track very small transactions, based on the currency set in the advertiser’s profile.

\n

A microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser’s profile.

\n

Equivalency equations, using dollars as an example currency:

\n\n

To convert between currency and microcurrency, using dollars as an example currency:

\n", "tags": [ "campaigns" ], "operationId": "campaigns/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "description": "Array of campaigns.", "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 30, "minItems": 1, "items": { "$ref": "#/components/schemas/CampaignCreateRequest" } } } } }, "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignCreateResponse" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "summary": "Update campaigns", "description": "Update multiple ad campaigns based on campaign_ids.

\nNote:

\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

Microcurrency is used to track very small transactions, based on the currency set in the advertiser’s profile.

\n

A microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser’s profile.

\n

Equivalency equations, using dollars as an example currency:

\n\n

To convert between currency and microcurrency, using dollars as an example currency:

\n", "tags": [ "campaigns" ], "operationId": "campaigns/update", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "description": "Array of campaigns.", "required": true, "content": { "application/json": { "schema": { "type": "array", "maxItems": 30, "minItems": 1, "items": { "$ref": "#/components/schemas/CampaignUpdateRequest" } } } } }, "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignUpdateResponse" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ad_accounts/{ad_account_id}/campaigns/analytics": { "get": { "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: 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.", "operationId": "campaigns/analytics", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$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" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignsAnalyticsResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account campaign analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account campaign analytics parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "campaigns" ] } }, "/ad_accounts/{ad_account_id}/campaigns/targeting_analytics": { "get": { "summary": "Get targeting analytics for campaigns", "description": "Get targeting analytics for one or more campaigns.\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- The token's user_account must either be the Owner of the specified ad account, or have one\nof the necessary roles granted to them via\nBusiness Access: 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.", "operationId": "campaign_targeting_analytics/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_campaign_ids_required" }, { "$ref": "#/components/parameters/query_start_date" }, { "$ref": "#/components/parameters/query_end_date" }, { "$ref": "#/components/parameters/query_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" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsResponse" } } }, "description": "Success" }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "campaigns" ] } }, "/ad_accounts/{ad_account_id}/campaigns/{campaign_id}": { "get": { "summary": "Get campaign", "description": "Get a specific campaign given the campaign ID.", "operationId": "campaigns/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_campaign_id" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CampaignResponse" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "campaigns" ] } }, "/ad_accounts/{ad_account_id}/conversion_tags": { "get": { "summary": "Get conversion tags", "description": "List conversion tags associated with an ad account.", "operationId": "conversion_tags/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_filter_deleted" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionTagListResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "conversion_tags" ], "x-sandbox": "disabled" }, "post": { "x-sandbox": "disabled", "summary": "Create conversion tag", "description": "Create a conversion tag, also known as Pinterest tag, with the option to enable enhanced match.

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

\nFor more information, see:

\nSet up the Pinterest tag

\nPinterest Tag

\nEnhanced match", "operationId": "conversion_tags/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionTagCreate" } } }, "description": "Conversion Tag to create", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionTagResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "conversion_tags" ] } }, "/ad_accounts/{ad_account_id}/conversion_tags/ocpm_eligible": { "get": { "summary": "Get Ocpm eligible conversion tags", "description": "Get Ocpm eligible conversion tag events for an ad account.", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "operationId": "ocpm_eligible_conversion_tags/get", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "x-sandbox": "disabled", "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionTagsOcpmEligibleResponse" } } } }, "default": { "description": "Unexpected errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "conversion_tags" ] } }, "/ad_accounts/{ad_account_id}/conversion_tags/page_visit": { "get": { "summary": "Get page visit conversion tags", "description": "Get all page visit conversion tag events for an ad account.", "operationId": "page_visit_conversion_tags/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ConversionEventResponse" } } } } ] } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "conversion_tags" ] } }, "/ad_accounts/{ad_account_id}/conversion_tags/{conversion_tag_id}": { "get": { "x-sandbox": "disabled", "summary": "Get conversion tag", "description": "Get information about an existing conversion tag.", "operationId": "conversion_tags/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_conversion_tag_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionTagResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "conversion_tags" ] } }, "/ad_accounts/{ad_account_id}/customer_lists": { "post": { "description": "

Create a customer list from your records(hashed or plain-text email addresses, or hashed MAIDs or IDFAs).

\n

A customer list is one of the four types of Pinterest audiences: for more information, see Audience targeting\nor the Audiences section of the ads management guide.

\n

Please review our requirements for what type of information is allowed when uploading a customer list.

\n

When you create a customer list, the system scans the list for existing Pinterest accounts;\nthe list must include at least 100 Pinterest accounts. Your original list will be deleted when the matching process\nis complete. The filtered list – containing only the Pinterest accounts that were included in your starting\nlist – is what will be used to create the audience.

\n

Note that once you have created your customer list, you must convert it into an audience (of the “CUSTOMER_LIST” type)\nusing the create audience endpoint before it can be used.

", "operationId": "customer_lists/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListRequest" } } }, "description": "Parameters to get Customer lists info", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Create customer lists", "tags": [ "customer_lists" ] }, "get": { "description": "

Get a set of customer lists including id and name based on the filters provided.

\n

(Customer lists are a type of audience.) For more information, see\nAudience targeting\n or the Audiences\nsection of the ads management guide.

", "operationId": "customer_lists/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerList" } } } } ] } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Get customer lists", "tags": [ "customer_lists" ] } }, "/ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}": { "get": { "summary": "Get customer list", "description": "Gets a specific customer list given the customer list ID.", "operationId": "customer_lists/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_customer_list_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" } } }, "description": "Success" }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "customer_lists" ] }, "patch": { "description": "

Append or remove records to/from an existing customer list. (A customer list is one of the four types of Pinterest audiences.)

\n

When you add records to an existing customer list, the system scans the additions for existing Pinterest\naccounts; those are the records that will be added to your “CUSTOMER_LIST” audience. Your original list of records\nto add will be deleted when the matching process is complete.

\n

For more information, see Audience targeting\nor the Audiences\nsection of the ads management guide.

", "operationId": "customer_lists/update", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_customer_list_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Update customer list", "tags": [ "customer_lists" ] } }, "/ad_accounts/{ad_account_id}/events": { "post": { "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 for more details.\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: 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.)", "operationId": "events/create", "tags": [ "conversion_events" ], "security": [ { "pinterest_oauth2": [ "ads:write" ] }, { "conversion_token": [] } ], "x-ratelimit-category": "ads_conversions", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "name": "test", "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.", "in": "query", "required": false, "schema": { "type": "boolean" } } ], "requestBody": { "description": "Conversion events.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionEvents" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConversionApiResponse" } } }, "description": "Success" }, "400": { "description": "The request was invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 4196, "message": "The request was invalid." } } } }, "401": { "description": "Not authorized to send conversion events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 2, "message": "Authentication failed." } } } } } }, "403": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailedError" } } }, "description": "Not all events were successfully processed." }, "429": { "description": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits within a short time window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 8, "message": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits within a short time window." } } } }, "503": { "description": "The endpoint has been ramped down and is currently not accepting any traffic.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 4197, "message": "The endpoint has been ramped down and is currently not accepting any traffic." } } } }, "default": { "description": "Unexpected errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ad_accounts/{ad_account_id}/insights/audiences": { "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.", "operationId": "audience_insights_scope_and_type/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AudienceDefinitionResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "audience_insights" ] } }, "/ad_accounts/{ad_account_id}/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

For more information, see Keyword targeting.

\n

Notes:

For more information on match types, see match type enums.

\n

Returns:

", "operationId": "keywords/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_campaign_id" }, { "$ref": "#/components/parameters/query_ad_group_id" }, { "$ref": "#/components/parameters/query_match_types" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Keyword" } } } } ] } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "keywords" ] }, "post": { "summary": "Create keywords", "description": "

Create keywords for following entity types(advertiser, campaign, ad group or ad).

For more information, see Keyword targeting.

\n

Notes:

For more information on match types, see match type enums.

\n

Returns:

\n

Rate limit: WRITE.

", "operationId": "keywords/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordsRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordsResponse" } } }, "description": "Success" }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "keywords" ] }, "patch": { "summary": "Update keywords", "description": "

Update one or more keywords' bid and archived fields.

Archiving a keyword effectively deletes it - keywords no longer receive metrics and no longer visible within the parent entity's keywords list.

", "operationId": "keywords/update", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordUpdateBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordsResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "keywords" ] } }, "/ad_accounts/{ad_account_id}/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\"\nAPI endpoint).", "operationId": "country_keywords_metrics/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_country_code" }, { "$ref": "#/components/parameters/query_keywords" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordsMetricsArrayResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "keywords" ] } }, "/ad_accounts/{ad_account_id}/lead_forms": { "get": { "summary": "Get lead forms", "description": "Gets all Lead Forms associated with an ad account ID.\nRetrieving an advertiser's list of lead forms will only contain results if you're a part of the Lead ads beta. If you're interested in joining the beta, please reach out to your Pinterest account manager.", "operationId": "lead_forms/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/LeadFormResponse" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid ad account lead forms parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account lead forms parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "lead_forms" ] } }, "/ad_accounts/{ad_account_id}/lead_forms/{lead_form_id}": { "get": { "summary": "Get lead form by id", "description": "Gets a lead form given it's ID. It must also be associated with the provided ad account ID.\nRetrieving an advertiser's lead form will only contain results if you're a part of the Lead ads beta. If you're interested in joining the beta, please reach out to your Pinterest account manager.", "operationId": "lead_form/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_lead_form_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadFormResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account lead forms parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 1, "message": "Invalid ad account lead forms parameters." } } } }, "404": { "description": "The lead form ID for the given ad account ID does not exist.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 4842, "message": "Lead form is not found." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "lead_forms" ] } }, "/ad_accounts/{ad_account_id}/lead_forms/{lead_form_id}/test": { "post": { "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.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.", "operationId": "lead_form_test/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_lead_form_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadFormTestRequest" } } }, "description": "Subscription to create.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadFormTestResponse" } } }, "description": "Success" }, "400": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 1, "message": "Invalid parameters." } } } }, "404": { "description": "Lead not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 4842, "message": "Lead not found." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "lead_forms" ] } }, "/ad_accounts/{ad_account_id}/leads/subscriptions": { "post": { "summary": "Create lead ads subscription", "description": "Create a lead ads webhook subscription.\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\nThis endpoint is currently in beta and not available to all apps. Learn more.", "tags": [ "lead_ads" ], "operationId": "ad_accounts_subscriptions/post", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdAccountCreateSubscriptionRequest" } } }, "description": "Subscription to create.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdAccountCreateSubscriptionResponse" } } }, "description": "Success" }, "400": { "description": "Invalid input parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 1, "message": "Advertiser ID must be numeric." } } } }, "403": { "description": "Can't access this subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NotIntegrationOwner": { "value": { "code": 4182, "message": "Can't access this subscription." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "summary": "Get lead ads subscriptions", "description": "Get the advertiser's list of lead ads subscriptions.\n- Only requests for the OWNER or ADMIN of the ad_account will be allowed.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.", "operationId": "ad_accounts_subscriptions/get_list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdAccountGetSubscriptionResponse" } } } } ] } } }, "description": "Success" }, "403": { "description": "Can't access this subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NotIntegrationOwner": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "lead_ads" ] } }, "/ad_accounts/{ad_account_id}/leads/subscriptions/{subscription_id}": { "get": { "summary": "Get lead ads subscription", "description": "Get a specific lead ads subscription record.\n- Only requests for the OWNER or ADMIN of the ad_account will be allowed.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.", "operationId": "ad_accounts_subscriptions/get_by_id", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_subscription_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdAccountGetSubscriptionResponse" } } }, "description": "Success" }, "400": { "description": "Invalid input parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 1, "message": "Advertiser ID must be numeric." } } } }, "403": { "description": "Can't access this subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NotIntegrationOwner": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "404": { "description": "Subscription not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CommerceIntegrationNotFound": { "value": { "code": 4517, "message": "Subscription for given ids not found." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "lead_ads" ] }, "delete": { "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.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.", "operationId": "ad_accounts_subscriptions/del_by_id", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_subscription_id" } ], "responses": { "204": { "description": "Subscription deleted successfully" }, "400": { "description": "Invalid input parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 1, "message": "Advertiser ID must be numeric." } } } }, "403": { "description": "You are not authorized to delete this subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NotIntegrationOwner": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "404": { "description": "Subscription not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CommerceIntegrationNotFound": { "value": { "code": 4517, "message": "Subscription for given ids not found." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "lead_ads" ] } }, "/ad_accounts/{ad_account_id}/mmm_reports": { "get": { "summary": "Get advertiser Marketing Mix Modeling (MMM) report.", "description": "Get an mmm report for an ad account. This returns a URL to an mmm metrics report given a token returned from the\ncreate mmm report endpoint.", "operationId": "analytics/get_mmm_report", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_token_required" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetMMMReportResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account ads analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account ads analytics parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] }, "post": { "summary": "Create a request for a Marketing Mix Modeling (MMM) report", "description": "This creates an asynchronous mmm report based on the given request. It returns a token that you can use to download\nthe report when it is ready. NOTE: An additional limit of 5 queries per minute per advertiser applies to this endpoint while it's in beta release.", "operationId": "analytics/create_mmm_report", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMMMReportRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMMMReportResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account ads analytics mmm parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account ads analytics mmm parameters" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] } }, "/ad_accounts/{ad_account_id}/order_lines": { "get": { "summary": "Get order lines", "description": "List existing order lines associated with an ad account.", "operationId": "order_lines/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/OrderLine" } } } } ] } } }, "description": "Success" }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "order_lines" ] } }, "/ad_accounts/{ad_account_id}/order_lines/{order_line_id}": { "get": { "summary": "Get order line", "description": "Get a specific existing order line associated with an ad account.", "operationId": "order_lines/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_order_line_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderLine" } } }, "description": "Success" }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "order_lines" ] } }, "/ad_accounts/{ad_account_id}/product_group_promotions": { "post": { "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.')", "operationId": "product_group_promotions/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductGroupPromotionCreateRequest" } } }, "description": "List of Product Group Promotions to create, size limit [1, 30].", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductGroupPromotionResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Create product group promotions", "tags": [ "product_group_promotions" ] }, "patch": { "description": "Update multiple existing Product Group Promotions (by product_group_id)", "operationId": "product_group_promotions/update", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductGroupPromotionUpdateRequest" } } }, "description": "Parameters to update Product group promotions", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductGroupPromotionResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Update product group promotions", "tags": [ "product_group_promotions" ] }, "get": { "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\nNote: 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.", "operationId": "product_group_promotions/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_product_group_promotion_ids" }, { "$ref": "#/components/parameters/query_entity_statuses" }, { "$ref": "#/components/parameters/query_ad_group_id" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProductGroupPromotionResponseItem" } } } } ] } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Get product group promotions", "tags": [ "product_group_promotions" ] } }, "/ad_accounts/{ad_account_id}/product_group_promotions/{product_group_promotion_id}": { "get": { "description": "Get a product group promotion by id", "operationId": "product_group_promotions/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_product_group_promotion_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductGroupPromotionResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Get a product group promotion by id", "tags": [ "product_group_promotions" ] } }, "/ad_accounts/{ad_account_id}/product_groups/analytics": { "get": { "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- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.\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.", "operationId": "product_groups/analytics", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$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" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductGroupAnalyticsResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account ads analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account ads analytics parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "product_group_promotions" ] } }, "/ad_accounts/{ad_account_id}/product_groups/catalogs": { "get": { "deprecated": true, "description": "This endpoint is completely deprecated. Please use List product groups from Catalogs API instead.", "operationId": "ad_accounts_catalogs_product_groups/list", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_feed_profile_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogProductGroup" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid ad account ads parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account ads parameters." } } } }, "401": { "description": "Access Denied. This can happen if account is not yet approved to operate as Merchant on Pinterest.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Merchant data not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "summary": "Get catalog product groups", "tags": [ "product_groups" ] } }, "/ad_accounts/{ad_account_id}/reports": { "get": { "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. 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: Admin, Analyst, Campaign Manager.", "operationId": "analytics/get_report", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_token_required" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsAnalyticsGetAsyncResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account ads analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account ads analytics parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] }, "post": { "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. 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: Admin, Analyst, Campaign Manager.\n- If granularity is not HOUR, the furthest back you can are allowed to pull data is 914 days before the current date in UTC time and the max time range supported is 186 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.\n- If level is PRODUCT_ITEM, the furthest back you can are allowed to pull data is 92 days before the current date in UTC time and the max time range supported is 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.", "operationId": "analytics/create_report", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsAnalyticsCreateAsyncRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsAnalyticsCreateAsyncResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account ads analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account ads analytics parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] } }, "/ad_accounts/{ad_account_id}/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 https://developers.pinterest.com/docs/dev-tools/sandbox/ for more information.", "operationId": "sandbox/delete", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "string", "example": "Delete Success" } } } }, "400": { "description": "Invalid ad account id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account id" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] } }, "/ad_accounts/{ad_account_id}/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 to them via Business Access: Admin, Finance, Campaign.", "operationId": "ssio_accounts/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSIOAccountResponse" } } }, "description": "Success" }, "400": { "description": "Invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid request parameter." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "billing" ] } }, "/ad_accounts/{ad_account_id}/ssio/insertion_orders": { "post": { "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 to them via Business Access: Admin, Finance, Campaign.", "operationId": "ssio_insertion_order/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSIOCreateInsertionOrderRequest" } } }, "description": "Order line to create.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSIOCreateInsertionOrderResponse" } } }, "description": "Success" }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid request." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "billing" ] }, "patch": { "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 to them via Business Access: Admin, Finance, Campaign.", "operationId": "ssio_insertion_order/edit", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSIOEditInsertionOrderRequest" } } }, "description": "Order line to create.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSIOEditInsertionOrderResponse" } } }, "description": "Success" }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid request." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "billing" ] } }, "/ad_accounts/{ad_account_id}/ssio/insertion_orders/status": { "get": { "summary": "Get insertion order status by ad account id.", "description": "Get insertion order status 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 to them via Business Access: Admin, Finance, Campaign.", "operationId": "ssio_insertion_orders_status/get_by_ad_account", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Insertion orders status by ad acount id", "items": { "$ref": "#/components/schemas/SSIOInsertionOrderStatus" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid request parameter." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "billing" ] } }, "/ad_accounts/{ad_account_id}/ssio/insertion_orders/{pin_order_id}/status": { "get": { "summary": "Get insertion order status by pin order id.", "description": "Get insertion order status for pin order id 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 to them via Business Access: Admin, Finance, Campaign.", "operationId": "ssio_insertion_orders_status/get_by_pin_order_id", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_pin_order_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SSIOInsertionOrderStatusResponse" } } }, "description": "Success" }, "400": { "description": "Invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid request parameter." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "billing" ] } }, "/ad_accounts/{ad_account_id}/ssio/order_lines": { "get": { "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 to them via Business Access: Admin, Finance, Campaign.", "operationId": "ssio_order_lines/get_by_ad_account", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_pin_order_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "SSIO order lines by ad acount id", "items": { "$ref": "#/components/schemas/SSIOOrderLine" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid request parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid request parameter." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "billing" ] } }, "/ad_accounts/{ad_account_id}/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- The token's user_account must either be the Owner of the specified ad account, or have one\nof the necessary roles granted to them via\nBusiness Access: 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.", "operationId": "ad_account_targeting_analytics/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_start_date" }, { "$ref": "#/components/parameters/query_end_date" }, { "$ref": "#/components/parameters/query_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" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsResponse" } } }, "description": "Success" }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] } }, "/ad_accounts/{ad_account_id}/templates": { "get": { "summary": "List templates", "description": "Gets all Templates associated with an ad account ID.", "operationId": "templates/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TemplateResponse" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid ad account template parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account template parameters" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] } }, "/ad_accounts/{ad_account_id}/templates/{template_id}/reports": { "post": { "summary": "Create async request for an analytics report using a template", "description": "This takes a template ID and an optional custom timeframe and constructs an asynchronous report based on the\ntemplate. It returns a token that you can use to download the report when it is ready.", "operationId": "analytics/create_template_report", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_template_id" }, { "$ref": "#/components/parameters/query_start_date_async" }, { "$ref": "#/components/parameters/query_end_date_async" }, { "$ref": "#/components/parameters/query_granularity_async" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsAnalyticsCreateAsyncResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account ads analytics template parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account analytics template parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] } }, "/ad_accounts/{ad_account_id}/terms_of_service": { "get": { "description": "Get the text of the terms of service and see whether the advertiser has accepted the terms of service.", "operationId": "terms_of_service/get", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_include_html" }, { "$ref": "#/components/parameters/query_tos_type" } ], "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsOfService" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Get terms of service", "tags": [ "terms_of_service" ] } }, "/boards": { "get": { "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.", "tags": [ "boards" ], "operationId": "boards/list", "security": [ { "pinterest_oauth2": [ "boards:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": "enabled", "x-codeSamples": [ { "lang": "cURL", "label": "curl", "source": "curl --location --request GET 'https://api.pinterest.com/v5/boards' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json'\n" }, { "lang": "cURL", "label": "curl (Sandbox)", "source": "curl --location --request GET 'https://api-sandbox.pinterest.com/v5/boards' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json'\n" } ], "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "name": "privacy", "description": "Privacy setting for a board.", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ALL", "PROTECTED", "PUBLIC", "SECRET", "PUBLIC_AND_SECRET" ] } } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Boards", "items": { "$ref": "#/components/schemas/Board" } } } } ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "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.", "tags": [ "boards" ], "operationId": "boards/create", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": "enabled", "x-codeSamples": [ { "lang": "python", "label": "Python SDK", "source": "# Follow this link for initial setup: https://github.com/pinterest/pinterest-python-sdk#getting-started\n\nfrom pinterest.organic.boards import Board\n\nboard_create=Board.create(\n name=\"Summer Recipes\",\n description=\"My favorite summer recipes\",\n privacy=\"PUBLIC\"\n)\nprint(\"Board Id: %s, Board name:%s\"%(board_create.id, board_create.name))\n" }, { "lang": "cURL", "label": "curl", "source": "curl --location --request POST 'https://api.pinterest.com/v5/boards' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"name\": \"Summer Recipes\",\n \"description\": \"My favorite summer recipes\",\n \"privacy\": \"PUBLIC\"\n}'\n" }, { "lang": "cURL", "label": "curl (Sandbox)", "source": "curl --location --request POST 'https://api-sandbox.pinterest.com/v5/boards' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"name\": \"Summer Recipes\",\n \"description\": \"My favorite summer recipes\",\n \"privacy\": \"PUBLIC\"\n}'\n" } ], "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "description": "Create a board using a single board json object.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Board" } } } }, "responses": { "201": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Board" } } } }, "400": { "description": "The board name is invalid or duplicated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "The board name is invalid or duplicated." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{board_id}": { "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.", "tags": [ "boards" ], "operationId": "boards/get", "security": [ { "pinterest_oauth2": [ "boards:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": "enabled", "x-codeSamples": [ { "lang": "python", "label": "Python SDK", "source": "# Follow this link for initial setup: https://github.com/pinterest/pinterest-python-sdk#getting-started\n\nfrom pinterest.organic.boards import Board\n# Board information can be fetched from profile page or from create/list board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\nBOARD_ID=\"\"\n\nboard_get = Board(board_id=BOARD_ID)\nprint(\"Board Id: %s, Board name:%s\"%(board_get.id, board_get.name))\n" }, { "lang": "cURL", "label": "curl", "source": "# Board information can be fetched from profile page or from create/list board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\n\ncurl --location --request GET 'https://api.pinterest.com/v5/boards/' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json'\n" }, { "lang": "cURL", "label": "curl (Sandbox)", "source": "# Board information can be fetched from profile page or from create/ist board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\n\ncurl --location --request GET 'https://api-sandbox.pinterest.com/v5/boards/' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json'\n" } ], "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Board" } } } }, "404": { "description": "Board not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Board not found." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "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.", "tags": [ "boards" ], "operationId": "boards/update", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": "enabled", "x-codeSamples": [ { "lang": "python", "label": "Python SDK", "source": "# Follow this link for initial setup: https://github.com/pinterest/pinterest-python-sdk#getting-started\n\nfrom pinterest.organic.boards import Board\n# Board information can be fetched from profile page or from create/list board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\nBOARD_ID=\"\"\nNEW_DESCRIPTION=\"Updated summer recipes!\"\nNEW_PRIVACY=\"SECRET\"\n\nboard_update = Board(board_id=BOARD_ID)\nboard_update.update_fields(\n description=NEW_DESCRIPTION,\n privacy=NEW_PRIVACY\n)\nprint(\"Board Id: %s, Board description:%s, Board privacy:%s\" %(board_update.id, board_update.description, board_update.privacy))\n" }, { "lang": "cURL", "label": "curl", "source": "# Board information can be fetched from profile page or from create/list board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\n\ncurl --location --request PATCH 'https://api.pinterest.com/v5/boards/' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"name\": \"New Summer Recipes\",\n \"description\": \"Updated summer recipes!\",\n \"privacy\": \"SECRET\"\n}'\n" }, { "lang": "cURL", "label": "curl (Sandbox)", "source": "# Board information can be fetched from profile page or from create/list board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\n\ncurl --location --request PATCH 'https://api-sandbox.pinterest.com/v5/boards/' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"name\": \"New Summer Recipes\",\n \"description\": \"Updated summer recipes!\",\n \"privacy\": \"SECRET\"\n}'\n" } ], "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "description": "Update a board.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoardUpdate" } } } }, "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Board" } } } }, "400": { "description": "Invalid board parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid board parameters." } } } }, "403": { "description": "Not authorized to update the board.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to update the board." } } } }, "429": { "description": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits or if multiple write operations are applied to\nan object within a short time window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 8, "message": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits or if multiple write operations are applied to\nan object within a short time window." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "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.", "tags": [ "boards" ], "operationId": "boards/delete", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": "enabled", "x-codeSamples": [ { "lang": "python", "label": "Python SDK", "source": "# Follow this link for initial setup: https://github.com/pinterest/pinterest-python-sdk#getting-started\n\nfrom pinterest.organic.boards import Board\n# Board information can be fetched from profile page or from create/list board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\nBOARD_ID=\"\"\n\nboard_delete=Board.delete(board_id=BOARD_ID)\nprint(\"Board was deleted? %s\" % (board_delete))\n" }, { "lang": "cURL", "label": "curl", "source": "# Board information can be fetched from profile page or create/from list board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\n\ncurl --request DELETE 'https://api.pinterest.com/v5/boards/' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json' \\\n" }, { "lang": "cURL", "label": "curl (Sandbox)", "source": "# Board information can be fetched from profile page or from create/list board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\n\ncurl --request DELETE 'https://api-sandbox.pinterest.com/v5/boards/' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json' \\\n" } ], "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "204": { "description": "Board deleted successfully" }, "403": { "description": "Not authorized to delete the board.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to delete the board." } } } }, "404": { "description": "Board not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Board not found." } } } }, "409": { "description": "Could not get exclusive access to delete the board.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 409, "message": "Could not get exclusive access to delete the board." } } } }, "429": { "description": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits or if multiple write operations are applied to\nan object within a short time window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 8, "message": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits or if multiple write operations are applied to\nan object within a short time window." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{board_id}/pins": { "get": { "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.", "tags": [ "boards" ], "operationId": "boards/list_pins", "security": [ { "pinterest_oauth2": [ "boards:read", "pins:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_creative_types" }, { "$ref": "#/components/parameters/query_ad_account_id" }, { "$ref": "#/components/parameters/query_pin_metrics" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Pins", "items": { "$ref": "#/components/schemas/Pin" } } } } ] } } } }, "404": { "description": "Board not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Board not found." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{board_id}/sections": { "get": { "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.", "tags": [ "boards" ], "operationId": "board_sections/list", "security": [ { "pinterest_oauth2": [ "boards:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/query_ad_account_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Board sections", "items": { "$ref": "#/components/schemas/BoardSection" } } } } ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "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.", "tags": [ "boards" ], "operationId": "board_sections/create", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "description": "Create a board section.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoardSection" } } } }, "responses": { "201": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoardSection" } } } }, "400": { "description": "Invalid board section parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid board section parameters." } } } }, "403": { "description": "Not authorized to create board sections.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to create board sections." } } } }, "409": { "description": "Could not get exclusive access to the board to create a new section.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 409, "message": "Could not get exclusive access to the board to create a new section." } } } }, "500": { "description": "Could not create a new board section.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 500, "message": "Could not create a new board section." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{board_id}/sections/{section_id}": { "patch": { "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.", "tags": [ "boards" ], "operationId": "board_sections/update", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/path_board_section_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "description": "Update a board section.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoardSection" } } } }, "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BoardSection" } } } }, "400": { "description": "Invalid board section parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid board section parameters." } } } }, "403": { "description": "Not authorized to update board section.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to update board section." } } } }, "409": { "description": "Board section conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 409, "message": "Board section conflict." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "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.", "tags": [ "boards" ], "operationId": "board_sections/delete", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/path_board_section_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "204": { "description": "Board section deleted successfully" }, "403": { "description": "Not authorized to delete board section.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to delete board section." } } } }, "404": { "description": "Board section not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Board section not found." } } } }, "409": { "description": "Board section conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 409, "message": "Board section conflict." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/boards/{board_id}/sections/{section_id}/pins": { "get": { "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.", "tags": [ "boards" ], "operationId": "board_sections/list_pins", "security": [ { "pinterest_oauth2": [ "boards:read", "pins:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/path_board_section_id" }, { "$ref": "#/components/parameters/query_ad_account_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Pins", "items": { "$ref": "#/components/schemas/Pin" } } } } ] } } } }, "403": { "description": "Not authorized to access Pins on board section.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access Pins on board section." } } } }, "404": { "description": "Board or section not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Board or section not found." } } } }, "409": { "description": "Board section conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 409, "message": "Board section conflict." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/catalogs": { "get": { "x-ratelimit-category": "catalogs_read", "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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more", "operationId": "catalogs/list", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Catalog" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "Parameter 'page_size' was not numeric (was 3e)\"" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/feeds": { "get": { "x-ratelimit-category": "catalogs_read", "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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nFor Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.", "operationId": "feeds/list", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_catalogs_catalog_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogsFeed" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "Parameter 'page_size' was not numeric (was 3e)\"" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] }, "post": { "x-ratelimit-category": "catalogs_write", "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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nFor Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.", "operationId": "feeds/create", "security": [ { "pinterest_oauth2": [ "catalogs:read", "catalogs:write" ] } ], "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "description": "Request object used to created a feed.", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CatalogsVerticalFeedsCreateRequest" }, { "$ref": "#/components/schemas/CatalogsFeedsCreateRequest" } ] } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsFeed" } } }, "description": "Success" }, "400": { "description": "Invalid feed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "Invalid request: ..." } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "403": { "description": "Business account required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "BusinessAccountRequired": { "value": { "code": 654, "message": "You must have a business account to operate as merchant." } }, "MerchantDisapproved": { "value": { "code": 2625, "message": "Sorry, you cannot perform this action. Account is disapproved." } } } } } }, "409": { "description": "User website required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UserWebsiteRequired": { "value": { "code": 4168, "message": "User does not have a website." } }, "UserWebsiteNotVerified": { "value": { "code": 4169, "message": "User does not have a verified website." } } } } } }, "422": { "description": "Unique feed name is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "FeedDuplicatedName": { "value": { "code": 4170, "message": "The feed name already exists." } } } } } }, "501": { "description": "Not implemented (absent \"default_country\" or \"default_locale\").", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NotImplemented": { "value": { "code": 4181, "message": "Not implemented at the moment. Please, see documentation" } } } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/feeds/{feed_id}": { "get": { "x-ratelimit-category": "catalogs_read", "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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nFor Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.", "operationId": "feeds/get", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_catalogs_feed_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsFeed" } } }, "description": "Success" }, "400": { "description": "Invalid feed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "'feed_id' value '1511851494501_' must match the pattern: ^\\d+$\"}" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "404": { "description": "Data feed not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "FeedNotFound": { "value": { "code": 4161, "message": "Sorry! We could not find your catalogs feed." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] }, "patch": { "x-ratelimit-category": "catalogs_write", "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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nFor Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.", "operationId": "feeds/update", "security": [ { "pinterest_oauth2": [ "catalogs:read", "catalogs:write" ] } ], "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_catalogs_feed_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "description": "Request object used to update a feed.", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CatalogsVerticalFeedsUpdateRequest" }, { "$ref": "#/components/schemas/CatalogsFeedsUpdateRequest" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsFeed" } } }, "description": "Success" }, "400": { "description": "Invalid feed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "Invalid request: ..." } } } } } }, "403": { "description": "Forbidden. Account not approved for feed mutations yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MerchantDisapproved": { "value": { "code": 2625, "message": "Sorry, you cannot perform this action. Account is disapproved." } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "Sorry, you cannot perform this action. Account is under review." } } } } } }, "404": { "description": "Data feed not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "FeedNotFound": { "value": { "code": 4161, "message": "Sorry! We could not find your catalogs feed." } } } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] }, "delete": { "x-ratelimit-category": "catalogs_write", "summary": "Delete feed", "description": "Delete a feed 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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nFor Retail partners, refer to Before you get started with Catalogs. For Hotel parterns, refer to Pinterest API for shopping.", "operationId": "feeds/delete", "security": [ { "pinterest_oauth2": [ "catalogs:read", "catalogs:write" ] } ], "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_catalogs_feed_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "204": { "description": "Feed deleted successfully." }, "400": { "description": "Invalid feed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "'feed_id' value '1511851494501_' must match the pattern: ^\\d+$\"}" } } } } } }, "403": { "description": "Forbidden. Account not approved for feed mutations yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MerchantDisapproved": { "value": { "code": 2625, "message": "Sorry, you cannot perform this action. Account is disapproved." } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "Sorry, you cannot perform this action. Account is under review." } } } } } }, "404": { "description": "Data feed not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "FeedNotFound": { "value": { "code": 4161, "message": "Sorry! We could not find your catalogs feed." } } } } } }, "409": { "description": "Conflict. Can't delete a feed with active promotions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "FeedHasActivePromotions": { "value": { "code": 4162, "message": "We can't disable a Product Group with active promotions." } } } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/feeds/{feed_id}/processing_results": { "get": { "x-ratelimit-category": "catalogs_read", "summary": "List processing results for a given feed", "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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more", "operationId": "feed_processing_results/list", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_catalogs_feed_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogsFeedProcessingResult" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "Parameter 'page_size' was not numeric (was 3e)\"" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "404": { "description": "Feed not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "FeedNotFound": { "value": { "code": 4161, "message": "Sorry! We could not find your catalogs feed." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/processing_results/{processing_result_id}/item_issues": { "get": { "x-ratelimit-category": "catalogs_read", "summary": "List item issues for a given processing result", "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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more", "operationId": "items_issues/list", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$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" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogsItemValidationIssues" } } } } ] } } }, "description": "Success" }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "404": { "description": "Processing Result not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ProcessingResultFound": { "value": { "code": 4184, "message": "Sorry! We could not find your processing result." } } } } } }, "501": { "description": "Not implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NotImplemented": { "value": { "code": 4181, "message": "Not implemented at the moment. Please, see documentation." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/items": { "get": { "summary": "Get catalogs items", "description": "Get the items of the catalog owned by the \"operation user_account\". See detailed documentation here.\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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.", "operationId": "items/get", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-ratelimit-category": "catalogs_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" }, { "$ref": "#/components/parameters/query_catalogs_items_country" }, { "$ref": "#/components/parameters/query_catalogs_items_language" }, { "$ref": "#/components/parameters/query_catalogs_items" }, { "$ref": "#/components/parameters/query_catalogs_items_filters" } ], "responses": { "200": { "description": "Response containing the requested catalogs items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsItems" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "Parameter 'item_ids' is required." } } } } } }, "401": { "description": "Not authorized to access catalogs items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 2, "message": "Authentication failed." } } } } } }, "403": { "description": "Not authorized to access catalogs items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/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.\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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.", "operationId": "items_batch/post", "x-ratelimit-category": "catalogs_write", "x-sandbox": "enabled", "security": [ { "pinterest_oauth2": [ "catalogs:read", "catalogs:write" ] } ], "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "description": "Request object used to create catalogs items in a batch", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CatalogsVerticalBatchRequest" }, { "$ref": "#/components/schemas/CatalogsItemsBatchRequest" } ] } } } }, "responses": { "200": { "description": "Response containing the requested catalogs items batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsItemsBatch" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "Invalid request: {'country': 'US', 'language': 'EN', 'operation': 'CREATE', 'items': [{'item_id': 'RAY_01_', 'attributes': {'image_link': 'https://www.example.com/', 'title': 'My Product'}}]} ('https://www.example.com/' is not of type array)" } } } } } }, "401": { "description": "Not authenticated to post catalogs items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthenticatedAccess": { "value": { "code": 2, "message": "Authentication failed." } } } } } }, "403": { "description": "Not authorized to post catalogs items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/items/batch/{batch_id}": { "get": { "summary": "Get catalogs item batch status", "description": "Get a single catalogs items batch owned by the \"operating user_account\". See detailed documentation here.\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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.", "operationId": "items_batch/get", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-ratelimit-category": "catalogs_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_catalogs_items_batch_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "description": "Response containing the requested catalogs items batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsItemsBatch" } } } }, "401": { "description": "Not authenticated to access catalogs items batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthenticatedAccess": { "value": { "code": 2, "message": "Authentication failed." } } } } } }, "403": { "description": "Not authorized to access catalogs items batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Catalogs items batch not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CannotFindBatch": { "value": { "code": 4331, "message": "Sorry! We could not find your batch ID." } } } } } }, "405": { "description": "Method Not Allowed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MethodNotAllowed": { "value": { "status": "failure", "code": 5, "data": "405 Method Not Allowed: The method is not allowed for the requested URL.", "message": "Method not allowed", "endpoint_name": null } } } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/product_groups": { "get": { "x-ratelimit-category": "catalogs_read", "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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more", "operationId": "catalogs_product_groups/list", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_catalogs_feed_id" }, { "$ref": "#/components/parameters/query_catalogs_catalog_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "anyOf": [ { "$ref": "#/components/schemas/CatalogsProductGroup" }, { "$ref": "#/components/schemas/CatalogsVerticalProductGroup" } ] } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid feed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "'feed_id' value '1511851494501_' must match the pattern: ^\\d+$\"}" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "403": { "description": "Forbidden. Account not approved for catalog product group mutations yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MerchantDisapproved": { "value": { "code": 2625, "message": "Sorry, you cannot perform this action. Account is disapproved." } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "Sorry, you cannot perform this action. Account is under review." } } } } } }, "404": { "description": "Data feed not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "FeedNotFound": { "value": { "code": 4161, "message": "Sorry! We could not find your catalogs feed." } } } } } }, "409": { "description": "Conflict. Can't create this catalogs product group with this value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsMerchantNotCreated": { "value": { "code": 4182, "message": "Can't access this feature without an existing catalog." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] }, "post": { "x-ratelimit-category": "catalogs_write", "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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more", "operationId": "catalogs_product_groups/create", "security": [ { "pinterest_oauth2": [ "catalogs:write" ] } ], "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "description": "Request object used to created a catalogs product group.", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CatalogsProductGroupCreateRequest" }, { "$ref": "#/components/schemas/CatalogsVerticalProductGroupCreateRequest" } ] }, "examples": { "RetailFewFiltersUsingAllOf": { "summary": "A simple retail example that applies \"all of the following filters\".", "description": "The use of \"all_of\" creates a Product Group where all of the individual filters\nmust be satisfied by a product to be included in the Product Group.\n", "value": { "name": "Few Filters using \"all_of\"", "feed_id": "2680059592705", "featured": false, "filters": { "all_of": [ { "MIN_PRICE": { "values": 999.99, "inclusion": true } }, { "CURRENCY": { "values": "USD" } }, { "CUSTOM_LABEL_0": { "values": [ "Luxury Items" ] } } ] } } }, "RetailManyFiltersUsingAnyOf": { "summary": "A more complete retail example that applies \"any of the following filters\".", "description": "The use of \"any_of\" creates a Product Group where any of the individual filters\ncan add products to the Product Group independently.\n", "value": { "name": "Many Filters using \"any_of\"", "featured": false, "feed_id": "2680059592705", "filters": { "all_of": [ { "MIN_PRICE": { "values": 111.55, "inclusion": false, "negated": false } }, { "CURRENCY": { "values": "USD", "negated": false } }, { "AVAILABILITY": { "values": [ "IN_STOCK", "OUT_OF_STOCK", "PREORDER" ], "negated": false } }, { "BRAND": { "values": [ "avanti", "beautyrest" ], "negated": true } }, { "GOOGLE_PRODUCT_CATEGORY_0": { "values": [ [ "furniture", "tables", "accent tables", "end tables" ], [ "furniture", "chairs", "slipper chairs" ], [ "home & garden" ] ], "negated": false } }, { "CONDITION": { "values": [ "NEW", "REFURBISHED", "USED" ], "negated": false } }, { "CUSTOM_LABEL_0": { "values": [ "004 - home furn leisure" ], "negated": false } }, { "CUSTOM_LABEL_1": { "values": [ "clearance", "original price" ], "negated": false } }, { "CUSTOM_LABEL_2": { "values": [ "789 - table linens", "794 - living room accents" ], "negated": false } }, { "GENDER": { "values": [ "FEMALE", "MALE", "UNISEX" ], "negated": false } }, { "ITEM_ID": { "values": [ "does not exists", "this one neither", "nope" ], "negated": true } }, { "ITEM_GROUP_ID": { "values": [ "nonexistant group", "another one", "last one" ], "negated": true } }, { "PRODUCT_TYPE_0": { "values": [ [ "accent chairs", "club chairs" ], [ "accent chairs", "slipper chairs" ], [ "accent tables", "end tables" ], [ "air mattresses", "air mattresses" ], [ "table linens" ] ], "negated": false } } ] } } }, "HotelFewFiltersUsingAllOf": { "summary": "A simple hotel example that applies \"all of the following filters\".", "description": "The use of \"all_of\" creates a Product Group where all of the individual filters\nmust be satisfied by a hotel to be included in the Product Group.\n", "value": { "catalog_type": "HOTEL", "name": "Few Filters using \"all_of\"", "catalog_id": "4866935934774", "filters": { "all_of": [ { "HOTEL_ID": { "values": [ "hotel1", "hotel2" ] } }, { "CUSTOM_LABEL_1": { "values": [ "big_hotels" ], "negated": false } } ] } } } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CatalogsProductGroup" }, { "$ref": "#/components/schemas/CatalogsVerticalProductGroup" } ] } } }, "description": "Success" }, "400": { "description": "Invalid body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "'feed_id' value '1511851494501_' must match the pattern: ^\\d+$\"}" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "403": { "description": "Forbidden. Account not approved for catalog product group mutations yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MerchantDisapproved": { "value": { "code": 2625, "message": "Sorry, you cannot perform this action. Account is disapproved." } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "Sorry, you cannot perform this action. Account is under review." } } } } } }, "409": { "description": "Conflict. Can't create this catalogs product group with this value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsProductGroupFiltersAlreadyExist": { "value": { "code": 4178, "message": "A catalogs product group with these filters already exists for this feed." } }, "CatalogsProductGroupNameAlreadyExist": { "value": { "code": 4179, "message": "A catalogs product group with this name already exists for this feed." } }, "CatalogsMerchantNotCreated": { "value": { "code": 4182, "message": "Can't access this feature without an existing catalog." } }, "CatalogsProductGroupFiltersInvalid": { "value": { "code": 4183, "message": "Catalog product group filters failed validation, please ensure all filters are set correctly." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/product_groups/{product_group_id}": { "get": { "x-ratelimit-category": "catalogs_read", "summary": "Get product group", "description": "Get a singe 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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more", "operationId": "catalogs_product_groups/get", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_catalogs_product_group_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CatalogsProductGroup" }, { "$ref": "#/components/schemas/CatalogsVerticalProductGroup" } ] } } }, "description": "Success" }, "400": { "description": "Invalid catalogs product group id parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "'product_group_id' value '11851494501_' must match the pattern: ^\\d+$\"}" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "403": { "description": "Forbidden. Account not approved for catalog product group mutations yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MerchantDisapproved": { "value": { "code": 2625, "message": "Sorry, you cannot perform this action. Account is disapproved." } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "Sorry, you cannot perform this action. Account is under review." } } } } } }, "404": { "description": "Catalogs product group not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsProductGroupNotFound": { "value": { "code": 4180, "message": "Sorry! We could not find your catalogs product group." } } } } } }, "409": { "description": "Conflict. Can't get a catalogs product group without an existing catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsMerchantNotCreated": { "value": { "code": 4182, "message": "Can't acccess this feature without an existing catalog." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] }, "delete": { "x-ratelimit-category": "catalogs_write", "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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more", "operationId": "catalogs_product_groups/delete", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_catalogs_product_group_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "security": [ { "pinterest_oauth2": [ "catalogs:write" ] } ], "responses": { "204": { "description": "Catalogs Product Group deleted successfully." }, "400": { "description": "Invalid catalogs product group id parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "'product_group_id' value '11851494501_' must match the pattern: ^\\d+$\"}" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "403": { "description": "Forbidden. Account not approved for catalog product group mutations yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MerchantDisapproved": { "value": { "code": 2625, "message": "Sorry, you cannot perform this action. Account is disapproved." } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "Sorry, you cannot perform this action. Account is under review." } } } } } }, "404": { "description": "Catalogs product group not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsProductGroupNotFound": { "value": { "code": 4180, "message": "Sorry! We could not find your catalogs product group." } } } } } }, "409": { "description": "Conflict. Can't delete this catalogs product group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsProductGroupHasActivePromotions": { "value": { "code": 4176, "message": "We can't delete a Catalogs Product Group with active promotions." } }, "CannotAlterAutoGeneratedCatalogsProductGroup": { "value": { "code": 4177, "message": "You cannot alter an auto generated catalogs product group." } }, "CatalogsMerchantNotCreated": { "value": { "code": 4182, "message": "Can't access this feature without an existing catalog." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] }, "patch": { "x-ratelimit-category": "catalogs_write", "summary": "Update 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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more", "operationId": "catalogs_product_groups/update", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_catalogs_product_group_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "security": [ { "pinterest_oauth2": [ "catalogs:write" ] } ], "requestBody": { "description": "Request object used to Update a catalogs product group.", "required": true, "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CatalogsProductGroupUpdateRequest" }, { "$ref": "#/components/schemas/CatalogsVerticalProductGroupUpdateRequest" } ] } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/CatalogsProductGroup" }, { "$ref": "#/components/schemas/CatalogsVerticalProductGroup" } ] } } }, "description": "Success" }, "400": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "'product_group_id' value '11851494501_' must match the pattern: ^\\d+$\"}" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "403": { "description": "Forbidden. Account not approved for catalog product group mutations yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MerchantDisapproved": { "value": { "code": 2625, "message": "Sorry, you cannot perform this action. Account is disapproved." } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "Sorry, you cannot perform this action. Account is under review." } } } } } }, "404": { "description": "Catalogs product group not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsProductGroupNotFound": { "value": { "code": 4180, "message": "Sorry! We could not find your catalogs product group." } } } } } }, "409": { "description": "Conflict. Can't update this catalogs product group to this value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CannotAlterAutoGeneratedCatalogsProductGroup": { "value": { "code": 4177, "message": "You cannot alter an auto generated catalogs product group." } }, "CatalogsProductGroupFiltersAlreadyExist": { "value": { "code": 4178, "message": "A catalogs product group with these filters already exists for this feed." } }, "CatalogsProductGroupNameAlreadyExist": { "value": { "code": 4179, "message": "A catalogs product group with this name already exists for this feed." } }, "CatalogsMerchantNotCreated": { "value": { "code": 4182, "message": "Can't access this feature without an existing catalog." } }, "CatalogsProductGroupFiltersInvalid": { "value": { "code": 4183, "message": "Catalog product group filters failed validation, please ensure all filters are set correctly." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/product_groups/{product_group_id}/product_counts": { "get": { "x-ratelimit-category": "catalogs_read", "summary": "Get product counts for a Product Group", "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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more", "operationId": "catalogs_product_groups/product_counts_get", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_catalogs_product_group_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsProductGroupProductCounts" } } }, "description": "Success" }, "404": { "description": "Product Group Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsProductGroupNotFound": { "value": { "code": 4180, "message": "Sorry! We could not find your catalogs product group." } } } } } }, "409": { "description": "Can't access this feature without an existing catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsMerchantNotCreated": { "value": { "code": 4182, "message": "Can't access this feature without an existing catalog." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/product_groups/{product_group_id}/products": { "get": { "x-ratelimit-category": "catalogs_read", "summary": "List products for a 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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more", "operationId": "catalogs_product_group_pins/list", "security": [ { "pinterest_oauth2": [ "boards:read", "catalogs:read", "pins:read" ] } ], "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/path_catalogs_product_group_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Pins", "items": { "$ref": "#/components/schemas/CatalogsProduct" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "'product_group_id' value '11851494501_' must match the pattern: ^\\d+$\"}" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "404": { "description": "Catalogs product group not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsProductGroupNotFound": { "value": { "code": 4180, "message": "Sorry! We could not find your catalogs product group." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/products/get_by_product_group_filters": { "post": { "x-ratelimit-category": "catalogs_read", "summary": "List filtered products", "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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more", "operationId": "products_by_product_group_filter/list", "security": [ { "pinterest_oauth2": [ "boards:read", "catalogs:read", "pins:read" ] } ], "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "description": "Object holding a group of filters for a catalog product group", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsListProductsByFilterRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Pins", "items": { "$ref": "#/components/schemas/CatalogsProduct" } } } } ] } } }, "description": "Success" }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "409": { "description": "Conflict. Can't get products.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsMerchantNotCreated": { "value": { "code": 4182, "message": "Can't acccess this feature without an existing catalog." } }, "CatalogsProductGroupFiltersInvalid": { "value": { "code": 4183, "message": "Catalog product group filters failed validation, please ensure all filters are set correctly." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/integrations/commerce": { "post": { "summary": "Create commerce integration", "description": "Create commerce integration metadata to link an external business ID with a Pinterest merchant & ad account.\nNote: If you're interested in joining the beta, please reach out to your Pinterest account manager.", "operationId": "integrations_commerce/post", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationRequest" } } }, "description": "Parameters to get create/update the Integration Metadata" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationMetadata" } } }, "description": "Success" }, "404": { "description": "Integration not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IntegrationNotFound": { "value": { "code": 4180, "message": "Sorry! We could not find your integration." } } } } } }, "409": { "description": "Can't access this integration metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NotIntegrationOwner": { "value": { "code": 4182, "message": "Can't access this integration metadata." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "integrations" ] } }, "/integrations/commerce/{external_business_id}": { "get": { "summary": "Get commerce integration", "description": "Get commerce integration metadata associated with the given external business ID.\nNote: If you're interested in joining the beta, please reach out to your Pinterest account manager.", "operationId": "integrations_commerce/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_external_business_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationMetadata" } } }, "description": "Success" }, "404": { "description": "Integration not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IntegrationNotFound": { "value": { "code": 4180, "message": "Sorry! We could not find your integration." } } } } } }, "409": { "description": "Can't access this integration metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NotIntegrationOwner": { "value": { "code": 4182, "message": "Can't access this integration metadata." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "integrations" ] }, "patch": { "summary": "Update commerce integration", "description": "Update commerce integration metadata for the given external business ID.\nNote: If you're interested in joining the beta, please reach out to your Pinterest account manager.", "operationId": "integrations_commerce/patch", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_external_business_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationRequestPatch" } } }, "description": "Parameters to get create/update the Integration Metadata" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationMetadata" } } }, "description": "Success" }, "404": { "description": "Integration not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IntegrationNotFound": { "value": { "code": 4180, "message": "Sorry! We could not find your integration." } } } } } }, "409": { "description": "Can't access this integration metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NotIntegrationOwner": { "value": { "code": 4182, "message": "Can't access this integration metadata." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "integrations" ] }, "delete": { "summary": "Delete commerce integration", "description": "Delete commerce integration metadata for the given external business ID.\nNote: If you're interested in joining the beta, please reach out to your Pinterest account manager.", "operationId": "integrations_commerce/del", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_external_business_id" } ], "responses": { "204": { "description": "Commerce Integration deleted successfully" }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "integrations" ] } }, "/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.", "tags": [ "integrations" ], "operationId": "integrations_logs/post", "x-ratelimit-category": "ads_write", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-sandbox": "enabled", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationLogsRequest" } } }, "description": "Ingest log information from external integration application.", "required": true }, "responses": { "200": { "description": "Success.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationLogsSuccessResponse" } } } }, "400": { "description": "Bad request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DetailedError" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/integrations": { "get": { "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.", "operationId": "integrations/get_list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrationRecord" } } } } ] } } }, "description": "Success" }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "integrations" ] } }, "/integrations/{id}": { "get": { "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.", "operationId": "integrations/get_by_id", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "name": "id", "description": "Integration ID.", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IntegrationRecord" } } }, "description": "Success" }, "404": { "description": "Integration not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "IntegrationNotFound": { "value": { "code": 4517, "message": "Sorry! We could not find your integration." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "integrations" ] } }, "/media": { "get": { "summary": "List media uploads", "description": "List media uploads filtered by given parameters.\n\nLearn more about video Pin creation.", "tags": [ "media" ], "operationId": "media/list", "security": [ { "pinterest_oauth2": [ "pins:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Media", "items": { "$ref": "#/components/schemas/MediaUploadDetails" } } } } ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Register media upload", "description": "Register your intent to upload media\n\nThe response includes all of the information needed to upload the media\nto Pinterest.\n\nTo upload the media, make an HTTP POST request (using curl, for\nexample) to upload_url using the Content-Type header\nvalue. Send the media file's contents as the request's file\nparameter and also include all of the parameters from\nupload_parameters.\n\nLearn more about video Pin creation.", "tags": [ "media" ], "operationId": "media/create", "security": [ { "pinterest_oauth2": [ "pins:read", "pins:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": "enabled", "requestBody": { "description": "Create a media upload request", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUploadRequest" } } } }, "responses": { "201": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUpload" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/media/{media_id}": { "get": { "summary": "Get media upload details", "description": "Get details for a registered media upload, including its current status.\n\nLearn more about video Pin creation.", "tags": [ "media" ], "operationId": "media/get", "security": [ { "pinterest_oauth2": [ "pins:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_media_id" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MediaUploadDetails" } } } }, "404": { "description": "Media upload not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Media upload not found" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/oauth/token": { "post": { "summary": "Generate OAuth access token", "description": "Generate an OAuth access token by using an authorization code or a refresh token.\n\nIMPORTANT: You need to start the OAuth flow via www.pinterest.com/oauth before calling this endpoint (or have an existing refresh token).\n\nSee Authentication for more.\n\nParameter refresh_on and its corresponding response type everlasting_refresh are now available to all apps! Later this year, continuous refresh will become the default behavior (ie you will no longer need to send this parameter). Learn more.", "tags": [ "oauth" ], "operationId": "oauth/token", "security": [ { "basic": [] } ], "x-ratelimit-category": "org_read", "x-sandbox": "enabled", "requestBody": { "description": "Generate an OAuth access token.", "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "$ref": "#/components/schemas/OauthAccessTokenRequest" } } } }, "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OauthAccessTokenResponse" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pins": { "get": { "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.\nOptional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\".", "operationId": "pins/list", "security": [ { "pinterest_oauth2": [ "boards:read", "pins:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": "enabled", "x-codeSamples": [ { "lang": "cURL", "label": "curl", "source": "curl --location --request GET 'https://api.pinterest.com/v5/pins' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json'\n" }, { "lang": "cURL", "label": "curl (Sandbox)", "source": "curl --location --request GET 'https://api-sandbox.pinterest.com/v5/pins' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json'\n" } ], "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_pin_filter" }, { "$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_pin_metrics" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Pin" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid pin filter value", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid pin filter value" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "pins" ] }, "post": { "summary": "Create Pin", "description": "Create a Pin on a board or board section owned by the \"operation user_account\".\n\nNote: 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 instead. For more tips on creating fresh content for Pinterest, review our Content App Solutions Guide.\n\nLearn more about video Pin creation.", "tags": [ "pins" ], "operationId": "pins/create", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write", "pins:read", "pins:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": "enabled", "x-codeSamples": [ { "lang": "python", "label": "Python SDK", "source": "# Follow this link for initial setup: https://github.com/pinterest/pinterest-python-sdk#getting-started\n\nfrom pinterest.organic.pins import Pin\n# Board information can be fetched from profile page or from create/list board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\nBOARD_ID=\"\"\n\npin_create = Pin.create(\n board_id=BOARD_ID,\n title=\"My Pin\",\n description=\"Pin Description\",\n media_source={\n \"source_type\": \"image_url\",\n \"content_type\": \"image/jpeg\",\n \"data\": \"string\",\n 'url':'https://i.pinimg.com/564x/28/75/e9/2875e94f8055227e72d514b837adb271.jpg'\n }\n )\nprint(\"Pin Id: %s, Pin Title:%s\" %(pin_create.id, pin_create.title))\n" }, { "lang": "cURL", "label": "curl", "source": "# Board information can be fetched from profile page or from create/list board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\n\ncurl --location --request POST 'https://api.pinterest.com/v5/pins' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"title\": \"My Pin\",\n \"description\": \"Pin Description\",\n \"board_id\": \",\n \"media_source\": {\n \"source_type\": \"image_url\",\n \"url\": \"https://i.pinimg.com/564x/28/75/e9/2875e94f8055227e72d514b837adb271.jpg\"\n }\n }'\n" }, { "lang": "cURL", "label": "curl (Sandbox)", "source": "# Board information can be fetched from profile page or from create/list board method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/boards/list\n\ncurl --location --request POST 'https://api-sandbox.pinterest.com/v5/pins' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"title\": \"My Pin\",\n \"description\": \"Pin Description\",\n \"board_id\": \",\n \"media_source\": {\n \"source_type\": \"image_url\",\n \"url\": \"https://i.pinimg.com/564x/28/75/e9/2875e94f8055227e72d514b837adb271.jpg\"\n }\n }'\n" } ], "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "description": "Create a new Pin.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinCreate" } } } }, "responses": { "201": { "description": "Successful pin creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pin" } } } }, "400": { "description": "Invalid Pin parameters response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidPinUrl": { "value": { "code": 1, "message": "Whoops! It looks like you entered an invalid URL. Try creating a Pin again with a valid URL." } } } } } }, "403": { "description": "The Pin's image is too small, too large or is broken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PinImageTooSmall": { "value": { "code": 233, "message": "Your image is too small. Please choose a larger image and try again." } }, "PinImageBroken": { "value": { "code": 235, "message": "Sorry, this image is broken. Please pick a different image." } } } } } }, "404": { "description": "Board or section not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "BoardNotFound": { "value": { "code": 40, "message": "Board not found." } }, "BoardSectionNotFound": { "value": { "code": 2031, "message": "Sorry! We couldn't find this board section." } } } } } }, "429": { "description": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits or if multiple write operations are applied to\nan object within a short time window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 8, "message": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits or if multiple write operations are applied to\nan object within a short time window." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pins/{pin_id}": { "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\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account:\n\n- For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager.\n- For Pins on secret boards: Owner, Admin.", "tags": [ "pins" ], "operationId": "pins/get", "security": [ { "pinterest_oauth2": [ "boards:read", "pins:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": "enabled", "x-codeSamples": [ { "lang": "python", "label": "Python SDK", "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 list pin method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/pins/list\nPIN_ID=\"\"\n\npin_get = Pin(pin_id=PIN_ID)\nprint(\"Pin Id: %s, Pin Title:%s\" %(pin_get.id, pin_get.title))\n" }, { "lang": "cURL", "label": "curl", "source": "# Pin information can be fetched from profile page or from list pin method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/pins/list\n\ncurl --location --request GET 'https://api.pinterest.com/v5/pins/' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json'\n" }, { "lang": "cURL", "label": "curl (Sandbox)", "source": "# Pin information can be fetched from profile page or from list pin method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/pins/list\n\ncurl --location --request GET 'https://api-sandbox.pinterest.com/v5/pins/' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json'\n" } ], "parameters": [ { "$ref": "#/components/parameters/path_pin_id" }, { "$ref": "#/components/parameters/query_pin_metrics" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pin" } } } }, "403": { "description": "Not authorized to access board or Pin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 29, "message": "You are not permitted to access that resource." } } } }, "404": { "description": "Pin not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 50, "message": "Pin not found." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "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\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account:\n\n- For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager.\n- For Pins on secret boards: Owner, Admin.", "tags": [ "pins" ], "operationId": "pins/delete", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write", "pins:read", "pins:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": "enabled", "x-codeSamples": [ { "lang": "python", "label": "Python SDK", "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# https://developers.pinterest.com/docs/api/v5/#operation/pins/list\nPIN_ID=\"\"\n\npin_delete=Pin.delete(pin_id=PIN_ID)\n\nprint(\"Pin was deleted? %s\" % (pin_delete))\n" }, { "lang": "cURL", "label": "curl", "source": "# Pin information can be fetched from profile page or from create/list pin method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/pins/list\n\ncurl --request DELETE 'https://api.pinterest.com/v5/pins/' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json'\n" }, { "lang": "cURL", "label": "curl (Sandbox)", "source": "# Pin information can be fetched from profile page or from create/list pin method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/pins/list\n\ncurl --request DELETE 'https://api-sandbox.pinterest.com/v5/pins/' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json'\n" } ], "parameters": [ { "$ref": "#/components/parameters/path_pin_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "204": { "description": "Successfully deleted Pin" }, "403": { "description": "Not authorized to access board or Pin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access board or Pin." } } } }, "404": { "description": "Pin not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Pin not found." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account:\n\n- For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager.\n- For Pins on secret boards: Owner, Admin.\n\nThis endpoint is currently in beta and not available to all apps. Learn more.", "tags": [ "pins" ], "operationId": "pins/update", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write", "pins:read", "pins:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": "enabled", "x-codeSamples": [ { "lang": "cURL", "label": "curl", "source": "# Pin information can be fetched from profile page or from create/list pin method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/pins/list\n\ncurl --location --request PATCH 'https://api.pinterest.com/v5/pins/' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"title\": \"My updated Pin title\"\n}'\n" }, { "lang": "cURL", "label": "curl (Sandbox)", "source": "# Pin information can be fetched from profile page or from create/list pin method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/pins/list\n\ncurl --location --request GET 'https://api-sandbox.pinterest.com/v5/pins/' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"title\": \"My updated Pin title\"\n}'\n" } ], "parameters": [ { "$ref": "#/components/parameters/path_pin_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinUpdate" } } } }, "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pin" } } } }, "403": { "description": "Not authorized to update Pin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 29, "message": "Not authorized to update Pin." } } } }, "404": { "description": "Pin not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 50, "message": "Pin not found." } } } }, "429": { "description": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits or if multiple write operations are applied to\nan object within a short time window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 8, "message": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits or if multiple write operations are applied to\nan object within a short time window." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pins/{pin_id}/analytics": { "get": { "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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account:\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.", "tags": [ "pins" ], "operationId": "pins/analytics", "security": [ { "pinterest_oauth2": [ "boards:read", "pins:read" ] } ], "x-ratelimit-category": "org_analytics", "x-sandbox": "disabled", "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": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinAnalyticsResponse" } } } }, "400": { "description": "Invalid pins analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid pins analytics parameters." } } } }, "403": { "description": "Not authorized to access board or Pin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access board or Pin." } } } }, "404": { "description": "Pin not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Pin not found." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pins/{pin_id}/save": { "post": { "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) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account:\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.", "tags": [ "pins" ], "operationId": "pins/save", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write", "pins:read", "pins:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": "enabled", "x-codeSamples": [ { "lang": "python", "label": "Python SDK", "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# https://developers.pinterest.com/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# https://developers.pinterest.com/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" }, { "lang": "cURL", "label": "curl", "source": "# Pin and Board information can be fetched from profile page or from create/list pin method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/pins/list\n# https://developers.pinterest.com/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" }, { "lang": "cURL", "label": "curl (Sandbox)", "source": "# Pin and Board information can be fetched from profile page or from create/list pin method here:\n# https://developers.pinterest.com/docs/api/v5/#operation/pins/list\n# https://developers.pinterest.com/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" } ], "parameters": [ { "$ref": "#/components/parameters/path_pin_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "description": "Request object used to save an existing pin", "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "board_id": { "description": "Unique identifier of the board to which the pin will be saved.", "type": "string", "pattern": "^\\d+$", "nullable": true }, "board_section_id": { "description": "Unique identifier of the board section to which the pin will be saved.", "type": "string", "pattern": "^\\d+$", "nullable": true } } } } } }, "responses": { "201": { "description": "Successfully saved pin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pin" } } } }, "403": { "description": "Not authorized to access Board or Pin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 29, "message": "You are not permitted to access that resource." } } } }, "404": { "description": "Board or Pin not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "BoardNotFound": { "value": { "code": 40, "message": "Board not found." } }, "PinNotFound": { "value": { "code": 50, "message": "Pin not found." } }, "BoardSectionNotFound": { "value": { "code": 2031, "message": "Sorry! We couldn't find this board section." } } } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/resources/ad_account_countries": { "get": { "summary": "Get ad accounts countries", "description": "Get Ad Accounts countries", "operationId": "ad_account_countries/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdAccountsCountryResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "resources" ] } }, "/resources/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 and Ads Analytics for more information.", "operationId": "delivery_metrics/get", "security": [ { "pinterest_oauth2": [ "ads:read", "pins:read", "user_accounts:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_report_type" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeliveryMetricsResponse" } } }, "description": "Success" }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "resources" ] } }, "/resources/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\nThis endpoint is currently in beta and not available to all apps. Learn more.", "operationId": "lead_form_questions/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "responses": { "200": { "description": "Success" }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "resources" ] } }, "/resources/metrics_ready_state": { "get": { "summary": "Get metrics ready state", "description": "Learn whether conversion or non-conversion metrics are finalized and ready to query.", "operationId": "metrics_ready_state/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": "enabled", "parameters": [ { "name": "date", "description": "Analytics reports request date (UTC). Format: YYYY-MM-DD", "in": "query", "required": true, "style": "form", "schema": { "type": "string", "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$", "example": "2022-07-13" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookClosedResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "resources" ] } }, "/resources/targeting/interests/{interest_id}": { "get": { "summary": "Get interest details", "description": "

Get details of a specific interest given interest ID.

Click here for a spreadsheet listing interests and their IDs.

", "operationId": "interest_targeting_options/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_interest_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleInterestTargetingOptionResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "resources" ] } }, "/resources/targeting/{targeting_type}": { "get": { "summary": "Get targeting options", "description": "

You can use targeting values in ads placement to define your intended audience.

Targeting metrics are organized around targeting specifications.

For more information on ads targeting, see Audience targeting.

\n

Sample return:

 [{"36313": "Australia: Moreton Bay - North", "124735": "Canada: North Battleford", "36109": "Australia: Murray", "36108": "Australia: Mid North Coast", "36101": "Australia: Capital Region", "811": "U.S.: Reno", "36103": "Australia: Central West", "36102": "Australia: Central Coast", "36105": "Australia: Far West and Orana", "36104": "Australia: Coffs Harbour - Grafton", "36107": "Australia: Illawarra", "36106": "Australia: Hunter Valley Exc Newcastle", "554017": "New Zealand: Wanganui", "554016": "New Zealand: Marlborough", "554015": "New Zealand: Gisborne", "554014": "New Zealand: Tararua", "554013": "New Zealand: Invercargill", "GR": "Greece", "554011": "New Zealand: Whangarei", "554010": "New Zealand: Far North", "717": "U.S.: Quincy-Hannibal-Keokuk", "716": "U.S.: Baton Rouge",...}]
", "operationId": "targeting_options/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_targeting_type" }, { "$ref": "#/components/parameters/query_client_id" }, { "$ref": "#/components/parameters/query_oauth_signature" }, { "$ref": "#/components/parameters/query_timestamp" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetingOptionResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "resources" ] } }, "/search/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 for more information.", "operationId": "search_user_boards/get", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:read_secret" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_query" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "items", "items": { "$ref": "#/components/schemas/Board" } } } } ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "search" ] } }, "/search/pins": { "get": { "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 for more information.", "operationId": "search_user_pins/list", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:read_secret", "pins:read", "pins:read_secret" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" }, { "$ref": "#/components/parameters/query_required_search_query" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Pin" } } } } ] } } }, "description": "Success" }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UserNotFound": { "value": { "code": 30, "message": "User not found." } } } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Search user's Pins", "tags": [ "search" ] } }, "/search/partner/pins": { "get": { "summary": "Search pins by a given search term", "description": "This endpoint is currently in beta and not available to all apps. Learn more.\n\nGet the top 10 Pins by a given search term.", "operationId": "search_partner_pins", "security": [ { "pinterest_oauth2": [ "boards:read", "pins:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": "disabled", "x-codeSamples": [ { "lang": "cURL", "label": "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" } ], "parameters": [ { "description": "Search term to look up pins.", "in": "query", "name": "term", "required": true, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/query_country_code" }, { "$ref": "#/components/parameters/query_bookmark" }, { "description": "Search locale.", "in": "query", "name": "locale", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/result_limit" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SummaryPin" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid pins", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid pin filter value" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "search" ] } }, "/terms/related": { "get": { "summary": "List related terms", "description": "Get a list of terms logically related to each input term.

\nExample: the term 'workout' would list related terms like 'one song workout', 'yoga workout', 'workout motivation', etc.", "tags": [ "terms" ], "operationId": "terms_related/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_list_input_terms" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RelatedTerms" } } }, "description": "Success" }, "400": { "description": "Invalid terms related parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid terms related parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/terms/suggested": { "get": { "summary": "List suggested terms", "description": "Get popular search terms that begin with your input term.

\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.", "tags": [ "terms" ], "operationId": "terms_suggested/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_input_term" }, { "$ref": "#/components/parameters/query_term_limit" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsSuggestedResponse" } } }, "description": "Success" }, "400": { "description": "Invalid terms suggested parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid terms suggested parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/trends/keywords/{region}/top/{trend_type}": { "get": { "summary": "List trending keywords", "description": "

Get the top trending search keywords among the Pinterest user audience.

\n

Trending keywords can be used to inform ad targeting, budget strategy, and creative decisions about which products and Pins will resonate with your audience.

\n

Geographic, demographic and interest-based filters are available to narrow down to the top trends among a specific audience. Multiple trend types are supported that can be used to identify newly-popular, evergreen or seasonal keywords.

\n

For an interactive way to explore this data, please visit trends.pinterest.com.", "operationId": "trending_keywords/list", "security": [ { "pinterest_oauth2": [ "user_accounts:read" ] } ], "x-ratelimit-category": "trends_read", "x-sandbox": "enabled", "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_normalize_against_group" }, { "$ref": "#/components/parameters/query_trending_keyword_limit" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TrendingKeywordsResponse" } } }, "description": "Success" }, "400": { "description": "Invalid trending keywords request parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid trending keywords request parameters" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "keywords" ] } }, "/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\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.", "tags": [ "user_account" ], "operationId": "user_account/get", "security": [ { "pinterest_oauth2": [ "user_accounts:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Account" } } } }, "403": { "description": "Not authorized to access the user account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access the user account." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user_account/analytics": { "get": { "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\".", "tags": [ "user_account" ], "operationId": "user_account/analytics", "security": [ { "pinterest_oauth2": [ "user_accounts:read" ] } ], "x-ratelimit-category": "org_analytics", "x-sandbox": "disabled", "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": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } } }, "description": "Success" }, "400": { "description": "Invalid user accounts analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid user accounts analytics parameters." } } } }, "403": { "description": "Not authorized to access the user account analytics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access the user account analytics." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user_account/analytics/top_pins": { "get": { "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\".", "tags": [ "user_account" ], "operationId": "user_account/analytics/top_pins", "security": [ { "pinterest_oauth2": [ "pins:read", "user_accounts:read" ] } ], "x-ratelimit-category": "org_analytics", "x-sandbox": "disabled", "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": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopPinsAnalyticsResponse" } } }, "description": "Success" }, "403": { "description": "Not authorized to access the user account analytics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access the user account analytics." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user_account/analytics/top_video_pins": { "get": { "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\".", "tags": [ "user_account" ], "operationId": "user_account/analytics/top_video_pins", "security": [ { "pinterest_oauth2": [ "pins:read", "user_accounts:read" ] } ], "x-ratelimit-category": "org_analytics", "x-sandbox": "disabled", "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": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopVideoPinsAnalyticsResponse" } } }, "description": "Success" }, "403": { "description": "Not authorized to access the user account analytics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access the user account analytics." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user_account/businesses": { "get": { "summary": "List linked businesses", "description": "Get a list of your linked business accounts.", "operationId": "linked_business_accounts/get", "security": [ { "pinterest_oauth2": [ "user_accounts:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": "enabled", "responses": { "200": { "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedBusiness" } } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "user_account" ] } }, "/user_account/followers": { "get": { "summary": "List followers", "description": "Get a list of your followers.", "operationId": "followers/list", "security": [ { "pinterest_oauth2": [ "user_accounts:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserSummary" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid user id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid user id" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "user_account" ] } }, "/user_account/following": { "get": { "summary": "List following", "description": "Get a list of who a certain user follows.", "operationId": "user_following/get", "security": [ { "pinterest_oauth2": [ "user_accounts:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_user_following_feed_type" }, { "$ref": "#/components/parameters/query_explicit_following" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Users", "items": { "$ref": "#/components/schemas/UserSummary" } } } } ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "user_account" ] } }, "/user_account/following/boards": { "get": { "summary": "List following boards", "description": "Get a list of the boards a user follows. The request returns a board summary object array.", "operationId": "boards_user_follows/list", "security": [ { "pinterest_oauth2": [ "user_accounts:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_explicit_following" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Board" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid user id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid user id" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "user_account" ] } }, "/user_account/following/{username}": { "post": { "summary": "Follow user", "description": "This endpoint is currently in beta and not available to all apps. Learn more.\n\nUse this request, as a signed-in user, to follow another user.", "tags": [ "user_account" ], "operationId": "follow_user/update", "security": [ { "pinterest_oauth2": [ "user_accounts:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_username" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FollowUserRequest" } } }, "description": "Follow a user.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserSummary" } } }, "description": "Success" }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UserNotFound": { "value": { "code": 30, "message": "User not found." } } } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } } } }, "/user_account/websites": { "post": { "summary": "Verify website", "description": "Verify a website as a signed-in user.", "tags": [ "user_account" ], "operationId": "verify_website/update", "security": [ { "pinterest_oauth2": [ "user_accounts:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": "disabled", "requestBody": { "description": "Verify a website.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWebsiteVerifyRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWebsiteSummary" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } } }, "get": { "summary": "Get user websites", "description": "Get user websites, claimed or not", "tags": [ "user_account" ], "operationId": "user_websites/get", "security": [ { "pinterest_oauth2": [ "user_accounts:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/UserWebsiteSummary" } } } } ] } } } }, "403": { "description": "Not authorized to access the user website list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access the user website list." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-ratelimit-category": "org_read", "x-sandbox": "disabled" }, "delete": { "summary": "Unverify website", "description": "Unverifu a website verified by the signed-in user.", "tags": [ "user_account" ], "operationId": "unverify_website/delete", "security": [ { "pinterest_oauth2": [ "user_accounts:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/query_website" } ], "responses": { "204": { "description": "Successfully unverified website" }, "404": { "description": "Website not in user list.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Website not in user list." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user_account/websites/verification": { "get": { "summary": "Get user verification code for website claiming", "description": "Get verification code for user to install on the website to claim it.", "tags": [ "user_account" ], "operationId": "website_verification/get", "security": [ { "pinterest_oauth2": [ "user_accounts:read" ] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserWebsiteVerificationCode" } } }, "description": "Success" }, "403": { "description": "Not authorized to access the user verification code for website claiming.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access the user verification code for website claiming." } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "x-ratelimit-category": "org_read", "x-sandbox": "disabled" } }, "/users/{username}/interests/follow": { "get": { "summary": "List following interests", "description": "Get a list of a user's following interests in one place.", "tags": [ "user_account" ], "operationId": "user_account/followed_interests", "security": [ { "pinterest_oauth2": [ "user_accounts:read" ] } ], "x-ratelimit-category": "org_read", "parameters": [ { "$ref": "#/components/parameters/path_username" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Interest" } } } } ] } } } }, "400": { "description": "Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Authorization failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "User not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "x-sandbox": "enabled" } } }, "components": { "securitySchemes": { "pinterest_oauth2": { "type": "oauth2", "flows": { "authorizationCode": { "authorizationUrl": "https://www.pinterest.com/oauth/", "tokenUrl": "https://api.pinterest.com/v5/oauth/token", "scopes": { "ads:read": "See all of your advertising data, including ads, ad groups, campaigns etc.", "ads:write": "Create, update, or delete ads, ad groups, campaigns etc.", "billing:read": "See all of your billing data, billing profile, etc.", "billing:write": "Create, update, or delete billing data, billing profiles, etc.", "biz_access:read": "See business access data", "biz_access:write": "Create, update, or delete business access data", "boards:read": "See your public boards, including group boards you join", "boards:read_secret": "See your secret boards", "boards:write": "Create, update, or delete your public boards", "boards:write_secret": "Create, update, or delete your secret boards", "catalogs:read": "See all of your catalogs data", "catalogs:write": "Create, update, or delete your catalogs data", "pins:read": "See your public Pins", "pins:read_secret": "See your secret Pins", "pins:write": "Create, update, or delete your public Pins", "pins:write_secret": "Create, update, or delete your secret Pins", "user_accounts:read": "See your user accounts and followers", "user_accounts:write": "Update your user accounts and followers" } } } }, "conversion_token": { "type": "http", "scheme": "bearer", "description": "This security scheme only applies to the conversion events endpoint (POST /ad_accounts/{ad_account_id}/events). This endpoint requires a bearer token generated via Ads Manager (ads.pinterest.com)." }, "basic": { "type": "http", "scheme": "basic" } }, "schemas": { "Account": { "type": "object", "readOnly": true, "properties": { "account_type": { "description": "Type of account", "type": "string", "enum": [ "PINNER", "BUSINESS" ] }, "id": { "description": "User account ID.", "type": "string", "pattern": "^\\d+$", "example": "2783136121146311751" }, "profile_image": { "type": "string" }, "website_url": { "type": "string" }, "username": { "type": "string" }, "about": { "description": "Profile about description.", "type": "string" }, "business_name": { "type": "string", "nullable": true }, "board_count": { "type": "integer", "readOnly": true, "nullable": true, "example": 14, "description": "User account board count.
**Note**: Board count on user account level may differ from counts found elsewhere due to attribution of collaborative Boards." }, "pin_count": { "type": "integer", "readOnly": true, "nullable": true, "example": 339, "description": "User account pin count. This includes both created and saved pins." }, "follower_count": { "type": "integer", "readOnly": true, "nullable": true, "example": 10, "description": "User account follower count." }, "following_count": { "type": "integer", "readOnly": true, "nullable": true, "example": 347, "description": "User account following count." }, "monthly_views": { "type": "integer", "readOnly": true, "nullable": true, "example": 163, "description": "User account monthly views." } } }, "ActionType": { "type": "string", "description": "Ad group billable event type. For update, only draft ad groups may update billable event.", "example": "CLICKTHROUGH", "enum": [ "CLICKTHROUGH", "IMPRESSION", "VIDEO_V_50_MRC" ] }, "AdAccount": { "type": "object", "readOnly": true, "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "owner": { "title": "Ad account owner", "type": "object", "properties": { "username": { "type": "string", "description": "Public username for the user account" }, "id": { "type": "string", "description": "The owning account's user ID." } } }, "country": { "$ref": "#/components/schemas/Country" }, "currency": { "$ref": "#/components/schemas/Currency" }, "permissions": { "title": "permissions", "type": "array", "items": { "$ref": "#/components/schemas/BusinessAccessRole", "nullable": true } }, "created_time": { "description": "Creation time. Unix timestamp in seconds.", "example": 1451431341, "nullable": true, "title": "created_time", "type": "integer" }, "updated_time": { "description": "Last update time. Unix timestamp in seconds.", "example": 1451431341, "nullable": true, "title": "updated_time", "type": "integer" } } }, "AdAccountAnalyticsResponse": { "type": "array", "items": { "type": "object", "properties": { "AD_ACCOUNT_ID": { "description": "The ID of the advertiser that this metrics belongs to.", "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" } }, "required": [ "AD_ACCOUNT_ID" ], "additionalProperties": true, "example": { "DATE": "2021-04-01", "AD_ACCOUNT_ID": "547602124502", "SPEND_IN_DOLLAR": 30, "TOTAL_CLICKTHROUGH": 216 } } }, "AdAccountCreateRequest": { "title": "AdAccountCreate", "type": "object", "example": { "country": "US", "owner_user_id": "383791336903426391", "name": "ACME Tools" }, "properties": { "country": { "$ref": "#/components/schemas/Country" }, "name": { "description": "Ad Account name.", "example": "ACME Tools", "maxLength": 256, "title": "name", "type": "string" }, "owner_user_id": { "description": "Advertiser's owning user ID.", "example": "383791336903426391", "pattern": "^\\d+$", "title": "owner_user_id", "type": "string" } } }, "AdAccountCreateSubscriptionRequest": { "title": "AdAccountCreateSubscriptionRequest", "type": "object", "example": { "webhook_url": "https://webhook.example.com/xyz", "lead_form_id": "383791336903426390" }, "properties": { "webhook_url": { "description": "Standard HTTPS webhook URL.", "example": "https://webhook.example.com/xyz", "title": "webhook_url", "type": "string" }, "lead_form_id": { "description": "Lead form ID.", "example": "383791336903426390", "title": "Lead form ID", "type": "string", "pattern": "^\\d+$" }, "partner_access_token": { "description": "Partner access token. Only for clients that requires authentication. We recommend to avoid this param.", "type": "string" }, "partner_refresh_token": { "description": "Partner refresh token. Only for clients that requires authentication. We recommend to avoid this param.", "type": "string" } }, "required": [ "webhook_url" ] }, "AdAccountCreateSubscriptionResponse": { "title": "AdAccountCreateSubscriptionResponse", "type": "object", "properties": { "id": { "description": "Subscription ID.", "example": "8078432025948590686", "type": "string", "pattern": "^\\d+$" }, "cryptographic_key": { "description": "Base64 encoded key for client to decrypt lead data.", "example": "ucvxbV2Tdss0vNeYsdh4Qfa/1Khm2b0PqXvXeTTZh54", "type": "string" }, "cryptographic_algorithm": { "description": "Lead data encryption algorithm.", "example": "AES-256-GCM", "type": "string" }, "created_time": { "description": "Subscription creation time. Unix timestamp in milliseconds.", "example": 1699209842000, "type": "integer" } } }, "AdAccountGetSubscriptionResponse": { "title": "AdAccountGetSubscriptionsResponse", "type": "object", "allOf": [ { "type": "object", "description": "Lead ads subscription response common fields.", "properties": { "lead_form_id": { "description": "Lead form ID.", "example": "383791336903426390", "type": "string", "pattern": "^\\d+$", "nullable": true }, "webhook_url": { "description": "Standard HTTPS webhook URL.", "example": "https://webhook.example.com/xyz", "type": "string" } } }, { "type": "object", "properties": { "id": { "description": "Subscription ID.", "example": "8078432025948590686", "type": "string", "pattern": "^\\d+$" }, "user_account_id": { "description": "User account used to subscribe lead data.", "example": "549755885175", "type": "string", "pattern": "^\\d+$" }, "ad_account_id": { "description": "The Ad Account ID that this lead form belongs to.", "example": "549755885176", "type": "string", "pattern": "^\\d+$" }, "api_version": { "description": "API version.", "example": "v5", "type": "string" }, "cryptographic_key": { "description": "Base64 encoded key for client to decrypt lead data.", "example": "ucvxbV2Tdss0vNeYsdh4Qfa/1Khm2b0PqXvXeTTZh54", "type": "string" }, "cryptographic_algorithm": { "description": "Lead data encryption algorithm.", "example": "AES-256-GCM", "type": "string" }, "created_time": { "description": "Lead form creation time. Unix timestamp in milliseconds.", "example": 1699209842000, "type": "integer" } } } ] }, "AdAccountsCountryResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdAccountsCountryResponseData" } } } }, "AdAccountsCountryResponseData": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/AdCountry", "type": "string" }, "currency": { "description": "Country currency.", "example": "Dollars", "type": "string" }, "index": { "type": "number", "description": "Country index", "example": 1 }, "name": { "type": "string", "description": "Country name", "example": "United States of America" } } }, "AdArrayResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdArrayResponseElement" } } }, "title": "AdArrayResponse" }, "AdArrayResponseElement": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdResponse" }, "exceptions": { "$ref": "#/components/schemas/Exception" } } }, "AdCommon": { "type": "object", "description": "Creation fields", "properties": { "ad_group_id": { "description": "ID of the ad group that contains the ad.", "example": "2680059592705", "type": "string", "pattern": "^(AG)?\\d+$" }, "android_deep_link": { "description": "Deep link URL for Android devices. Not currently available. Using this field will generate an error.", "nullable": true, "type": "string" }, "carousel_android_deep_links": { "description": "Comma-separated deep links for the carousel pin on Android.", "type": "array", "nullable": true, "items": { "type": "string" } }, "carousel_destination_urls": { "description": "Comma-separated destination URLs for the carousel pin to promote.", "type": "array", "nullable": true, "items": { "type": "string" } }, "carousel_ios_deep_links": { "description": "Comma-separated deep links for the carousel pin on iOS.", "type": "array", "nullable": true, "items": { "type": "string" } }, "click_tracking_url": { "description": "Tracking url for the ad clicks.", "type": "string", "nullable": true }, "creative_type": { "$ref": "#/components/schemas/CreativeType" }, "destination_url": { "description": "Destination URL.", "type": "string", "nullable": true }, "ios_deep_link": { "description": "Deep link URL for iOS devices. Not currently available. Using this field will generate an error.", "type": "string", "nullable": true }, "is_pin_deleted": { "description": "Is original pin deleted?", "example": false, "type": "boolean" }, "is_removable": { "description": "Is pin repinnable?", "example": false, "type": "boolean" }, "name": { "description": "Name of the ad - 255 chars max.", "type": "string", "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 }, "lead_form_id": { "description": "Lead form ID for lead ad generation.", "type": "string", "pattern": "^(AG)?\\d+$", "nullable": true }, "grid_click_type": { "$ref": "#/components/schemas/GridClickType" }, "customizable_cta_type": { "type": "string", "description": "Select a call to action (CTA) to display below your ad. Available only for ads with direct links enabled. CTA options for consideration and conversion campaigns are LEARN_MORE, SHOP_NOW, BOOK_NOW, SIGN_UP, VISIT_WEBSITE, BUY_NOW, GET_OFFER, ORDER_NOW, ADD_TO_CART (for conversion campaigns with add to cart conversion events only)", "example": "LEARN_MORE", "nullable": true, "enum": [ "GET_OFFER", "LEARN_MORE", "ORDER_NOW", "SHOP_NOW", "SIGN_UP", "SUBSCRIBE", "BUY_NOW", "CONTACT_US", "GET_QUOTE", "VISIT_WEBSITE", "APPLY_NOW", "BOOK_NOW", "REQUEST_DEMO", "REGISTER_NOW", "FIND_A_DEALER", "ADD_TO_CART", "WATCH_NOW", "READ_MORE", null ] }, "quiz_pin_data": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/QuizPinData" } ], "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.", "nullable": true } } }, "AdCountry": { "type": "string", "description": "Country ID from ISO 3166-1 alpha-2.", "example": "US", "enum": [ "AD", "AE", "AF", "AG", "AI", "AL", "AM", "AO", "AQ", "AR", "AS", "AT", "AU", "AW", "AX", "AZ", "BA", "BB", "BD", "BE", "BF", "BG", "BH", "BI", "BJ", "BL", "BM", "BN", "BO", "BQ", "BR", "BS", "BT", "BV", "BW", "BY", "BZ", "CA", "CC", "CD", "CF", "CG", "CH", "CI", "CK", "CL", "CM", "CN", "CO", "CR", "CU", "CV", "CW", "CX", "CY", "CZ", "DE", "DJ", "DK", "DM", "DO", "DZ", "EC", "EE", "EG", "EH", "ER", "ES", "ET", "FI", "FJ", "FK", "FM", "FO", "FR", "GA", "GB", "GD", "GE", "GF", "GG", "GH", "GI", "GL", "GM", "GN", "GP", "GQ", "GR", "GS", "GT", "GU", "GW", "GY", "HK", "HM", "HN", "HR", "HT", "HU", "ID", "IE", "IL", "IM", "IN", "IO", "IQ", "IR", "IS", "IT", "JE", "JM", "JO", "JP", "KE", "KG", "KH", "KI", "KM", "KN", "KR", "KW", "KY", "KZ", "LA", "LB", "LC", "LI", "LK", "LR", "LS", "LT", "LU", "LV", "LY", "MA", "MC", "MD", "ME", "MF", "MG", "MH", "MK", "ML", "MM", "MN", "MO", "MP", "MQ", "MR", "MS", "MT", "MU", "MV", "MW", "MX", "MY", "MZ", "NA", "NC", "NE", "NF", "NG", "NI", "NL", "NO", "NP", "NR", "NU", "NZ", "OM", "PA", "PE", "PF", "PG", "PH", "PK", "PL", "PM", "PN", "PR", "PS", "PT", "PW", "PY", "QA", "RE", "RO", "RS", "RU", "RW", "SA", "SB", "SC", "SD", "SE", "SG", "SH", "SI", "SJ", "SK", "SL", "SM", "SN", "SO", "SR", "SS", "ST", "SV", "SX", "SY", "SZ", "TC", "TD", "TF", "TG", "TH", "TJ", "TK", "TL", "TM", "TN", "TO", "TR", "TT", "TV", "TW", "TZ", "UA", "UG", "UM", "US", "UY", "UZ", "VA", "VC", "VE", "VG", "VI", "VN", "VU", "WF", "WS", "YE", "YT", "ZA", "ZM", "ZW" ] }, "AdCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/AdCommon" }, { "$ref": "#/components/schemas/AdPinId" }, { "type": "object", "title": "Request schema for creating ads", "required": [ "ad_group_id", "pin_id", "creative_type" ] } ] }, "AdGroupArrayResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdGroupArrayResponseElement" } } } }, "AdGroupArrayResponseElement": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdGroupResponse" }, "exceptions": { "type": "array", "items": { "$ref": "#/components/schemas/Exception" } } } }, "AdGroupCommon": { "type": "object", "properties": { "name": { "description": "Ad group name.", "type": "string", "example": "Ad Group For Pin: 687195905986" }, "status": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/EntityStatus" } ], "description": "Ad group/entity status." }, "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 }, "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", "example": 5000000, "nullable": true }, "optimization_goal_metadata": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/OptimizationGoalMetadata" } ], "description": "Optimization goals for objective-based performance campaigns. **REQUIRED** when campaign's `objective_type` is set to `\"WEB_CONVERSION\"`.", "nullable": true }, "budget_type": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/BudgetType" } ] }, "start_time": { "description": "Ad group start time. Unix timestamp in seconds. Defaults to current time.", "type": "integer", "example": 5686848000, "nullable": true }, "end_time": { "description": "Ad group end time. Unix timestamp in seconds.", "type": "integer", "example": 5705424000, "nullable": true }, "targeting_spec": { "$ref": "#/components/schemas/TargetingSpec" }, "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 }, "tracking_urls": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/TrackingUrls" } ], "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 - {} - to remove tracking URLs.

For more information, see Third-party and dynamic tracking.", "nullable": true }, "auto_targeting_enabled": { "type": "boolean", "description": "Enable auto-targeting for ad group. Also known as \"expanded targeting\".", "example": true, "nullable": true }, "placement_group": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/PlacementGroupType" } ], "description": "Placement group." }, "pacing_delivery_type": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/PacingDeliveryType" } ] }, "campaign_id": { "description": "Campaign ID of the ad group.", "type": "string", "pattern": "^[C]?\\d+$", "example": "626736533506" }, "billable_event": { "$ref": "#/components/schemas/ActionType" }, "bid_strategy_type": { "nullable": true, "description": "Bid strategy type", "enum": [ "AUTOMATIC_BID", "MAX_BID", "TARGET_AVG", null ], "example": "MAX_BID", "title": "BidStrategyType", "type": "string" } } }, "AdGroupCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/AdGroupCommon" }, { "type": "object", "properties": { "pacing_delivery_type": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/PacingDeliveryType" } ], "default": "STANDARD" }, "auto_targeting_enabled": { "type": "boolean", "allOf": [ { "type": "boolean", "description": "Enable auto-targeting for ad group.Default value is True. Also known as \"expanded targeting\".", "example": true } ] }, "budget_type": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/BudgetType" } ], "default": "DAILY" } }, "required": [ "billable_event", "campaign_id", "name" ] } ] }, "AdGroupResponse": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/AdGroupCommon" }, { "type": "object", "properties": { "id": { "description": "Ad group ID.", "type": "string", "pattern": "^\\d+$", "example": "2680060704746" }, "ad_account_id": { "description": "Advertiser ID.", "type": "string", "pattern": "^\\d+$", "example": "549755885175" }, "created_time": { "description": "Ad group creation time. Unix timestamp in seconds.", "type": "integer", "example": 1476477189 }, "updated_time": { "description": "Ad group last update time. Unix timestamp in seconds.", "type": "integer", "example": 1476477189 }, "type": { "description": "Always \"adgroup\".", "type": "string", "default": "adgroup" }, "conversion_learning_mode_type": { "type": "string", "description": "oCPM learn mode", "example": "ACTIVE", "nullable": true, "enum": [ "NOT_ACTIVE", "ACTIVE", null ] }, "summary_status": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/AdGroupSummaryStatus" } ], "description": "Ad group summary status." }, "feed_profile_id": { "description": "Feed Profile ID associated to the adgroup.", "type": "string", "example": "626736533506" }, "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." } } } ] }, "AdGroupSummaryStatus": { "type": "string", "description": "Summary status for ad group", "example": "RUNNING", "enum": [ "RUNNING", "PAUSED", "NOT_STARTED", "COMPLETED", "ADVERTISER_DISABLED", "ARCHIVED", "DRAFT", "DELETED_DRAFT" ] }, "AdGroupUpdateRequest": { "allOf": [ { "$ref": "#/components/schemas/AdGroupCommon" }, { "type": "object", "properties": { "id": { "description": "Ad group ID.", "type": "string", "pattern": "^\\d+$", "example": "2680060704746" } }, "required": [ "id" ] } ] }, "AdGroupsAnalyticsResponse": { "type": "array", "items": { "type": "object", "properties": { "AD_GROUP_ID": { "description": "The ID of the ad group that this metrics belongs to.", "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" } }, "required": [ "AD_GROUP_ID" ], "additionalProperties": true, "example": { "DATE": "2021-04-01", "AD_GROUP_ID": "547602124502", "SPEND_IN_DOLLAR": 30, "TOTAL_CLICKTHROUGH": 216 } } }, "AdGroupAudienceSizingRequest": { "type": "object", "properties": { "auto_targeting_enabled": { "type": "boolean", "description": "Enable auto-targeting for ad group. Also known as \"expanded targeting\".", "example": true, "default": true }, "placement_group": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/PlacementGroupType" } ], "default": "ALL", "description": "Placement group." }, "creative_types": { "description": "Pin creative types filter.

Note: SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.", "type": "array", "items": { "type": "string", "example": "REGULAR", "enum": [ "REGULAR", "VIDEO", "SHOPPING", "CAROUSEL", "MAX_VIDEO", "SHOP_THE_PIN", "COLLECTION", "IDEA" ] }, "nullable": true }, "targeting_spec": { "$ref": "#/components/schemas/TargetingSpec" }, "product_group_ids": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$", "example": "23423422123" }, "description": "Targeted product group IDs.

Note: This can only be combined with shopping/catalog sales campaigns. For more information, click here. SHOPPING_RETARGETING must be included in targeting_spec object or this field will be ignored.", "nullable": true }, "keywords": { "type": "array", "description": "Array of keyword objects. If the keywords field is missing, all keywords will be targeted.", "items": { "type": "object", "properties": { "match_type": { "$ref": "#/components/schemas/MatchTypeResponse" }, "value": { "type": "string", "description": "Keyword value (120 chars max)." } }, "required": [ "match_type", "value" ] }, "nullable": true } } }, "AdGroupAudienceSizingResponse": { "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", "example": 100000 }, "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", "example": 150000 } } }, "AdPinId": { "type": "object", "properties": { "pin_id": { "description": "Pin ID.", "example": "394205773611545468", "type": "string", "pattern": "^\\d+$" } } }, "AdPreviewRequest": { "oneOf": [ { "example": { "image_url": "https://somewebsite.com/someimage.jpg", "title": "My Preview Image" }, "properties": { "image_url": { "description": "Image URL.", "example": "https://somewebsite.com/someimage.jpg", "title": "image_url", "type": "string" }, "title": { "description": "Title displayed below ad.", "example": "My Preview Image", "title": "title", "type": "string" } }, "required": [ "image_url", "title" ], "title": "AdPreviewCreateFromImage", "type": "object" }, { "example": { "pin_id": "7389479023" }, "properties": { "pin_id": { "description": "Pin ID.", "example": "7389479023", "title": "pin_id", "type": "string" } }, "required": [ "pin_id" ], "title": "AdPreviewCreateFromPin", "type": "object" } ] }, "AdPreviewURLResponse": { "example": { "url": "https://ads.pinterest.com/ad-preview/58f1a0e9ab0bd0f99462a0e4c5dd7e8297888c8a36331e88f757abe8f0295d31/" }, "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'", "example": "https://ads.pinterest.com/ad-preview/58f1a0e9ab0bd0f99462a0e4c5dd7e8297888c8a36331e88f757abe8f0295d31/", "title": "url", "type": "string" } }, "title": "AdPreviewURLResponse", "type": "object" }, "AdResponse": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/AdCommon" }, { "$ref": "#/components/schemas/AdPinId" }, { "type": "object", "properties": { "ad_account_id": { "description": "The ID of the advertiser that this ad belongs to.", "example": "549755885175", "type": "string", "pattern": "^\\d+$" }, "campaign_id": { "description": "ID of the ad campaign that contains this ad.", "example": "626735565838", "type": "string", "pattern": "^\\d+$" }, "collection_items_destination_url_template": { "description": "Destination URL template for all items within a collections drawer.", "type": "string", "nullable": true }, "created_time": { "description": "Pin creation time. Unix timestamp in seconds.", "example": 1451431341, "type": "integer" }, "id": { "description": "The ID of this ad.", "example": "687195134316", "type": "string", "pattern": "^\\d+$" }, "rejected_reasons": { "description": "Enum reason why the pin was rejected. Returned if review_status is \"REJECTED\".", "type": "array", "items": { "type": "string", "description": "ad disapproval reasons", "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" ] } }, "rejection_labels": { "description": "Text reason why the pin was rejected. Returned if review_status is \"REJECTED\".", "type": "array", "items": { "type": "string" } }, "review_status": { "type": "string", "description": "Ad review status", "example": "PENDING", "enum": [ "OTHER", "PENDING", "REJECTED", "APPROVED" ] }, "type": { "description": "Always \"ad\".", "example": "pinpromotion", "type": "string" }, "updated_time": { "description": "Last update time. Unix timestamp in seconds.", "example": 1451431341, "type": "integer" }, "summary_status": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/PinPromotionSummaryStatus" } ], "description": "Ad summary status" } } } ] }, "AdUpdateRequest": { "allOf": [ { "$ref": "#/components/schemas/AdCommon" }, { "type": "object", "title": "AdUpdateRequest", "properties": { "id": { "type": "string", "example": "687195134316", "pattern": "^\\d+$", "description": "The ID of this ad.", "title": "id" }, "pin_id": { "type": "string", "description": "Pin ID. This field may only be updated for draft ads.", "example": "394205773611545468", "pattern": "^\\d+$", "nullable": true } }, "required": [ "id" ] } ] }, "AdsAnalyticsCreateAsyncRequest": { "type": "object", "allOf": [ { "type": "object", "properties": { "start_date": { "description": "Metric report start date (UTC). Format: YYYY-MM-DD", "type": "string", "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$", "example": "2020-12-20" }, "end_date": { "description": "Metric report end date (UTC). Format: YYYY-MM-DD", "type": "string", "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$", "example": "2020-12-20" }, "granularity": { "description": "TOTAL - metrics are aggregated over the specified date range.
DAY - metrics are broken down daily.
HOUR - metrics are broken down hourly.
WEEKLY - metrics are broken down weekly.
MONTHLY - metrics are broken down monthly", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Granularity" } ] }, "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.", "type": "integer", "allOf": [ { "$ref": "#/components/schemas/ConversionAttributionWindowDays" } ], "default": 30 }, "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. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days.", "type": "integer", "allOf": [ { "$ref": "#/components/schemas/ConversionAttributionWindowDays" } ], "default": 30 }, "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.", "type": "integer", "allOf": [ { "$ref": "#/components/schemas/ConversionAttributionWindowDays" } ], "default": 1 }, "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.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/ConversionReportTimeType" } ], "default": "TIME_OF_AD_ACTION" }, "attribution_types": { "description": "List of types of attribution for the conversion report", "type": "array", "items": { "$ref": "#/components/schemas/ConversionReportAttributionType" } } }, "required": [ "start_date", "end_date", "granularity" ] }, { "type": "object", "allOf": [ { "type": "object", "properties": { "campaign_ids": { "type": "array", "description": "List of campaign ids", "example": [ "12345678" ], "items": { "type": "string", "pattern": "^\\d+$" }, "maxItems": 500, "minItems": 1 } } }, { "type": "object", "properties": { "campaign_statuses": { "type": "array", "description": "List of status values for filtering", "example": [ "RUNNING", "PAUSED" ], "items": { "$ref": "#/components/schemas/CampaignSummaryStatus" }, "maxItems": 6, "minItems": 1 } } }, { "type": "object", "properties": { "campaign_objective_types": { "type": "array", "description": "List of values for filtering. [\"WEB_SESSIONS\"] in BETA.", "example": [ "AWARENESS", "VIDEO_VIEW" ], "items": { "$ref": "#/components/schemas/ObjectiveType" }, "maxItems": 6, "minItems": 1 } } }, { "type": "object", "properties": { "ad_group_ids": { "type": "array", "description": "List of ad group ids", "example": [ "12345678" ], "items": { "type": "string", "pattern": "^\\d+$" }, "maxItems": 500, "minItems": 1 } } }, { "type": "object", "properties": { "ad_group_statuses": { "type": "array", "description": "List of values for filtering", "example": [ "RUNNING", "PAUSED" ], "items": { "$ref": "#/components/schemas/AdGroupSummaryStatus" }, "maxItems": 6, "minItems": 1 } } }, { "type": "object", "properties": { "ad_ids": { "type": "array", "description": "List of ad ids [This parameter is no supported for Product Item Level Reports]", "example": [ "12345678" ], "items": { "type": "string", "pattern": "^\\d+$" }, "maxItems": 500, "minItems": 1 } } }, { "type": "object", "properties": { "ad_statuses": { "type": "array", "description": "List of values for filtering [This parameter is not supported for Product Item Level Reports]", "example": [ "APPROVED", "PAUSED" ], "items": { "$ref": "#/components/schemas/PinPromotionSummaryStatus" }, "maxItems": 6, "minItems": 1 } } }, { "type": "object", "properties": { "product_group_ids": { "type": "array", "description": "List of product group ids", "example": [ "12345678" ], "items": { "type": "string", "pattern": "^\\d+$" }, "maxItems": 500, "minItems": 1 } } }, { "type": "object", "properties": { "product_group_statuses": { "type": "array", "description": "List of values for filtering", "example": [ "RUNNING", "PAUSED" ], "items": { "$ref": "#/components/schemas/ProductGroupSummaryStatus" }, "maxItems": 6, "minItems": 1 } } }, { "type": "object", "properties": { "product_item_ids": { "type": "array", "description": "List of product item ids", "example": [ "12345678" ], "items": { "type": "string", "pattern": "^\\d+$" }, "maxItems": 500, "minItems": 1 } } }, { "$ref": "#/components/schemas/TargetingTypeFilter" }, { "type": "object", "properties": { "metrics_filters": { "type": "array", "description": "List of metrics filters", "minItems": 1, "items": { "$ref": "#/components/schemas/AdsAnalyticsMetricsFilter" } } } } ] }, { "type": "object", "required": [ "level", "columns" ], "properties": { "columns": { "description": "Metric and entity columns. Pin promotion and ad related columns are not supported for the Product Item level reports.", "type": "array", "items": { "$ref": "#/components/schemas/ReportingColumnAsync" } }, "level": { "type": "string", "description": "Level of the report", "allOf": [ { "$ref": "#/components/schemas/MetricsReportingLevel" } ], "example": "CAMPAIGN" }, "report_format": { "description": "Specification for formatting the report data. Reports in JSON will not zero-fill metrics, whereas reports in CSV will. Both report formats will omit rows where all the columns are equal to 0.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/DataOutputFormat" } ], "default": "JSON" } } } ] }, "AdsAnalyticsCreateAsyncResponse": { "type": "object", "properties": { "report_status": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/BulkReportingJobStatus" } ] }, "token": { "type": "string" }, "message": { "type": "string", "nullable": true } } }, "AdsAnalyticsFilterColumn": { "type": "string", "description": "Reporting columns for sync reporting data filter", "example": "SPEND_IN_DOLLAR", "enum": [ "SPEND_IN_DOLLAR", "TOTAL_IMPRESSION" ] }, "AdsAnalyticsFilterOperator": { "type": "string", "description": "Filter operator for sync reporting", "example": "LESS_THAN", "enum": [ "LESS_THAN", "GREATER_THAN" ] }, "AdsAnalyticsGetAsyncResponse": { "type": "object", "properties": { "report_status": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/BulkReportingJobStatus" } ] }, "url": { "type": "string", "nullable": true }, "size": { "type": "number", "nullable": true } } }, "AdsAnalyticsMetricsFilter": { "type": "object", "properties": { "field": { "$ref": "#/components/schemas/AdsAnalyticsFilterColumn" }, "operator": { "$ref": "#/components/schemas/AdsAnalyticsFilterOperator" }, "values": { "type": "array", "description": "List of values for filtering", "items": { "type": "number" }, "minItems": 1 } }, "required": [ "field", "operator", "values" ] }, "AdsAnalyticsResponse": { "type": "array", "items": { "type": "object", "properties": { "AD_ID": { "description": "The ID of the ad that this metrics belongs to.", "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" } }, "required": [ "AD_ID" ], "additionalProperties": true, "example": { "DATE": "2021-04-01", "AD_ID": "547602124502", "SPEND_IN_DOLLAR": 30, "TOTAL_CLICKTHROUGH": 216 } } }, "AdsAnalyticsTargetingType": { "type": "string", "description": "Reporting targeting type", "example": "APPTYPE", "enum": [ "KEYWORD", "APPTYPE", "GENDER", "LOCATION", "PLACEMENT", "COUNTRY", "TARGETED_INTEREST", "PINNER_INTEREST", "AUDIENCE_INCLUDE", "GEO", "AGE_BUCKET", "REGION" ] }, "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", "pattern": "^\\d+$", "example": "12312451231" }, "discountType": { "description": "The type of discount of this credit", "type": "string", "nullable": true, "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 ] }, "discountInMicroCurrency": { "description": "The discount applied in the offer’s currency value.", "type": "number", "nullable": true, "example": 125000000 }, "discountCurrency": { "type": "string", "nullable": true, "description": "Currency value for the discount.", "example": "USD" }, "title": { "description": "Human readable title of the offer code.", "type": "string", "nullable": true, "example": "Ads Credits" }, "remainingDiscountInMicroCurrency": { "type": "number", "nullable": true, "description": "The credits left to spend.", "example": 125000000 } } }, "AdsCreditRedeemRequest": { "type": "object", "required": [ "offerCodeHash", "validateOnly" ], "properties": { "offerCodeHash": { "description": "Takes in a SHA256 hash of the offerCode.", "example": "138e9e0ff7e38cf511b880975eb574c09aa9d5e1657590ab0431040da68caa67", "type": "string", "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", "example": true, "type": "boolean" } } }, "AdsCreditRedeemResponse": { "type": "object", "properties": { "success": { "description": "Returns true if the offer code was successfully applied(validateOnly=false) or can be applied(validateOnly=true).", "type": "boolean", "example": false }, "errorCode": { "description": "Error code type if error occurs", "type": "integer", "nullable": true, "example": 2708 }, "errorMessage": { "description": "Reason for failure", "type": "string", "nullable": true, "example": "The offer has already been redeemed by this advertiser" } } }, "AgeBucketList": { "title": "AgeRange", "type": "array", "example": [ "35-44", "50-54" ], "items": { "type": "string", "enum": [ "18-24", "25-34", "35-44", "45-49", "50-54", "55-64", "65+" ] } }, "AnalyticsDailyMetrics": { "type": "object", "properties": { "data_status": { "$ref": "#/components/schemas/DataStatus" }, "date": { "description": "Metrics date (UTC): YYYY-MM-DD.", "example": "2019-12-01", "type": "string" }, "metrics": { "$ref": "#/components/schemas/Metrics" } } }, "AnalyticsMetricsResponse": { "type": "object", "properties": { "summary_metrics": { "description": "The metric name and value over the requested period for each requested metric", "type": "object", "additionalProperties": { "type": "number" }, "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 } }, "daily_metrics": { "description": "Array with the requested daily metric records", "items": { "$ref": "#/components/schemas/AnalyticsDailyMetrics" }, "type": "array" } } }, "AnalyticsResponse": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/AnalyticsMetricsResponse" } }, "Audience": { "properties": { "ad_account_id": { "description": "Ad account ID.", "example": "549755885175", "pattern": "^\\d+$", "title": "ad_account_id", "type": "string" }, "id": { "description": "Audience ID.", "example": "1234", "pattern": "^\\d+$", "title": "id", "type": "string" }, "name": { "description": "Audience name.", "example": "ACME Tools", "title": "name", "type": "string" }, "audience_type": { "type": "string", "description": "Audience types: ACTALIKE, ENGAGEMENT, CUSTOMER_LIST and VISITOR", "title": "audience_type" }, "description": { "description": "Audience description.", "example": "People who love making quilts.", "nullable": true, "title": "description", "type": "string" }, "rule": { "$ref": "#/components/schemas/AudienceRule" }, "size": { "description": "Audience size.", "example": 1000, "nullable": true, "title": "size", "type": "integer" }, "status": { "type": "string", "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.", "title": "status" }, "type": { "description": "Always \"audience\".", "example": "audience", "title": "type", "type": "string" }, "created_timestamp": { "description": "Creation time. Unix timestamp in seconds.", "example": 1451431341, "nullable": true, "title": "created_time", "type": "integer" }, "updated_timestamp": { "description": "Last update time. Unix timestamp in seconds.", "example": 1451431341, "nullable": true, "title": "updated_time", "type": "integer" } }, "title": "Audience", "type": "object" }, "AudienceCategory": { "title": "AudienceCategory", "type": "object", "properties": { "key": { "title": "key", "description": "Interest unique key (same as ID).", "type": "string", "example": "1234567" }, "name": { "title": "name", "description": "Interest name.", "type": "string", "example": "travel" }, "ratio": { "title": "ratio", "description": "Interest's percent of category's total audience.", "type": "number", "example": 0.551 }, "index": { "title": "index", "description": "Interest affinity index.", "type": "number", "example": 1.2 }, "id": { "title": "id", "description": "Interest ID.", "type": "string", "example": "1234567" }, "subcategories": { "title": "subcategories", "description": "Subcategory interest distribution", "type": "array", "items": { "title": "AudienceSubcategory", "type": "object", "properties": { "key": { "title": "key", "description": "Interest unique key (same as ID).", "type": "string", "example": "958862518888" }, "name": { "title": "name", "description": "Subinterest name.", "type": "string", "example": "travel destinations" }, "ratio": { "title": "ratio", "description": "Subinterest's percent of category's total audience.", "type": "number", "example": 0.482 }, "index": { "title": "index", "description": "Subinterest affinity index.", "type": "number", "example": 1.2 }, "id": { "title": "id", "description": "Subinterest ID.", "type": "string", "example": "958862518888" } } } } } }, "AudienceCommon": { "title": "AudienceCommon", "type": "object", "properties": { "ad_account_id": { "title": "ad_account_id", "description": "Ad account ID.", "type": "string", "example": "549755885175", "pattern": "^\\d+$" }, "name": { "title": "name", "description": "Audience name.", "type": "string", "example": "string" }, "rule": { "$ref": "#/components/schemas/AudienceRule" } } }, "AudienceCreateCustomRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/AudienceCommon" }, { "title": "AudienceCreateCustomRequest", "required": [ "sharing_type", "name", "rule", "data_party" ], "properties": { "sharing_type": { "$ref": "#/components/schemas/AudienceSharingType" }, "data_party": { "$ref": "#/components/schemas/AudienceDataParty" }, "category": { "type": "string", "example": "DLX Demographics" } } } ] }, "AudienceCreateRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/AudienceCommon" }, { "title": "AudienceCreateRequest", "required": [ "audience_type", "name", "rule" ], "properties": { "description": { "$ref": "#/components/schemas/AudienceDescription" }, "audience_type": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/AudienceType" }, { "title": "audience_type", "description": "Audience types: ACTALIKE, ENGAGEMENT, CUSTOMER_LIST and VISITOR. Values are case-sensitive." } ] } } } ] }, "AudienceDataParty": { "description": "Whether the data is owned by the partner (1p) or by the data provider (3p)", "type": "string", "enum": [ "1p", "3p" ] }, "AudienceDefinition": { "title": "AudienceDefinition", "description": "Queryable audience representation.", "type": "object", "properties": { "date": { "title": "date", "description": "Generation date", "type": "string", "nullable": true, "example": "2022-10-09" }, "type": { "$ref": "#/components/schemas/AudienceDefinitionType" }, "scope": { "$ref": "#/components/schemas/AudienceDefinitionScope" } }, "example": { "date": "2022-10-09", "scope": "PARTNER", "type": "IMPRESSION_PLUS_ENGAGEMENT" } }, "AudienceDefinitionResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AudienceDefinition" } } } }, "AudienceDefinitionScope": { "description": "Generated audience scope to request.", "type": "string", "properties": { "scope": { "enum": [ "PARTNER", "PINTEREST" ] } } }, "AudienceDefinitionType": { "description": "Generated audience type to request.", "type": "string", "properties": { "scope": { "enum": [ "IMPRESSION_PLUS_ENGAGEMENT", "ENGAGEMENT" ] } } }, "AudienceDemographicValue": { "title": "AudienceDemographicValue", "description": "Demographic detail for a single audience demographic", "type": "object", "properties": { "key": { "title": "key", "description": "Unique key for demographic item", "type": "string", "example": "us" }, "name": { "title": "name", "description": "Display name for demographic", "type": "string", "example": "United States" }, "ratio": { "title": "ratio", "description": "Value of demographic item as a percent of total audience", "type": "number", "example": 0.551 } }, "example": { "name": "United States", "key": "us", "ratio": 0.551 } }, "AudienceDemographics": { "title": "AudienceDemographics", "description": "Audience demographics", "type": "object", "properties": { "ages": { "title": "ages", "description": "Ages distribution.", "type": "array", "items": { "$ref": "#/components/schemas/AudienceDemographicValue" } }, "genders": { "title": "genders", "description": "Gender distribution.", "type": "array", "items": { "$ref": "#/components/schemas/AudienceDemographicValue" } }, "devices": { "title": "devices", "description": "Device usage distribution.", "type": "array", "items": { "$ref": "#/components/schemas/AudienceDemographicValue" } }, "metros": { "title": "metros", "description": "Geographic metro area distribution.", "type": "array", "items": { "$ref": "#/components/schemas/AudienceDemographicValue" } }, "countries": { "title": "countries", "description": "Country area distribution.", "type": "array", "items": { "$ref": "#/components/schemas/AudienceDemographicValue" } } } }, "AudienceDescription": { "title": "description", "description": "Audience description.", "type": "string", "example": "string" }, "AudienceInsightCategoryArrayResponse": { "deprecated": true, "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AudienceInsightCategoryCommon" } } } }, "AudienceInsightCategoryCommon": { "deprecated": true, "type": "object", "properties": { "key": { "example": "549755885175", "type": "string" }, "name": { "example": "travel", "type": "string" }, "ratio": { "example": 0.551, "type": "number" }, "index": { "example": 1.2, "type": "number" }, "id": { "example": "549755885175", "type": "string" } } }, "AudienceInsightType": { "default": "YOUR_TOTAL_AUDIENCE", "type": "string", "example": "YOUR_TOTAL_AUDIENCE", "enum": [ "YOUR_TOTAL_AUDIENCE", "YOUR_ENGAGED_AUDIENCE", "PINTEREST_TOTAL_AUDIENCE" ] }, "AudienceInsightsResponse": { "title": "AudienceInsightsResponse", "description": "Audience interests and demographics.", "type": "object", "properties": { "categories": { "title": "categories", "description": "Category interest distribution", "type": "array", "items": { "$ref": "#/components/schemas/AudienceCategory" } }, "demographics": { "$ref": "#/components/schemas/AudienceDemographics" }, "type": { "$ref": "#/components/schemas/AudienceInsightType" }, "date": { "title": "date", "description": "Generation date", "type": "string", "nullable": true, "example": "2022-10-09", "pattern": "^\\d{4}-\\d{2}-\\d{2}$" }, "size": { "title": "size", "description": "Population count.", "type": "integer", "example": 10000 }, "size_is_upper_bound": { "title": "size_is_upper_bound", "description": "Indicates whether the audience size has been rounded up to the next highest upper boundary.", "type": "boolean", "example": true } } }, "AudienceRule": { "description": "JSON object defining targeted audience users. Example rule formats per audience type:
CUSTOMER_LIST: { \"customer_list_id\": \"<customer list ID>\"}
ACTALIKE: { \"seed_id\": [\"<audience ID>\"], \"country\": \"US\", \"percentage\": \"10\" }
(Valid countries include: \"US\", \"CA\", and \"GB\". Percentage should be 1-10.
The targeted audience should be this % size across Pinterest.)
VISITOR: { \"visitor_source_id\": [\"<conversion tag ID>\"], \"retention_days\": \"180\", \"event_source\": {\"=\": [\"web\", \"mobile\"]}, \"ingestion_source\": {\"=\": [\"tag\"]}}
(Retention days should be 1-540. Retention applies to specific customers.)
ENGAGEMENT: {\"engagement_domain\": [\"www.entomi.com\"], \"engager_type\": 1}
For more details on engagement audiences, see November 2021 changelog.", "properties": { "country": { "description": "Valid countries include: \"US\", \"CA\", and \"GB\".", "example": "US", "title": "country", "type": "string" }, "customer_list_id": { "description": "Customer list ID. For CUSTOMER_LIST `audience_type`.", "example": "5497558859876", "pattern": "^\\d+$", "title": "customer_list_id", "type": "string" }, "engagement_domain": { "description": "The audience account's verified domain. **Required** for ENGAGEMENT `audience_type`.", "example": [ "www.somedomain.com" ], "items": { "type": "string" }, "title": "engagement_domain", "type": "array" }, "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. ", "example": "click", "title": "engagement_type", "type": "string" }, "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.", "example": "checkout", "title": "event", "type": "string" }, "event_data": { "description": "Optional for VISITOR `audience_type`. With the Pinterest tag, you can use event data to capture event details from your website. This object lists all the available predefined event data fields in the Pinterest tag. You can include these event data fields as part of a VISITOR audience’s `rule`; however, you **must** specify an `event` for the `event_data` fields to be evaluated. Besides what’s listed, you can also create your own set of `event_data` fields and define their usages or purposes according to your website needs. However, the benefit of using the predefined event data fields is that we can provide various metrics based on those fields' data.
Examples per `event` type:
`pagevisit`
\"event_data\": { \"page_name\": \"My online store 123 | view items | shoe\" }
`signup`
\"event_data\": { \"lead_type\": \"New release promotion\" }
`checkout`
\"event_data\": { \"value\": 116, \"order_quantity\": 2, \"currency\": \"USD\", \"line_items\": [ { \"product_name\": \"Pillows (Set of 2)\", \"product_id\": \"11\", \"product_price\": 48, \"product_quantity\": 1 }, { \"product_name\": \"Pillows, Large (Set of 2)\", \"product_id\": \"15\", \"product_price\": 68, \"product_quantity\": 1 } ] }
`addtocart`
\"event_data\": { \"value\": 499, \"order_quantity\": 1, \"currency\": \"USD\", \"line_items\": [ { \"product_name\": \"Red leather boots\", \"product_id\": \"3486\", \"product_category\": \"shoe\", \"product_variant_id\": \"JB11103000\", \"product_price\": 499, \"product_quantity\": \"1\", \"product_brand\": \"My brand\" }]}
`watchvideo`
\"event_data\": { \"video_title\": \"My Product Video 01\" }
`lead`
\"event_data\": { \"lead_type\": \"Newsletter\" }", "properties": { "currency": { "$ref": "#/components/schemas/Currency" }, "lead_type": { "description": "Promotion code. For example, \"Newsletter\".", "example": "Newsletter", "title": "lead_type", "type": "string" }, "line_items": { "properties": { "product_brand": { "description": "Product brand. For example, \"Parker\".", "example": "Parker", "title": "product_brand", "type": "string" }, "product_category": { "description": "Product category. For example, \"Shoes\".", "example": "Shoes", "title": "product_category", "type": "string" }, "product_id": { "description": "Product ID. For example, 1414.", "example": 1414, "title": "product_id", "type": "integer" }, "product_name": { "description": "Product name. For example, \"Parker Boots\".", "example": "Parker Boots", "title": "product_name", "type": "string" }, "product_price": { "description": "Product price. For example, \"99.99\".", "example": "99.99", "title": "product_price", "type": "string" }, "product_quantity": { "description": "Product quantity. For example, 2.", "example": 2, "title": "product_quantity", "type": "integer" }, "product_variant": { "description": "Product variant. For example, \"Red\".", "example": "Red", "title": "product_variant", "type": "string" }, "product_variant_id": { "description": "Product variant ID. For example, \"1414-34832\".", "example": "1414-34832", "title": "product_variant_id", "type": "string" } }, "title": "LineItem", "type": "object" }, "order_id": { "description": "Order ID. For example, \"X-151481\".", "example": "X-151481", "title": "order_id", "type": "string" }, "order_quantity": { "description": "Order quantity. For example, 1.", "example": 1, "title": "order_quantity", "type": "integer" }, "page_name": { "description": "Page name. For example, \"Our Favorite Pins on Pinterest\".", "example": "Our Favorite Pins on Pinterest.", "title": "page_name", "type": "string" }, "promo_code": { "description": "Promotion code. For example, \"WINTER10\".", "example": "WINTER10", "title": "promo_code", "type": "string" }, "property": { "description": "Property. For example, \"Athleta\".", "example": "Athleta", "title": "property", "type": "string" }, "search_query": { "description": "Search query string. For example, \"boots\".", "example": "boots", "title": "search_query", "type": "string" }, "value": { "description": "Product value. For example, \"199.98\"", "example": "199.98", "title": "value", "type": "string" }, "video_title": { "description": "Video title. For example, \"How to style your Parker Boots\".", "example": "How to style your Parker Boots", "title": "video_title", "type": "string" } }, "title": "PinterestTagEventData", "type": "object" }, "percentage": { "description": "Percentage should be 1-10. The targeted audience should be this % size across Pinterest.", "example": 3, "title": "percentage", "type": "integer" }, "pin_id": { "description": "IDs of engaged organic pins. Optional for ENGAGEMENT `audience_type`. For example, \"pin_id:\": [\"34567\"]", "example": [ "34567" ], "items": { "pattern": "^\\d+$", "type": "string" }, "title": "pin_id", "type": "array" }, "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`.", "example": true, "title": "prefill", "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.", "example": 30, "title": "retention_days", "type": "integer" }, "seed_id": { "description": "Audience ID(s). For ACTALIKE `audience_type`. ", "example": [ "2542620639259", "2542620639261" ], "items": { "pattern": "^\\d+$", "type": "string" }, "title": "seed_id", "type": "array" }, "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\"}", "items": { "type": "string" }, "title": "url", "type": "array" }, "visitor_source_id": { "description": "The conversion tag ID, or the Pinterest tag ID, that you use on your website. For VISITOR `audience_type`.", "example": "549755885175", "pattern": "^\\d+$", "title": "visitor_source_id", "type": "string" }, "event_source": { "description": "Optional for VISITOR. You can use it as a {'=': [value]}. Supported values are: web, mobile, offline", "example": { "=": [ "web", "mobile" ] }, "title": "event_source", "type": "object" }, "ingestion_source": { "description": "Optional for VISITOR. You can use it as a {'=': [value]}. Supported values are: tag, mmp, file_upload, conversions_api", "example": { "=": [ "tag" ] }, "title": "ingestion_source", "type": "object" }, "engager_type": { "description": "Optional for ENGAGEMENT. Engager type value should be 1-2.", "example": 1, "title": "engager_type", "type": "integer" }, "campaign_id": { "description": "Campaign ID for engagement audience filter.", "example": [ "626744528398" ], "items": { "pattern": "^\\d+$", "type": "string" }, "title": "campaign_id", "type": "array" }, "ad_id": { "description": "Ad ID for engagement audience filter.", "example": [ "687201361754" ], "items": { "pattern": "^\\d+$", "type": "string" }, "title": "ad_id", "type": "array" }, "objective_type": { "description": "Objective for engagement audience filter.", "example": [ "AWARENESS" ], "items": { "$ref": "#/components/schemas/ObjectiveType" }, "title": "objective_type", "type": "array" }, "ad_account_id": { "description": "Ad account ID.", "example": "549755885175", "pattern": "^\\d+$", "title": "ad_account_id", "type": "string" } }, "title": "Rule", "type": "object" }, "AudienceSharingType": { "description": "Audience sharing type: [\"CUSTOM\", \"SYNDICATED\"]", "type": "string", "enum": [ "CUSTOM", "SYNDICATED" ] }, "AudienceType": { "description": "Audience type", "enum": [ "CUSTOMER_LIST", "VISITOR", "ENGAGEMENT", "ACTALIKE", "PERSONA" ], "example": "ACTALIKE", "title": "AudienceType", "type": "string" }, "AudienceUpdateOperationType": { "title": "operation_type", "type": "string", "description": "Audience operation type (update or remove).", "example": "UPDATE", "default": "UPDATE", "enum": [ "UPDATE", "REMOVE" ] }, "AudienceUpdateRequest": { "allOf": [ { "$ref": "#/components/schemas/AudienceCommon" }, { "title": "AudienceUpdateRequest", "type": "object", "properties": { "description": { "$ref": "#/components/schemas/AudienceDescription" }, "operation_type": { "$ref": "#/components/schemas/AudienceUpdateOperationType" } } } ] }, "AvailabilityFilter": { "type": "object", "additionalProperties": false, "properties": { "AVAILABILITY": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringCriteria" } }, "required": [ "AVAILABILITY" ] }, "BatchOperation": { "description": "The operation performed by the batch. The DELETE_DISCONTINUED operation only updates availablity to \"Out of Stock\".", "example": "UPDATE", "type": "string", "enum": [ "UPDATE", "UPSERT", "CREATE", "DELETE_DISCONTINUED", "DELETE" ] }, "BatchOperationStatus": { "description": "The status of the operation performed by the batch", "example": "PROCESSING", "type": "string", "enum": [ "PROCESSING", "COMPLETED" ] }, "BidFloor": { "example": { "bid_floors": [ 100000, 200000 ], "type": "bidfloor" }, "properties": { "bid_floors": { "description": "A list of bid floors in micro currency. For example, [100000, 200000]", "example": [ 100000, 200000 ], "items": { "type": "integer" }, "title": "bid_floors", "type": "array" }, "type": { "default": "bidfloor", "description": "Always the string 'bidfloor'", "example": "bidfloor", "title": "type", "type": "string" } }, "title": "BidFloor", "type": "object" }, "BidFloorRequest": { "example": { "targeting_spec": { "GEO": [ "BE-VOV" ], "LOCATION": [ "US" ], "LOCALE": [ "cs" ], "AGE_BUCKET": [ "25-34" ], "AUDIENCE_INCLUDE": [ "2542620905473" ], "SHOPPING_RETARGETING": [ { "lookback_window": 30, "exclusion_window": 14, "tag_types": [ 0, 6 ] }, { "lookback_window": 30, "exclusion_window": 14, "tag_types": [ 0, 6 ] } ], "GENDER": [ "male" ], "TARGETING_STRATEGY": [ "CHOOSE_YOUR_OWN" ], "APPTYPE": [ "iphone" ], "AUDIENCE_EXCLUDE": [ "2542620905475" ], "INTEREST": [ "925056443165" ] }, "bid_floor_specs": [ { "billable_event": "CLICKTHROUGH", "creative_type": "REGULAR", "currency": "USD", "countries": [ "US", "US" ], "optimization_goal_metadata": { "frequency_goal_metadata": { "timerange": "DAY", "frequency": 5 }, "conversion_tag_v3_goal_metadata": { "attribution_windows": { "view_window_days": 1, "click_window_days": 0, "engagement_window_days": 6 }, "conversion_tag_id": "123456789", "learning_mode_type": "ACTIVE", "conversion_event": "PAGE_VISIT", "is_roas_optimized": true, "cpa_goal_value_in_micro_currency": "123456789" }, "scrollup_goal_metadata": { "scrollup_goal_value_in_micro_currency": "123456789" } } }, { "billable_event": "CLICKTHROUGH", "creative_type": "REGULAR", "currency": "USD", "countries": [ "US", "US" ], "optimization_goal_metadata": { "frequency_goal_metadata": { "timerange": "DAY", "frequency": 5 }, "conversion_tag_v3_goal_metadata": { "attribution_windows": { "view_window_days": 1, "click_window_days": 0, "engagement_window_days": 6 }, "conversion_tag_id": "123456789", "learning_mode_type": "ACTIVE", "conversion_event": "PAGE_VISIT", "is_roas_optimized": true, "cpa_goal_value_in_micro_currency": "123456789" }, "scrollup_goal_metadata": { "scrollup_goal_value_in_micro_currency": "123456789" } } } ] }, "properties": { "bid_floor_specs": { "items": { "example": { "billable_event": "CLICKTHROUGH", "creative_type": "REGULAR", "currency": "USD", "countries": [ "US", "US" ], "optimization_goal_metadata": { "frequency_goal_metadata": { "timerange": "DAY", "frequency": 5 }, "conversion_tag_v3_goal_metadata": { "attribution_windows": { "view_window_days": 1, "click_window_days": 0, "engagement_window_days": 6 }, "conversion_tag_id": "123456789", "learning_mode_type": "ACTIVE", "conversion_event": "PAGE_VISIT", "is_roas_optimized": true, "cpa_goal_value_in_micro_currency": "123456789" }, "scrollup_goal_metadata": { "scrollup_goal_value_in_micro_currency": "123456789" } } }, "properties": { "countries": { "items": { "$ref": "#/components/schemas/Country" }, "title": "countries", "type": "array" }, "currency": { "$ref": "#/components/schemas/Currency" }, "objective_type": { "$ref": "#/components/schemas/ObjectiveType" }, "billable_event": { "$ref": "#/components/schemas/ActionType" }, "optimization_goal_metadata": { "$ref": "#/components/schemas/OptimizationGoalMetadata" }, "creative_type": { "$ref": "#/components/schemas/CreativeType" } }, "required": [ "billable_event", "currency" ], "title": "BidFloorSpec", "type": "object" }, "title": "bid_floor_specs", "type": "array" }, "targeting_spec": { "$ref": "#/components/schemas/TargetingSpec" } }, "required": [ "bid_floor_specs" ], "title": "BidFloorBody", "type": "object" }, "BillingProfilesResponse": { "type": "object", "properties": { "id": { "description": "Billing ID.", "type": "string", "pattern": "^\\d+$", "example": "12312451231" }, "card_type": { "description": "Type of the card.", "type": "string", "enum": [ "UNKNOWN", "VISA", "MASTERCARD", "AMERICAN_EXPRESS", "DISCOVER", "ELO" ], "example": "VISA" }, "status": { "description": "Status of the billing.", "type": "string", "enum": [ "UNSPECIFIED", "VALID", "INVALID", "PENDING", "DELETED", "SECONDARY", "PENDING_SECONDARY" ], "example": "INVALID" }, "advertiser_id": { "description": "Advertiser ID of the billing.", "type": "string", "pattern": "^\\d+$", "example": "12312451231" }, "payment_method_brand": { "description": "Brand of the payment method.", "type": "string", "enum": [ "UNKNOWN", "VISA", "MASTERCARD", "AMERICAN_EXPRESS", "DISCOVER", "SOFORT", "DINERS_CLUB", "ELO", "CARTE_BANCAIRE" ], "example": "VISA" } } }, "Board": { "title": "Board", "description": "Board", "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "example": "549755885175" }, "created_at": { "type": "string", "description": "Date and time of board creation.", "readOnly": true, "format": "date-time", "example": "2020-01-01T20:10:40-00:00" }, "board_pins_modified_at": { "type": "string", "description": "Date and time of last board pins modified.", "readOnly": true, "format": "date-time", "example": "2020-01-01T20:10:40-00:00" }, "name": { "type": "string", "example": "Summer Recipes" }, "description": { "type": "string", "nullable": true, "example": "My favorite summer recipes" }, "collaborator_count": { "type": "integer", "description": "Count of collaborators on the board.", "minimum": 0, "readOnly": true, "example": 17 }, "pin_count": { "type": "integer", "description": "Count of pins on the board.", "minimum": 0, "readOnly": true, "example": 5 }, "follower_count": { "type": "integer", "description": "Board follower count.", "readOnly": true, "minimum": 0, "example": 13 }, "media": { "type": "object", "readOnly": true, "description": "Board media.", "properties": { "image_cover_url": { "type": "string", "nullable": true, "description": "Board cover image.", "example": "https://i.pinimg.com/400x300/fd/cd/d5/fdcdd5a6d8a80824add0d054125cd957.jpg" }, "pin_thumbnail_urls": { "type": "array", "description": "Board pin thumbnail urls.", "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" ] } } }, "owner": { "allOf": [ { "$ref": "#/components/schemas/BoardOwner" } ], "type": "object", "readOnly": true }, "privacy": { "type": "string", "default": "PUBLIC", "description": "Privacy setting for a board. Learn more about secret boards and protected boards", "enum": [ "PUBLIC", "PROTECTED", "SECRET" ] } }, "required": [ "name" ] }, "BoardOwner": { "title": "Board owner", "type": "object", "properties": { "username": { "type": "string", "readOnly": true } } }, "BoardSection": { "title": "Board section", "description": "Sections help organize pins within a board.", "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "example": "549755885175" }, "name": { "type": "string", "example": "Salads", "minLength": 1, "maxLength": 180 } }, "required": [ "name" ] }, "BoardUpdate": { "title": "BoardUpdate", "description": "Board fields for updates", "type": "object", "properties": { "name": { "type": "string", "example": "Summer Recipes" }, "description": { "type": "string", "nullable": true, "example": "My favorite summer recipes" }, "privacy": { "type": "string", "enum": [ "PUBLIC", "SECRET" ] } } }, "BookClosedResponse": { "title": "BookClosed", "description": "Creation fields", "type": "object", "properties": { "conversion_metrics_ready": { "title": "conversion_metrics_ready", "description": "Are conversion metrics ready?", "type": "boolean", "example": false }, "non_conversion_metrics_ready": { "title": "non_conversion_metrics_ready", "description": "Are non-conversion metrics ready?", "type": "boolean", "example": false } } }, "BrandFilter": { "type": "object", "additionalProperties": false, "properties": { "BRAND": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringCriteria" } }, "required": [ "BRAND" ] }, "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.", "example": "DAILY", "enum": [ "DAILY", "LIFETIME", "CBO_ADGROUP" ], "type": "string" }, "BulkDownloadRequest": { "type": "object", "description": "Ad entities to get in bulk request.", "properties": { "entity_types": { "type": "array", "items": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/BulkEntityType" } ] }, "minItems": 1, "maxItems": 5, "description": "All entity types specified will be downloaded. Fewer types result in faster downloads.", "example": [ "CAMPAIGN", "AD_GROUP" ] }, "entity_ids": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "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." }, "updated_since": { "type": "string", "pattern": "^\\d+$", "example": "1622848072", "description": "Unix UTC timestamp to retrieve all entities that have changed since this time." }, "campaign_filter": { "type": "object", "properties": { "start_time": { "type": "string", "pattern": "^\\d+$", "example": "1622848072", "description": "Unix UTC timestamp." }, "end_time": { "type": "string", "pattern": "^\\d+$", "example": "1622848072", "description": "Unix UTC timestamp." }, "name": { "type": "string", "example": "campaign name", "description": "Campaign name" }, "campaign_status": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignSummaryStatus" } }, "objective_type": { "type": "array", "items": { "$ref": "#/components/schemas/ObjectiveType" } } } }, "output_format": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/BulkOutputFormat" } ], "default": "JSON" } } }, "BulkDownloadResponse": { "type": "object", "example": { "request_id": "2680059592705" }, "properties": { "request_id": { "description": "ID of the bulk request.", "example": "2680059592705", "type": "string" } } }, "BulkEntityType": { "type": "string", "description": "Refers ads entity type", "example": "AD", "enum": [ "CAMPAIGN", "AD_GROUP", "PRODUCT_GROUP", "AD", "KEYWORD" ] }, "BulkOutputFormat": { "type": "string", "description": "Bulk file output format", "enum": [ "CSV", "JSON" ] }, "BulkReportingJobStatus": { "type": "string", "description": "Possible status for a bulk reporting job", "example": "FINISHED", "enum": [ "DOES_NOT_EXIST", "FINISHED", "IN_PROGRESS", "EXPIRED", "FAILED", "CANCELLED" ] }, "BulkUpsertRequest": { "type": "object", "description": "Two set of objects to be managed asyncronusly by bulk. One for creations, one for modifications.", "properties": { "create": { "$ref": "#/components/schemas/BulkUpsertRequestCreate" }, "update": { "$ref": "#/components/schemas/BulkUpsertRequestUpdate" } } }, "BulkUpsertRequestCreate": { "type": "object", "description": "Request for creation of entities in bulk.", "properties": { "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignCreateRequest" } }, "ad_groups": { "type": "array", "items": { "$ref": "#/components/schemas/AdGroupCreateRequest" } }, "ads": { "type": "array", "items": { "$ref": "#/components/schemas/AdCreateRequest" } }, "product_groups": { "type": "array", "items": { "$ref": "#/components/schemas/ProductGroupPromotionCreateRequest" } }, "keywords": { "type": "array", "items": { "$ref": "#/components/schemas/KeywordsRequest" } } } }, "BulkUpsertRequestUpdate": { "type": "object", "description": "Request for creation of entities in bulk.", "properties": { "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignUpdateRequest" } }, "ad_groups": { "type": "array", "items": { "$ref": "#/components/schemas/AdGroupUpdateRequest" } }, "ads": { "type": "array", "items": { "$ref": "#/components/schemas/AdUpdateRequest" } }, "product_groups": { "type": "array", "items": { "$ref": "#/components/schemas/ProductGroupPromotionUpdateRequest" } }, "keywords": { "type": "array", "items": { "$ref": "#/components/schemas/KeywordUpdate" } } } }, "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" } } }, "BulkUpsertStatus": { "type": "string", "enum": [ "RUNNING", "SUCCEEDED", "FAILED" ], "example": "SUCCEEDED" }, "BulkUpsertStatusResponse": { "description": "ID of the bulk request.", "type": "object", "properties": { "status": { "$ref": "#/components/schemas/BulkUpsertStatus" }, "result_url": { "type": "string", "example": "https://pinterest-waterloo.s3.us-east-1.amazonaws.com/bulk_framework/AD_ENTITY_UPSERT/549763856637-1659122537-0b4d77d3-f620-48ce-bec9-616106afb8d4/(...)" } } }, "BusinessAccessRole": { "type": "string", "description": "Permission role for business access.", "example": "ADMIN", "enum": [ "OWNER", "ADMIN", "ANALYST", "SOS_READER", "FINANCE_MANAGER", "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" ] }, "CampaignCommon": { "type": "object", "description": "Campaign Data", "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.", "example": "549755885175", "type": "string", "pattern": "^\\d+$" }, "name": { "type": "string", "description": "Campaign name.", "example": "ACME Tools" }, "status": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/EntityStatus" } ] }, "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.", "example": 1432744744, "type": "integer", "nullable": true }, "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.", "example": 1432744744, "type": "integer", "nullable": true }, "order_line_id": { "description": "Order line ID that appears on the invoice.", "example": "549755885175", "type": "string", "pattern": "^\\d+$", "nullable": true }, "tracking_urls": { "type": "object", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/TrackingUrls" } ] }, "start_time": { "type": "integer", "description": "Campaign start time. Unix timestamp in seconds. Only used for Campaign Budget Optimization (CBO) campaigns.", "example": 1580865126, "nullable": true }, "end_time": { "type": "integer", "description": "Campaign end time. Unix timestamp in seconds. Only used for Campaign Budget Optimization (CBO) campaigns.", "example": 1644023526, "nullable": true }, "summary_status": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/CampaignSummaryStatus" } ] } } }, "CampaignCreateCommon": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CampaignCommon" }, { "properties": { "status": { "type": "string", "default": "ACTIVE", "allOf": [ { "$ref": "#/components/schemas/EntityStatus" } ] }, "is_flexible_daily_budgets": { "type": "boolean", "default": false, "allOf": [ { "$ref": "#/components/schemas/CampaignIsFlexibleDailyBudgets" } ] }, "default_ad_group_budget_in_micro_currency": { "type": "integer", "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.", "example": 0, "nullable": true }, "is_automated_campaign": { "type": "boolean", "default": false, "allOf": [ { "$ref": "#/components/schemas/CampaignIsAutomatedCampaign" } ] } } } ] }, "CampaignCreateRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CampaignCreateCommon" }, { "required": [ "name", "objective_type", "ad_account_id" ], "properties": { "objective_type": { "$ref": "#/components/schemas/ObjectiveType" } } } ] }, "CampaignCreateResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignCreateResponseItem" } } } }, "CampaignCreateResponseData": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CampaignCreateCommon" }, { "$ref": "#/components/schemas/CampaignResponse" }, { "properties": { "objective_type": { "$ref": "#/components/schemas/ObjectiveType" } } } ] }, "CampaignCreateResponseItem": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CampaignCreateResponseData" }, "exceptions": { "type": "array", "items": { "$ref": "#/components/schemas/Exception" } } } }, "CampaignId": { "properties": { "id": { "description": "Campaign ID.", "example": "549755885175", "type": "string", "pattern": "^\\d+$" } }, "type": "object" }, "CampaignIsAutomatedCampaign": { "type": "boolean", "description": "Specifies whether the campaign was created in the automated campaign flow", "example": true, "default": false }, "CampaignIsCampaignBudgetOptimization": { "type": "boolean", "description": "Determines if a campaign automatically generate ad-group level budgets given a campaign budget to maximize campaign outcome. When transitioning from non-cbo to cbo, all previous child ad group budget will be cleared.", "example": true, "default": false }, "CampaignIsFlexibleDailyBudgets": { "type": "boolean", "description": "Determine if a campaign has flexible daily budgets setup.", "example": true, "default": false }, "CampaignResponse": { "allOf": [ { "$ref": "#/components/schemas/CampaignId" }, { "$ref": "#/components/schemas/CampaignCommon" }, { "type": "object", "properties": { "objective_type": { "$ref": "#/components/schemas/ObjectiveType" }, "created_time": { "type": "integer", "description": "Campaign creation time. Unix timestamp in seconds.", "example": 1432744744 }, "updated_time": { "type": "integer", "description": "UTC timestamp. Last update time.", "example": 1432744744 }, "type": { "type": "string", "description": "Always \"campaign\".", "example": "campaign" }, "is_flexible_daily_budgets": { "type": "boolean", "description": "Determines if a campaign has flexible daily budgets setup.", "example": true, "nullable": true }, "is_campaign_budget_optimization": { "type": "boolean", "description": "Determines if a campaign automatically generate ad-group level budgets given a campaign budget to maximize campaign outcome. When transitioning from non-cbo to cbo, all previous child ad group budget will be cleared.", "example": true, "nullable": true } } } ] }, "CampaignSummaryStatus": { "type": "string", "description": "Summary status for campaign", "example": "RUNNING", "enum": [ "RUNNING", "PAUSED", "NOT_STARTED", "COMPLETED", "ADVERTISER_DISABLED", "ARCHIVED", "DRAFT", "DELETED_DRAFT" ] }, "CampaignUpdateRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CampaignId" }, { "$ref": "#/components/schemas/CampaignCommon" }, { "$ref": "#/components/schemas/CampaignCreateCommon" }, { "properties": { "is_campaign_budget_optimization": { "type": "boolean", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CampaignIsCampaignBudgetOptimization" } ] }, "is_flexible_daily_budgets": { "type": "boolean", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CampaignIsFlexibleDailyBudgets" } ] }, "is_automated_campaign": { "type": "boolean", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CampaignIsAutomatedCampaign" } ] }, "status": { "type": "string", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EntityStatus" } ] }, "objective_type": { "type": "string", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ObjectiveType" } ] } }, "required": [ "id", "ad_account_id" ] } ] }, "CampaignUpdateResponse": { "allOf": [ { "$ref": "#/components/schemas/CampaignCreateResponse" } ] }, "CampaignsAnalyticsResponse": { "type": "array", "items": { "type": "object", "properties": { "CAMPAIGN_ID": { "description": "The ID of the campaing that this metrics belongs to.", "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" } }, "required": [ "CAMPAIGN_ID" ], "additionalProperties": true, "example": { "DATE": "2021-04-01", "CAMPAIGN_ID": "547602124502", "SPEND_IN_DOLLAR": 30, "TOTAL_CLICKTHROUGH": 216 } } }, "Catalog": { "type": "object", "title": "catalog", "description": "Catalog entity", "allOf": [ { "$ref": "#/components/schemas/CatalogsDbItem" }, { "type": "object", "properties": { "id": { "description": "ID of the catalog entity.", "example": "864344156814050986", "type": "string", "pattern": "^\\d+$" }, "name": { "description": "A human-friendly name associated to a catalog entity.", "nullable": true, "type": "string" }, "catalog_type": { "$ref": "#/components/schemas/CatalogsType" } }, "required": [ "id", "name", "catalog_type" ] } ] }, "CatalogProductGroup": { "description": "non-promoted catalog product group entity", "properties": { "id": { "description": "ID of the catalog product group.", "example": "2680059592705", "title": "id", "type": "string" }, "merchant_id": { "description": "Merchant ID pertaining to the owner of the catalog product group.", "example": "2680059592705", "pattern": "^\\d+$", "title": "merchant_id", "type": "string" }, "name": { "description": "Name of catalog product group", "example": "Most Popular", "title": "name", "type": "string" }, "filters": { "description": "Object holding a list of filters", "example": { "1": [ "123chars_title" ] }, "title": "filters", "type": "object" }, "filter_v2": { "description": "Object holding a list of filters", "example": { "1": [ "123chars_title" ] }, "title": "filters", "type": "object" }, "type": { "$ref": "#/components/schemas/Board" }, "status": { "$ref": "#/components/schemas/EntityStatus" }, "feed_profile_id": { "description": "id of the feed profile belonging to this catalog product group", "pattern": "^\\d+$", "title": "feed_profile_id", "type": "string" }, "created_at": { "description": "Unix timestamp in seconds of when catalog product group was created.", "example": 1621350033000, "title": "created_at", "type": "integer" }, "last_update": { "description": "Unix timestamp in seconds of last time catalog product group was updated.", "example": 1622742155000, "title": "last_update", "type": "integer" }, "product_count": { "description": "Amount of products in the catalog product group", "example": 6, "title": "product_count", "type": "integer" }, "featured_position": { "description": "index of the featured position of the catalog product group", "example": 2, "title": "featured_position", "type": "integer" } }, "title": "CatalogProductGroup", "type": "object" }, "CatalogsDbItem": { "type": "object", "title": "db_item", "properties": { "created_at": { "type": "string", "format": "date-time", "example": "2022-03-14T15:15:22Z" }, "id": { "type": "string" }, "updated_at": { "type": "string", "format": "date-time", "example": "2022-03-14T15:16:34Z" } } }, "CatalogsHotelBatchItem": { "description": "Hotel batch item", "type": "object", "anyOf": [ { "$ref": "#/components/schemas/CatalogsCreateHotelItem" }, { "$ref": "#/components/schemas/CatalogsUpsertHotelItem" }, { "$ref": "#/components/schemas/CatalogsUpdateHotelItem" }, { "$ref": "#/components/schemas/CatalogsDeleteHotelItem" } ], "discriminator": { "propertyName": "operation", "mapping": { "CREATE": "#/components/schemas/CatalogsCreateHotelItem", "UPSERT": "#/components/schemas/CatalogsUpsertHotelItem", "UPDATE": "#/components/schemas/CatalogsUpdateHotelItem", "DELETE": "#/components/schemas/CatalogsDeleteHotelItem" } } }, "CatalogsFeed": { "type": "object", "title": "catalogs_feed", "description": "Catalogs Feed object", "oneOf": [ { "$ref": "#/components/schemas/CatalogsRetailFeed" }, { "$ref": "#/components/schemas/CatalogsHotelFeed" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailFeed", "HOTEL": "#/components/schemas/CatalogsHotelFeed" } } }, "CatalogsHotelFeed": { "type": "object", "title": "catalogs_hotel_feed", "description": "Catalogs Hotel Feed object", "allOf": [ { "$ref": "#/components/schemas/CatalogsDbItem" }, { "type": "object", "title": "feed_fields", "properties": { "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.", "nullable": true, "type": "string" }, "format": { "$ref": "#/components/schemas/CatalogsFormat" }, "catalog_type": { "$ref": "#/components/schemas/CatalogsType" }, "credentials": { "$ref": "#/components/schemas/CatalogsFeedCredentials" }, "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" }, "preferred_processing_schedule": { "$ref": "#/components/schemas/CatalogsFeedProcessingSchedule" }, "status": { "$ref": "#/components/schemas/CatalogsStatus" }, "default_currency": { "$ref": "#/components/schemas/NullableCurrency" }, "default_locale": { "description": "The locale used within a feed for product descriptions.", "example": "en-US", "type": "string" }, "catalog_id": { "description": "Catalog id pertaining to the feed. If not provided, feed will use a default catalog based on type.", "nullable": true, "type": "string", "pattern": "^\\d+$" } }, "required": [ "credentials", "format", "location", "name", "preferred_processing_schedule", "status", "catalog_type", "default_locale", "default_currency", "catalog_id" ] } ] }, "CatalogsRetailFeed": { "type": "object", "title": "catalogs_retail_feed", "description": "Catalogs Retail Feed object", "allOf": [ { "$ref": "#/components/schemas/CatalogsDbItem" }, { "type": "object", "title": "feed_fields", "properties": { "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.", "nullable": true, "type": "string" }, "format": { "$ref": "#/components/schemas/CatalogsFormat" }, "catalog_type": { "$ref": "#/components/schemas/CatalogsType" }, "credentials": { "$ref": "#/components/schemas/CatalogsFeedCredentials" }, "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" }, "preferred_processing_schedule": { "$ref": "#/components/schemas/CatalogsFeedProcessingSchedule" }, "status": { "$ref": "#/components/schemas/CatalogsStatus" }, "default_currency": { "$ref": "#/components/schemas/NullableCurrency" }, "default_locale": { "description": "The locale used within a feed for product descriptions.", "example": "en-US", "type": "string" }, "default_country": { "$ref": "#/components/schemas/Country" }, "default_availability": { "$ref": "#/components/schemas/ProductAvailabilityType" } }, "required": [ "credentials", "default_availability", "default_country", "default_currency", "default_locale", "format", "location", "name", "preferred_processing_schedule", "status", "catalog_type" ] } ] }, "CatalogsFeedCredentials": { "type": "object", "nullable": true, "description": "This field is **OPTIONAL**. Use this if your feed file requires username and password.", "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" } }, "required": [ "username", "password" ] }, "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": { "LINE_LEVEL_INTERNAL_ERROR": { "type": "integer", "description": "We experienced a technical difficulty and were unable to ingest this some items. The next ingestion will happen in 24 hours." }, "LARGE_PRODUCT_COUNT_DECREASE": { "type": "integer", "enum": [ 1 ], "description": "The product count has decreased by more than 99% compared to the last successful ingestion." }, "ACCOUNT_FLAGGED": { "type": "integer", "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." }, "IMAGE_LEVEL_INTERNAL_ERROR": { "type": "integer", "description": "We experienced a technical difficulty and were unable to download some images. The next download attempt will happen in 24 hours." }, "IMAGE_FILE_NOT_ACCESSIBLE": { "type": "integer", "description": "Image files are unreadable. Please upload new files to continue." }, "IMAGE_MALFORMED_URL": { "type": "integer", "description": "Image files are unreadable. Please check your link and upload new files to continue." }, "IMAGE_FILE_NOT_FOUND": { "type": "integer", "description": "Image files are unreadable. Please upload new files to continue." }, "IMAGE_INVALID_FILE": { "type": "integer", "description": "Image files are unreadable. Please upload new files to continue." } } }, "CatalogsFeedIngestionInfo": { "type": "object", "properties": { "IN_STOCK": { "type": "integer", "description": "The number of ingested products that are in stock." }, "OUT_OF_STOCK": { "type": "integer", "description": "The number of ingested products that are in out of stock." }, "PREORDER": { "type": "integer", "description": "The number of ingested products that are in preorder." } } }, "CatalogsFeedIngestionWarnings": { "type": "object", "properties": { "ADDITIONAL_IMAGE_LEVEL_INTERNAL_ERROR": { "type": "integer", "description": "We experienced a technical difficulty and were unable to download some additional images. The next download attempt will happen in 24 hours." }, "ADDITIONAL_IMAGE_FILE_NOT_ACCESSIBLE": { "type": "integer", "description": "Additional image files are unreadable. Please upload new files to continue." }, "ADDITIONAL_IMAGE_MALFORMED_URL": { "type": "integer", "description": "Additional image files are unreadable. Please check your link and upload new files to continue." }, "ADDITIONAL_IMAGE_FILE_NOT_FOUND": { "type": "integer", "description": "Additional image files are unreadable. Please upload new files to continue." }, "ADDITIONAL_IMAGE_INVALID_FILE": { "type": "integer", "description": "Additional image files are unreadable. Please upload new files to continue." }, "HOTEL_PRICE_HEADER_IS_PRESENT": { "type": "integer", "description": "price is not a supported column. Use base_price and sale_price instead." } } }, "CatalogsFeedProcessingResult": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CatalogsDbItem" }, { "type": "object", "title": "catalogs_feed_processing_result_fields", "properties": { "ingestion_details": { "$ref": "#/components/schemas/CatalogsFeedIngestionDetails" }, "status": { "$ref": "#/components/schemas/CatalogsFeedProcessingStatus" }, "product_counts": { "$ref": "#/components/schemas/CatalogsFeedProductCounts" }, "validation_details": { "$ref": "#/components/schemas/CatalogsFeedValidationDetails" } }, "required": [ "ingestion_details", "status", "product_counts", "validation_details" ] } ] }, "CatalogsFeedProcessingSchedule": { "type": "object", "title": "catalogs_processing_schedule", "description": "Daily processing schedule. This field is **OPTIONAL**. Use this to configure the preferred time for processing a feed (otherwise random).", "nullable": true, "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]$", "example": "02:59" }, "timezone": { "description": "The timezone considered for the processing schedule time.", "type": "string", "nullable": true, "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 ] } }, "required": [ "time", "timezone" ] }, "CatalogsFeedProcessingStatus": { "type": "string", "enum": [ "COMPLETED", "COMPLETED_EARLY", "DISAPPROVED", "FAILED", "PROCESSING", "QUEUED_FOR_PROCESSING", "UNDER_APPEAL", "UNDER_REVIEW" ] }, "CatalogsFeedProductCounts": { "type": "object", "description": "The counts can be null early in the process.", "nullable": true, "properties": { "original": { "description": "The number of products in the feed file.", "type": "integer" }, "ingested": { "description": "The number of products successfully ingested from the feed file.", "type": "integer" } } }, "CatalogsFeedValidationDetails": { "type": "object", "properties": { "errors": { "$ref": "#/components/schemas/CatalogsFeedValidationErrors" }, "warnings": { "$ref": "#/components/schemas/CatalogsFeedValidationWarnings" } }, "required": [ "errors", "warnings" ] }, "CatalogsFeedValidationErrors": { "type": "object", "properties": { "FETCH_ERROR": { "type": "integer", "description": "Pinterest couldn't download your feed." }, "FETCH_INACTIVE_FEED_ERROR": { "type": "integer", "description": "Your feed wasn't ingested because it hasn’t changed in the previous 90 days." }, "ENCODING_ERROR": { "type": "integer", "description": "Your feed includes data with an unsupported encoding format." }, "DELIMITER_ERROR": { "type": "integer", "description": "Your feed includes data with formatting errors." }, "REQUIRED_COLUMNS_MISSING": { "type": "integer", "description": "Your feed is missing some required column headers." }, "DUPLICATE_PRODUCTS": { "type": "integer", "description": "Some products are duplicated." }, "IMAGE_LINK_INVALID": { "type": "integer", "description": "Some image links are formatted incorrectly." }, "ITEMID_MISSING": { "type": "integer", "description": "Some items are missing an item id in their product metadata, those items will not be published." }, "TITLE_MISSING": { "type": "integer", "description": "Some items are missing a title in their product metadata, those items will not be published." }, "DESCRIPTION_MISSING": { "type": "integer", "description": "Some items are missing a description in their product metadata, those items will not be published." }, "PRODUCT_LINK_MISSING": { "type": "integer", "description": "Some items are missing a link URL in their product metadata, those items will not be published." }, "IMAGE_LINK_MISSING": { "type": "integer", "description": "Some items are missing an image link URL in their product metadata, those items will not be published." }, "AVAILABILITY_INVALID": { "type": "integer", "description": "Some items are missing an availability value in their product metadata, those items will not be published." }, "PRODUCT_PRICE_INVALID": { "type": "integer", "description": "Some items have price formatting errors in their product metadata, those items will not be published." }, "LINK_FORMAT_INVALID": { "type": "integer", "description": "Some link values are formatted incorrectly." }, "PARSE_LINE_ERROR": { "type": "integer", "description": "Your feed contains formatting errors for some items." }, "ADWORDS_FORMAT_INVALID": { "type": "integer", "description": "Some adwords links contain too many characters." }, "INTERNAL_SERVICE_ERROR": { "type": "integer", "description": "We experienced a technical difficulty and were unable to ingest your feed. The next ingestion will happen in 24 hours." }, "NO_VERIFIED_DOMAIN": { "type": "integer", "description": "Your merchant domain needs to be claimed." }, "ADULT_INVALID": { "type": "integer", "description": "Some items have invalid adult values." }, "IMAGE_LINK_LENGTH_TOO_LONG": { "type": "integer", "description": "Some items have image_link URLs that contain too many characters, so those items will not be published." }, "INVALID_DOMAIN": { "type": "integer", "description": "Some of your product link values don't match the verified domain associated with this account." }, "FEED_LENGTH_TOO_LONG": { "type": "integer", "description": "Your feed contains too many items, some items will not be published." }, "LINK_LENGTH_TOO_LONG": { "type": "integer", "description": "Some product links contain too many characters, those items will not be published." }, "MALFORMED_XML": { "type": "integer", "description": "Your feed couldn't be validated because the xml file is formatted incorrectly." }, "PRICE_MISSING": { "type": "integer", "description": "Some products are missing a price, those items will not be published." }, "FEED_TOO_SMALL": { "type": "integer", "description": "Your feed couldn't be validated because the file doesn't contain the minimum number of lines required." }, "MAX_ITEMS_PER_ITEM_GROUP_EXCEEDED": { "type": "integer", "description": "Some items exceed the maximum number of items per item group, those items will not be published." }, "ITEM_MAIN_IMAGE_DOWNLOAD_FAILURE": { "type": "integer", "description": "Some items' main images can't be found." }, "PINJOIN_CONTENT_UNSAFE": { "type": "integer", "description": "Some items were not published because they don't meet Pinterest's Merchant Guidelines." }, "BLOCKLISTED_IMAGE_SIGNATURE": { "type": "integer", "description": "Some items were not published because they don't meet Pinterest's Merchant Guidelines." }, "LIST_PRICE_INVALID": { "type": "integer", "description": "Some items have list price formatting errors in their product metadata, those items will not be published." }, "PRICE_CANNOT_BE_DETERMINED": { "type": "integer", "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." } } }, "CatalogsFeedValidationWarnings": { "type": "object", "properties": { "AD_LINK_FORMAT_WARNING": { "type": "integer", "description": "Some items have ad links that are formatted incorrectly." }, "AD_LINK_SAME_AS_LINK": { "type": "integer", "description": "Some items have ad link URLs that are duplicates of the link URLs for those items." }, "TITLE_LENGTH_TOO_LONG": { "type": "integer", "description": "The title for some items were truncated because they contain too many characters." }, "DESCRIPTION_LENGTH_TOO_LONG": { "type": "integer", "description": "The description for some items were truncated because they contain too many characters." }, "GENDER_INVALID": { "type": "integer", "description": "Some items have gender values that are formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences." }, "AGE_GROUP_INVALID": { "type": "integer", "description": "Some items have age group values that are formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences." }, "SIZE_TYPE_INVALID": { "type": "integer", "description": "Some items have size type values that are formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences." }, "SIZE_SYSTEM_INVALID": { "type": "integer", "description": "Some items have size system values which are not one of the supported size systems." }, "LINK_FORMAT_WARNING": { "type": "integer", "description": "Some items have an invalid product link which contains invalid UTM tracking paramaters." }, "SALES_PRICE_INVALID": { "type": "integer", "description": "Some items have sale price values that are higher than the original price of the item." }, "PRODUCT_CATEGORY_DEPTH_WARNING": { "type": "integer", "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." }, "ADWORDS_FORMAT_WARNING": { "type": "integer", "description": "Some items have adwords_redirect links that are formatted incorrectly." }, "ADWORDS_SAME_AS_LINK": { "type": "integer", "description": "Some items have adwords_redirect URLs that are duplicates of the link URLs for those items." }, "DUPLICATE_HEADERS": { "type": "integer", "description": "Your feed contains duplicate headers." }, "FETCH_SAME_SIGNATURE": { "type": "integer", "description": "Ingestion completed early because there are no changes to your feed since the last successful update.", "enum": [ 1 ] }, "ADDITIONAL_IMAGE_LINK_LENGTH_TOO_LONG": { "type": "integer", "description": "Some items have additional_image_link URLs that contain too many characters, so those items will not be published." }, "ADDITIONAL_IMAGE_LINK_WARNING": { "type": "integer", "description": "Some items have additional_image_link URLs that are formatted incorrectly and will not be published with your items." }, "IMAGE_LINK_WARNING": { "type": "integer", "description": "Some items have image_link URLs that are formatted incorrectly and will not be published with those items." }, "SHIPPING_INVALID": { "type": "integer", "description": "Some items have shipping values that are formatted incorrectly." }, "TAX_INVALID": { "type": "integer", "description": "Some items have tax values that are formatted incorrectly." }, "SHIPPING_WEIGHT_INVALID": { "type": "integer", "description": "Some items have invalid shipping_weight values." }, "EXPIRATION_DATE_INVALID": { "type": "integer", "description": "Some items have expiration_date values that are formatted incorrectly, those items will be published without an expiration date." }, "AVAILABILITY_DATE_INVALID": { "type": "integer", "description": "Some items have availability_date values that are formatted incorrectly, those items will be published without an availability date." }, "SALE_DATE_INVALID": { "type": "integer", "description": "Some items have sale_price_effective_date values that are formatted incorrectly, those items will be published without a sale date." }, "WEIGHT_UNIT_INVALID": { "type": "integer", "description": "Some items have weight_unit values that are formatted incorrectly, those items will be published without a weight unit." }, "IS_BUNDLE_INVALID": { "type": "integer", "description": "Some items have is_bundle values that are formatted incorrectly, those items will be published without being bundled with other products." }, "UPDATED_TIME_INVALID": { "type": "integer", "description": "Some items have updated_time values thate are formatted incorrectly, those items will be published without an updated time." }, "CUSTOM_LABEL_LENGTH_TOO_LONG": { "type": "integer", "description": "Some items have custom_label values that are too long, those items will be published without that custom label." }, "PRODUCT_TYPE_LENGTH_TOO_LONG": { "type": "integer", "description": "Some items have product_type values that are too long, those items will be published without that product type." }, "TOO_MANY_ADDITIONAL_IMAGE_LINKS": { "type": "integer", "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." }, "MULTIPACK_INVALID": { "type": "integer", "description": "Some items have invalid multipack values." }, "INDEXED_PRODUCT_COUNT_LARGE_DELTA": { "type": "integer", "description": "The product count has increased or decreased significantly compared to the last successful ingestion." }, "ITEM_ADDITIONAL_IMAGE_DOWNLOAD_FAILURE": { "type": "integer", "description": "Some items include additional_image_links that can't be found." }, "OPTIONAL_PRODUCT_CATEGORY_MISSING": { "type": "integer", "description": "Some items are missing a google_product_category." }, "OPTIONAL_PRODUCT_CATEGORY_INVALID": { "type": "integer", "description": "Some items include google_product_category values that are not formatted correctly according to the GPC taxonomy." }, "OPTIONAL_CONDITION_MISSING": { "type": "integer", "description": "Some items are missing a condition value, which may limit visibility in recommendations, search results and shopping experiences." }, "OPTIONAL_CONDITION_INVALID": { "type": "integer", "description": "Some items include condition values that are formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences." }, "IOS_DEEP_LINK_INVALID": { "type": "integer", "description": "Some items include invalid ios_deep_link values." }, "ANDROID_DEEP_LINK_INVALID": { "type": "integer", "description": "Some items include invalid android_deep_link." }, "UTM_SOURCE_AUTO_CORRECTED": { "type": "integer", "description": "Some items include utm_source values that are formatted incorrectly and have been automatically corrected." }, "COUNTRY_DOES_NOT_MAP_TO_CURRENCY": { "type": "integer", "description": "Some items include a currency that doesn't match the usual currency for the location where that product is sold or shipped." }, "MIN_AD_PRICE_INVALID": { "type": "integer", "description": "Some items include min_ad_price values that are formatted incorrectly." }, "GTIN_INVALID": { "type": "integer", "description": "Some items include incorrectly formatted GTINs." }, "INCONSISTENT_CURRENCY_VALUES": { "type": "integer", "description": "Some items include inconsistent currencies in price fields." }, "SALES_PRICE_TOO_LOW": { "type": "integer", "description": "Some items include sales price that is much lower than the list price." }, "SHIPPING_WIDTH_INVALID": { "type": "integer", "description": "Some items include incorrectly formatted shipping_width." }, "SHIPPING_HEIGHT_INVALID": { "type": "integer", "description": "Some items include incorrectly formatted shipping_height." }, "SALES_PRICE_TOO_HIGH": { "type": "integer", "description": "Some items include a sales price that is higher than the list price. The sales price has been defaulted to the list price." }, "MPN_INVALID": { "type": "integer", "description": "Some items include incorrectly formatted MPNs." } } }, "CatalogsFeedsCreateRequest": { "type": "object", "title": "legacy_retail_only", "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.", "additionalProperties": false, "properties": { "default_currency": { "$ref": "#/components/schemas/NullableCurrency" }, "name": { "description": "A human-friendly name associated to a given feed.", "type": "string" }, "format": { "$ref": "#/components/schemas/CatalogsFormat" }, "default_locale": { "description": "The locale used within a feed for product descriptions.", "example": "en-US", "anyOf": [ { "description": "The locale used within a feed for product descriptions.", "$ref": "#/components/schemas/CatalogsLocale" }, { "description": "The locale used within a feed for product descriptions. This free text string version is deprecated in favor of official list of supported locales defined by CatalogsLocale.", "type": "string", "deprecated": true } ] }, "credentials": { "$ref": "#/components/schemas/CatalogsFeedCredentials" }, "location": { "description": "The URL where a feed is available for download. This URL is what Pinterest will use to download a feed for processing.", "pattern": "^(http|https|ftp|sftp)://", "type": "string" }, "preferred_processing_schedule": { "$ref": "#/components/schemas/CatalogsFeedProcessingSchedule" }, "default_country": { "$ref": "#/components/schemas/Country" }, "default_availability": { "$ref": "#/components/schemas/ProductAvailabilityType" } }, "required": [ "format", "location", "name" ] }, "CatalogsHotelAttributes": { "type": "object", "allOf": [ { "properties": { "main_image": { "type": "object", "description": "The main hotel image", "properties": { "link": { "type": "string", "description": "

<= 2000 characters

\n

The link to the main hotel image. Image should be at least\n75x75 pixels to avoid errors. Use the additional_image_link field to add\nmore images of your hotel. The URL of your main_image.link must be accessible\nby the Pinterest user-agent, and send the accurate image. Please make\nsure there is no template or placeholder image at the link. Must start\nwith http:// or https://.

" }, "tag": { "type": "array", "nullable": true, "description": "Tag appended to the image that identifies image category or details. There can be multiple tags associated with an image", "items": { "type": "string" } } } }, "additional_image_link": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "

<= 2000 characters

\n

The links to additional images for your hotel. Up to ten\nadditional images can be used to show a hotel from different angles.\nMust begin with http:// or https://.

", "example": [ "https://scene.example.com/image/image_v2.jpg", "https://scene.example.com/image/image_v3.jpg" ] } } }, { "$ref": "#/components/schemas/CatalogsUpdatableHotelAttributes" } ] }, "CatalogsRetailFeedsCreateRequest": { "type": "object", "title": "feeds_retail_create_request", "description": "Request object for creating a retail feed.", "additionalProperties": false, "properties": { "default_currency": { "$ref": "#/components/schemas/NullableCurrency" }, "name": { "description": "A human-friendly name associated to a given feed.", "type": "string" }, "format": { "$ref": "#/components/schemas/CatalogsFormat" }, "default_locale": { "description": "The locale used within a feed for product descriptions.", "example": "en-US", "anyOf": [ { "description": "The locale used within a feed for product descriptions.", "$ref": "#/components/schemas/CatalogsLocale" }, { "description": "The locale used within a feed for product descriptions. This free text string version is deprecated in favor of official list of supported locales defined by CatalogsLocale.", "type": "string", "deprecated": true } ] }, "credentials": { "$ref": "#/components/schemas/CatalogsFeedCredentials" }, "location": { "description": "The URL where a feed is available for download. This URL is what Pinterest will use to download a feed for processing.", "pattern": "^(http|https|ftp|sftp)://", "type": "string" }, "preferred_processing_schedule": { "$ref": "#/components/schemas/CatalogsFeedProcessingSchedule" }, "catalog_type": { "$ref": "#/components/schemas/CatalogsType" }, "default_country": { "$ref": "#/components/schemas/Country" }, "default_availability": { "$ref": "#/components/schemas/ProductAvailabilityType" } }, "required": [ "format", "location", "name", "catalog_type", "default_country", "default_locale" ] }, "CatalogsRetailItemsFilter": { "type": "object", "properties": { "catalog_type": { "type": "string", "enum": [ "RETAIL" ] }, "item_ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } }, "catalog_id": { "type": "string", "pattern": "^\\d+$", "description": "Catalog id pertaining to the retail item. If not provided, default to oldest retail catalog" } }, "required": [ "catalog_type", "item_ids" ] }, "CatalogsHotelFeedsCreateRequest": { "type": "object", "title": "feeds_hotel_create_request", "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.", "additionalProperties": false, "properties": { "default_currency": { "$ref": "#/components/schemas/NullableCurrency" }, "name": { "description": "A human-friendly name associated to a given feed.", "type": "string" }, "format": { "$ref": "#/components/schemas/CatalogsFormat" }, "default_locale": { "description": "The locale used within a feed for product descriptions.", "example": "en-US", "anyOf": [ { "description": "The locale used within a feed for product descriptions.", "$ref": "#/components/schemas/CatalogsLocale" }, { "description": "The locale used within a feed for product descriptions. This free text string version is deprecated in favor of official list of supported locales defined by CatalogsLocale.", "type": "string", "deprecated": true } ] }, "credentials": { "$ref": "#/components/schemas/CatalogsFeedCredentials" }, "location": { "description": "The URL where a feed is available for download. This URL is what Pinterest will use to download a feed for processing.", "pattern": "^(http|https|ftp|sftp)://", "type": "string" }, "preferred_processing_schedule": { "$ref": "#/components/schemas/CatalogsFeedProcessingSchedule" }, "catalog_type": { "$ref": "#/components/schemas/CatalogsType" }, "catalog_id": { "description": "Catalog id pertaining to the feed. If not provided, feed will use a default catalog based on type. At the moment a catalog can not have multiple hotel feeds but this will change in the future.", "nullable": true, "type": "string", "pattern": "^\\d+$" } }, "required": [ "format", "location", "name", "catalog_type", "default_locale" ] }, "CatalogsHotelItemsFilter": { "type": "object", "properties": { "catalog_type": { "type": "string", "enum": [ "HOTEL" ] }, "hotel_ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } }, "catalog_id": { "type": "string", "pattern": "^\\d+$", "description": "Catalog id pertaining to the hotel item. If not provided, default to oldest hotel catalog" } }, "required": [ "catalog_type", "hotel_ids" ] }, "CatalogsVerticalFeedsCreateRequest": { "type": "object", "title": "feeds_create_request", "description": "Request object for creating a feed.", "oneOf": [ { "$ref": "#/components/schemas/CatalogsRetailFeedsCreateRequest" }, { "$ref": "#/components/schemas/CatalogsHotelFeedsCreateRequest" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailFeedsCreateRequest", "HOTEL": "#/components/schemas/CatalogsHotelFeedsCreateRequest" } } }, "CatalogsRetailFeedsUpdateRequest": { "type": "object", "title": "catalogs_feeds_update_request", "description": "Request object for updating a feed.", "additionalProperties": false, "properties": { "default_currency": { "$ref": "#/components/schemas/NullableCurrency" }, "name": { "description": "A human-friendly name associated to a given feed.", "type": "string" }, "format": { "$ref": "#/components/schemas/CatalogsFormat" }, "credentials": { "$ref": "#/components/schemas/CatalogsFeedCredentials" }, "location": { "type": "string", "pattern": "^(http|https|ftp|sftp)://", "description": "The URL where a feed is available for download. This URL is what Pinterest will use to download a feed for processing." }, "preferred_processing_schedule": { "$ref": "#/components/schemas/CatalogsFeedProcessingSchedule" }, "status": { "$ref": "#/components/schemas/CatalogsStatus" }, "catalog_type": { "$ref": "#/components/schemas/CatalogsType" }, "default_availability": { "$ref": "#/components/schemas/ProductAvailabilityType" } }, "required": [ "catalog_type" ] }, "CatalogsHotelFeedsUpdateRequest": { "type": "object", "title": "catalogs_feeds_update_request", "description": "Request object for updating a feed.", "additionalProperties": false, "properties": { "default_currency": { "$ref": "#/components/schemas/NullableCurrency" }, "name": { "description": "A human-friendly name associated to a given feed.", "type": "string" }, "format": { "$ref": "#/components/schemas/CatalogsFormat" }, "credentials": { "$ref": "#/components/schemas/CatalogsFeedCredentials" }, "location": { "type": "string", "pattern": "^(http|https|ftp|sftp)://", "description": "The URL where a feed is available for download. This URL is what Pinterest will use to download a feed for processing." }, "preferred_processing_schedule": { "$ref": "#/components/schemas/CatalogsFeedProcessingSchedule" }, "status": { "$ref": "#/components/schemas/CatalogsStatus" }, "catalog_type": { "$ref": "#/components/schemas/CatalogsType" } }, "required": [ "catalog_type" ] }, "CatalogsVerticalFeedsUpdateRequest": { "type": "object", "title": "feeds_update_request", "description": "Request object for updating a feed.", "oneOf": [ { "$ref": "#/components/schemas/CatalogsRetailFeedsUpdateRequest" }, { "$ref": "#/components/schemas/CatalogsHotelFeedsUpdateRequest" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailFeedsUpdateRequest", "HOTEL": "#/components/schemas/CatalogsHotelFeedsUpdateRequest" } } }, "CatalogsFeedsUpdateRequest": { "type": "object", "title": "legacy_retail_only", "description": "Request object for updating a feed.", "additionalProperties": false, "properties": { "default_availability": { "$ref": "#/components/schemas/ProductAvailabilityType" }, "default_currency": { "$ref": "#/components/schemas/NullableCurrency" }, "name": { "description": "A human-friendly name associated to a given feed.", "type": "string" }, "format": { "$ref": "#/components/schemas/CatalogsFormat" }, "credentials": { "$ref": "#/components/schemas/CatalogsFeedCredentials" }, "location": { "type": "string", "pattern": "^(http|https|ftp|sftp)://", "description": "The URL where a feed is available for download. This URL is what Pinterest will use to download a feed for processing." }, "preferred_processing_schedule": { "$ref": "#/components/schemas/CatalogsFeedProcessingSchedule" }, "status": { "$ref": "#/components/schemas/CatalogsStatus" } } }, "CatalogsFormat": { "description": "The file format of a feed.", "type": "string", "enum": [ "TSV", "CSV", "XML" ] }, "CatalogsItemValidationDetails": { "type": "object", "properties": { "attribute_name": { "$ref": "#/components/schemas/NullableCatalogsItemFieldType", "description": "Attribute that has a validation issue." }, "provided_value": { "type": "string", "nullable": true, "description": "Provided value that caused the validation issue." } }, "required": [ "attribute_name", "provided_value" ] }, "CatalogsItemValidationErrors": { "type": "object", "properties": { "ADULT_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an invalid adult value." }, "ADWORDS_FORMAT_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Adword link contains too many characters." }, "AVAILABILITY_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item is missing availability value in its product metadata, this item will not be published." }, "BLOCKLISTED_IMAGE_SIGNATURE": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item will not be published because it doesn't meet Pinterest's Merchant Guidelines." }, "DESCRIPTION_MISSING": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item is missing description in its product metadata, this item will not be published." }, "DUPLICATE_PRODUCTS": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "This product is duplicated. The duplicate entry will not be published." }, "IMAGE_LINK_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Image link is invalid." }, "IMAGE_LINK_LENGTH_TOO_LONG": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has image_link URL that contains too many characters, so the item will not be published." }, "IMAGE_LINK_MISSING": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item is missing an image link URL in its product metadata, this item will not be published." }, "INVALID_DOMAIN": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Product link value doesn't match the verified domain associated with this account." }, "ITEMID_MISSING": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item is missing item id in its product metadata, this item will not be published." }, "ITEM_MAIN_IMAGE_DOWNLOAD_FAILURE": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Main image can't be found." }, "LINK_FORMAT_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Link is invalid." }, "LINK_LENGTH_TOO_LONG": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Product link contains too many characters, this item will not be published." }, "LIST_PRICE_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has a list price formatting error, this item will not be published." }, "MAX_ITEMS_PER_ITEM_GROUP_EXCEEDED": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item exceed the maximum number of items per item group, this item will not be published." }, "PARSE_LINE_ERROR": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item contains formating errors." }, "PINJOIN_CONTENT_UNSAFE": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item will not be published because it doesn't meet Pinterest's Merchant Guidelines." }, "PRICE_CANNOT_BE_DETERMINED": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item price cannot be determined because the price, list price, and sale price are all different." }, "PRICE_MISSING": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Product is missing a price, this item will not be published." }, "PRODUCT_LINK_MISSING": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item is missing a link URL in its product metadata, this item will not be published." }, "PRODUCT_PRICE_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has a price formatting error in its product metadata, this item will not be published." }, "TITLE_MISSING": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item is missing title in its product metadata, this item will not be published." } } }, "CatalogsItemValidationIssue": { "type": "string", "enum": [ "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": { "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.", "example": 0, "type": "integer" }, "item_id": { "description": "The merchant-created unique ID that represents the product.", "example": "DS0294-L", "type": "string", "nullable": true }, "errors": { "$ref": "#/components/schemas/CatalogsItemValidationErrors" }, "warnings": { "$ref": "#/components/schemas/CatalogsItemValidationWarnings" } }, "required": [ "item_number", "item_id", "errors", "warnings" ] }, "CatalogsItemValidationWarnings": { "type": "object", "properties": { "AD_LINK_FORMAT_WARNING": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an ad link that is formatted incorrectly." }, "AD_LINK_SAME_AS_LINK": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an ad link URL that is duplicate of the link URL." }, "ADDITIONAL_IMAGE_LINK_LENGTH_TOO_LONG": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an additional_image_link URL that contains too many characters, so the item will not be published." }, "ADDITIONAL_IMAGE_LINK_WARNING": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has additional_image_link URLs that are formatted incorrectly and will not be published with your items." }, "ADWORDS_FORMAT_WARNING": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an adwords_redirect link that is formatted incorrectly." }, "ADWORDS_SAME_AS_LINK": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an adwords_redirect URL that is duplicate of the link URL." }, "AGE_GROUP_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an age group value that is formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences." }, "SIZE_SYSTEM_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Some items have size system values which are not one of the supported size systems." }, "ANDROID_DEEP_LINK_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item includes an invalid android_deep_link." }, "AVAILABILITY_DATE_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an availability_date value that is formatted incorrectly, this item will be published without an availability date." }, "COUNTRY_DOES_NOT_MAP_TO_CURRENCY": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item includes a currency that doesn't match the usual currency for the location where the product is sold or shipped." }, "CUSTOM_LABEL_LENGTH_TOO_LONG": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has a custom_label value that is too long, this item will be published without that custom label." }, "DESCRIPTION_LENGTH_TOO_LONG": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "The description for this item was truncated because it contains too many characters." }, "EXPIRATION_DATE_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an expiration_date value that is formatted incorrectly, this item will be published without an expiration date." }, "GENDER_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has a gender value that is formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences." }, "GTIN_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has a GTIN value that is formatted incorrectly." }, "IMAGE_LINK_WARNING": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an image_link URL that is formatted incorrectly and will not be published." }, "IOS_DEEP_LINK_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item includes an invalid ios_deep_link value." }, "IS_BUNDLE_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an is_bundle value that is formatted incorrectly, this item will be published without being bundled with other products." }, "ITEM_ADDITIONAL_IMAGE_DOWNLOAD_FAILURE": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item includes additional_image_links that can't be found." }, "LINK_FORMAT_WARNING": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an invalid product link which contains invalid UTM tracking paramaters." }, "MIN_AD_PRICE_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item includes a min_ad_price value that is formatted incorrectly." }, "MPN_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has a MPN value that is formatted incorrectly." }, "MULTIPACK_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an invalid multipack value." }, "OPTIONAL_CONDITION_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item includes a condition value that is formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences." }, "OPTIONAL_CONDITION_MISSING": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item is missing condition value, which may limit visibility in recommendations, search results and shopping experiences." }, "OPTIONAL_PRODUCT_CATEGORY_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item includes a google_product_category value that is not formatted correctly according to the GPC taxonomy." }, "OPTIONAL_PRODUCT_CATEGORY_MISSING": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item is missing google_product_category." }, "PRODUCT_CATEGORY_DEPTH_WARNING": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item only has 1 or 2 levels of google_product_category value, which may limit visibility in recommendations, search results and shopping experiences." }, "PRODUCT_TYPE_LENGTH_TOO_LONG": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has a product_type value that is too long, this item will be published without that product type." }, "SALES_PRICE_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an incorrectly formatted sales price." }, "SALES_PRICE_TOO_LOW": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has a sale price value that is discounted very low compared to the price." }, "SALES_PRICE_TOO_HIGH": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has a sale price value that is higher than the original price of the item." }, "SALE_DATE_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has a sale_price_effective_date value that is formatted incorrectly, this item will be published without a sale date." }, "SHIPPING_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has a shipping value that is formatted incorrectly." }, "SHIPPING_HEIGHT_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an incorrectly formatted shipping_height value. The value must first contain a numeric value then a valid dimension unit type." }, "SHIPPING_WEIGHT_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an invalid shipping_weight value." }, "SHIPPING_WIDTH_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an incorrectly formatted shipping_width value. The value must first contain a numeric value then a valid dimension unit type." }, "SIZE_TYPE_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has a size type value that is formatted incorrectly, which may limit visibility in recommendations, search results and shopping experiences." }, "TAX_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has a tax value that is formatted incorrectly." }, "TITLE_LENGTH_TOO_LONG": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "The title for the item was truncated because it contains too many characters." }, "TOO_MANY_ADDITIONAL_IMAGE_LINKS": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "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." }, "UTM_SOURCE_AUTO_CORRECTED": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item includes an utm_source value that is formatted incorrectly and has been automatically corrected." }, "WEIGHT_UNIT_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has a weight_unit value that is formatted incorrectly, this item will be published without a weight unit." } } }, "CatalogsItems": { "type": "object", "description": "Response object of catalogs items", "properties": { "items": { "type": "array", "description": "Array with catalogs items", "items": { "$ref": "#/components/schemas/ItemResponse" } } } }, "CatalogsItemsBatch": { "type": "object", "description": "Object describing the catalogs items batch", "properties": { "catalog_type": { "$ref": "#/components/schemas/CatalogsType" } }, "required": [ "catalog_type" ], "oneOf": [ { "$ref": "#/components/schemas/CatalogsRetailItemsBatch" }, { "$ref": "#/components/schemas/CatalogsHotelItemsBatch" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailItemsBatch", "HOTEL": "#/components/schemas/CatalogsHotelItemsBatch" } } }, "CatalogsItemsFilters": { "type": "object", "properties": { "catalog_type": { "$ref": "#/components/schemas/CatalogsType" } }, "required": [ "catalog_type" ], "oneOf": [ { "$ref": "#/components/schemas/CatalogsRetailItemsFilter" }, { "$ref": "#/components/schemas/CatalogsHotelItemsFilter" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailItemsFilter", "HOTEL": "#/components/schemas/CatalogsHotelItemsFilter" } } }, "CatalogsHotelItemsBatch": { "type": "object", "description": "Object describing the catalogs hotel items batch", "properties": { "batch_id": { "description": "Id of the catalogs items batch", "example": "595953100599279259-66753b9bb65c46c49bd8503b27fecf9e", "type": "string" }, "created_time": { "description": "Time of the batch creation: YYYY-MM-DD'T'hh:mm:ssTZD", "example": "2020-01-01T20:10:40-00:00", "type": "string", "format": "date-time", "readOnly": true }, "completed_time": { "description": "Time of the batch completion: YYYY-MM-DD'T'hh:mm:ssTZD", "example": "2022-03-10T15:37:10-00:00", "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "status": { "$ref": "#/components/schemas/BatchOperationStatus" }, "catalog_type": { "$ref": "#/components/schemas/CatalogsType" }, "items": { "description": "Array with the catalogs items processing records part of the catalogs items batch", "items": { "$ref": "#/components/schemas/HotelProcessingRecord" }, "type": "array" } }, "required": [ "catalog_type" ] }, "CatalogsRetailItemsBatch": { "type": "object", "description": "Object describing the catalogs retail items batch", "properties": { "batch_id": { "description": "Id of the catalogs items batch", "example": "595953100599279259-66753b9bb65c46c49bd8503b27fecf9e", "type": "string" }, "created_time": { "description": "Time of the batch creation: YYYY-MM-DD'T'hh:mm:ssTZD", "example": "2020-01-01T20:10:40-00:00", "type": "string", "format": "date-time", "readOnly": true }, "completed_time": { "description": "Time of the batch completion: YYYY-MM-DD'T'hh:mm:ssTZD", "example": "2022-03-10T15:37:10-00:00", "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "status": { "$ref": "#/components/schemas/BatchOperationStatus" }, "catalog_type": { "$ref": "#/components/schemas/CatalogsType" }, "items": { "description": "Array with the catalogs items processing records part of the catalogs items batch", "items": { "$ref": "#/components/schemas/ItemProcessingRecord" }, "type": "array" } }, "required": [ "catalog_type" ] }, "CatalogsItemsBatchRequest": { "type": "object", "title": "legacy_retail_only", "description": "Request object of catalogs items batch", "oneOf": [ { "$ref": "#/components/schemas/CatalogsItemsUpdateBatchRequest" }, { "$ref": "#/components/schemas/CatalogsItemsUpsertBatchRequest" }, { "$ref": "#/components/schemas/CatalogsItemsCreateBatchRequest" }, { "$ref": "#/components/schemas/CatalogsItemsDeleteDiscontinuedBatchRequest" }, { "$ref": "#/components/schemas/CatalogsItemsDeleteBatchRequest" } ], "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" } } }, "CatalogsItemsCreateBatchRequest": { "description": "Request object to create catalogs items", "type": "object", "additionalProperties": false, "properties": { "country": { "$ref": "#/components/schemas/Country" }, "language": { "$ref": "#/components/schemas/Language" }, "operation": { "$ref": "#/components/schemas/BatchOperation" }, "items": { "type": "array", "description": "Array with catalogs items", "items": { "$ref": "#/components/schemas/ItemCreateBatchRecord" }, "minItems": 1, "maxItems": 1000 } }, "required": [ "country", "language", "operation", "items" ] }, "CatalogsItemsDeleteBatchRequest": { "description": "Request object to delete catalogs items", "type": "object", "additionalProperties": false, "properties": { "country": { "$ref": "#/components/schemas/Country" }, "language": { "$ref": "#/components/schemas/Language" }, "operation": { "$ref": "#/components/schemas/BatchOperation" }, "items": { "type": "array", "description": "Array with catalogs items", "items": { "$ref": "#/components/schemas/ItemDeleteBatchRecord" } } }, "required": [ "country", "language", "operation", "items" ] }, "CatalogsItemsDeleteDiscontinuedBatchRequest": { "description": "Request object to discontinue catalogs items", "type": "object", "additionalProperties": false, "properties": { "country": { "$ref": "#/components/schemas/Country" }, "language": { "$ref": "#/components/schemas/Language" }, "operation": { "$ref": "#/components/schemas/BatchOperation" }, "items": { "type": "array", "description": "Array with catalogs items", "items": { "$ref": "#/components/schemas/ItemDeleteDiscontinuedBatchRecord" } } }, "required": [ "country", "language", "operation", "items" ] }, "CatalogsItemsUpdateBatchRequest": { "description": "Request object to update catalogs items", "type": "object", "additionalProperties": false, "properties": { "country": { "$ref": "#/components/schemas/Country" }, "language": { "$ref": "#/components/schemas/Language" }, "operation": { "$ref": "#/components/schemas/BatchOperation" }, "items": { "type": "array", "description": "Array with catalogs items", "items": { "$ref": "#/components/schemas/ItemUpdateBatchRecord" }, "minItems": 1, "maxItems": 1000 } }, "required": [ "country", "language", "operation", "items" ] }, "CatalogsItemsUpsertBatchRequest": { "description": "Request object to upsert catalogs items", "type": "object", "properties": { "country": { "$ref": "#/components/schemas/Country" }, "language": { "$ref": "#/components/schemas/Language" }, "operation": { "$ref": "#/components/schemas/BatchOperation" }, "items": { "type": "array", "description": "Array with catalogs items", "items": { "$ref": "#/components/schemas/ItemUpsertBatchRecord" }, "minItems": 1, "maxItems": 1000 } }, "required": [ "country", "language", "operation", "items" ] }, "CatalogsListProductsByFilterRequest": { "description": "Request object to list products for a given product group filter.", "type": "object", "oneOf": [ { "description": "Request object to list products for a given feed_id and product group filter.", "type": "object", "additionalProperties": false, "properties": { "feed_id": { "description": "Catalog Feed id pertaining to the catalog product group filter.", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" }, "filters": { "$ref": "#/components/schemas/CatalogsProductGroupFilters" } }, "required": [ "feed_id", "filters" ] } ] }, "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", "properties": { "metadata": { "$ref": "#/components/schemas/CatalogsProductMetadata" }, "pin": { "$ref": "#/components/schemas/Pin" } }, "required": [ "metadata", "pin" ] }, "CatalogsProductGroup": { "type": "object", "title": "feed_based_product_group", "description": "catalog product group entity", "properties": { "id": { "description": "ID of the catalog product group.", "example": "443727193917", "type": "string", "pattern": "^\\d+$" }, "name": { "description": "Name of catalog product group", "example": "Most Popular", "type": "string" }, "description": { "type": "string", "nullable": true }, "filters": { "$ref": "#/components/schemas/CatalogsProductGroupFilters" }, "is_featured": { "description": "boolean indicator of whether the product group is being featured or not", "type": "boolean" }, "type": { "$ref": "#/components/schemas/CatalogsProductGroupType" }, "status": { "$ref": "#/components/schemas/CatalogsProductGroupStatus" }, "created_at": { "description": "Unix timestamp in seconds of when catalog product group was created.", "example": 1621350033000, "type": "integer" }, "updated_at": { "description": "Unix timestamp in seconds of last time catalog product group was updated.", "example": 1622742155000, "type": "integer" }, "feed_id": { "description": "id of the catalogs feed belonging to this catalog product group", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" }, "catalog_type": { "type": "string", "enum": [ "RETAIL" ] } }, "required": [ "filters", "id", "feed_id" ] }, "CatalogsVerticalProductGroup": { "type": "object", "title": "catalog_based_product_group", "oneOf": [ { "$ref": "#/components/schemas/CatalogsHotelProductGroup" }, { "$ref": "#/components/schemas/CatalogsRetailProductGroup" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "HOTEL": "#/components/schemas/CatalogsHotelProductGroup", "RETAIL": "#/components/schemas/CatalogsRetailProductGroup" } } }, "CatalogsHotelProductGroup": { "type": "object", "title": "catalog_based_product_group", "properties": { "catalog_type": { "type": "string", "enum": [ "HOTEL" ] }, "id": { "description": "ID of the hotel product group.", "example": "443727193917", "type": "string", "pattern": "^\\d+$" }, "name": { "description": "Name of hotel product group", "example": "Most Popular", "type": "string" }, "description": { "type": "string", "nullable": true }, "filters": { "$ref": "#/components/schemas/CatalogsHotelProductGroupFilters" }, "created_at": { "description": "Unix timestamp in seconds of when catalog product group was created.", "example": 1621350033000, "type": "integer" }, "updated_at": { "description": "Unix timestamp in seconds of last time catalog product group was updated.", "example": 1622742155000, "type": "integer" }, "catalog_id": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "id", "filters", "catalog_type", "catalog_id" ] }, "CatalogsHotelProductGroupFilterKeys": { "title": "catalogs_product_group_keys", "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" } ] }, "CatalogsHotelProductGroupFilters": { "description": "Object holding a group of filters for a hotel product group", "title": "catalogs_product_group_filters", "type": "object", "anyOf": [ { "$ref": "#/components/schemas/CatalogsHotelProductGroupFiltersAnyOf" }, { "$ref": "#/components/schemas/CatalogsHotelProductGroupFiltersAllOf" } ] }, "CatalogsHotelProductGroupFiltersAllOf": { "type": "object", "additionalProperties": false, "properties": { "all_of": { "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/CatalogsHotelProductGroupFilterKeys" } } }, "required": [ "all_of" ] }, "CatalogsHotelProductGroupFiltersAnyOf": { "type": "object", "additionalProperties": false, "properties": { "any_of": { "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/CatalogsHotelProductGroupFilterKeys" } } }, "required": [ "any_of" ] }, "CatalogsRetailProductGroup": { "type": "object", "title": "catalog_based_product_group", "properties": { "catalog_type": { "type": "string", "enum": [ "RETAIL" ] }, "id": { "description": "ID of the catalog product group.", "example": "443727193917", "type": "string", "pattern": "^\\d+$" }, "name": { "description": "Name of catalog product group", "example": "Most Popular", "type": "string" }, "description": { "type": "string", "nullable": true }, "filters": { "$ref": "#/components/schemas/CatalogsProductGroupFilters" }, "is_featured": { "description": "boolean indicator of whether the product group is being featured or not", "type": "boolean" }, "type": { "$ref": "#/components/schemas/CatalogsProductGroupType" }, "status": { "$ref": "#/components/schemas/CatalogsProductGroupStatus" }, "created_at": { "description": "Unix timestamp in seconds of when catalog product group was created.", "example": 1621350033000, "type": "integer" }, "updated_at": { "description": "Unix timestamp in seconds of last time catalog product group was updated.", "example": 1622742155000, "type": "integer" }, "feed_id": { "example": null, "type": "string", "nullable": true, "enum": [ null ] } }, "required": [ "filters", "id", "feed_id", "catalog_type" ] }, "CatalogsHotelProductGroupCreateRequest": { "type": "object", "title": "hotel_product_groups_create_request", "additionalProperties": false, "description": "Request object for creating a hotel product group.", "properties": { "catalog_type": { "type": "string", "enum": [ "HOTEL" ] }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "filters": { "$ref": "#/components/schemas/CatalogsHotelProductGroupFilters" }, "catalog_id": { "description": "Catalog id pertaining to the hotel product group.", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" } }, "required": [ "name", "filters", "catalog_id", "catalog_type" ] }, "CatalogsHotelProductGroupUpdateRequest": { "type": "object", "title": "hotel_product_groups_update_request", "additionalProperties": false, "description": "Request object for updating a hotel product group.", "properties": { "catalog_type": { "type": "string", "enum": [ "HOTEL" ] }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "filters": { "$ref": "#/components/schemas/CatalogsHotelProductGroupFilters" } } }, "CatalogsProductGroupCreateRequest": { "type": "object", "title": "retail", "description": "Request object for creating a product group.", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_featured": { "description": "boolean indicator of whether the product group is being featured or not", "type": "boolean", "default": false }, "filters": { "$ref": "#/components/schemas/CatalogsProductGroupFiltersRequest" }, "feed_id": { "description": "Catalog Feed id pertaining to the catalog product group.", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" } }, "required": [ "name", "filters", "feed_id" ] }, "CatalogsProductGroupCurrencyCriteria": { "title": "catalogs_product_group_currency_criteria", "type": "object", "description": "A currency filter. This filter cannot be negated", "additionalProperties": false, "properties": { "values": { "$ref": "#/components/schemas/NonNullableCatalogsCurrency" }, "negated": { "type": "boolean", "default": false, "enum": [ false ] } }, "required": [ "values" ] }, "CatalogsProductGroupFilterKeys": { "title": "catalogs_product_group_keys", "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/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" } ] }, "CatalogsProductGroupFilters": { "description": "Object holding a group of filters for a catalog product group", "title": "catalogs_product_group_filters", "type": "object", "anyOf": [ { "$ref": "#/components/schemas/CatalogsProductGroupFiltersAnyOf" }, { "$ref": "#/components/schemas/CatalogsProductGroupFiltersAllOf" } ] }, "CatalogsProductGroupFiltersAllOf": { "type": "object", "additionalProperties": false, "properties": { "all_of": { "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupFilterKeys" } } }, "required": [ "all_of" ] }, "CatalogsProductGroupFiltersRequest": { "description": "Object holding a group of filters for request on catalog product group. This is a distinct schema It is not possible to create or update a Product Group with empty filters. But some automatically generated Product Groups might have empty filters.", "title": "catalogs_product_group_filters", "type": "object", "anyOf": [ { "type": "object", "additionalProperties": false, "properties": { "any_of": { "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupFilterKeys" }, "minItems": 1 } }, "required": [ "any_of" ] }, { "type": "object", "additionalProperties": false, "properties": { "all_of": { "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupFilterKeys" }, "minItems": 1 } }, "required": [ "all_of" ] } ] }, "CatalogsProductGroupFiltersAnyOf": { "type": "object", "additionalProperties": false, "properties": { "any_of": { "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupFilterKeys" } } }, "required": [ "any_of" ] }, "CatalogsProductGroupMultipleCountriesCriteria": { "title": "catalogs_product_group_multiple_country_criteria", "type": "object", "additionalProperties": false, "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/Country" } }, "negated": { "type": "boolean", "default": false } }, "required": [ "values" ] }, "CatalogsProductGroupMultipleGenderCriteria": { "title": "catalogs_product_group_multiple_gender_criteria", "type": "object", "additionalProperties": false, "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/Gender" } }, "negated": { "type": "boolean", "default": false } }, "required": [ "values" ] }, "CatalogsProductGroupMultipleStringCriteria": { "title": "catalogs_product_group_multiple_string_criteria", "type": "object", "additionalProperties": false, "properties": { "values": { "type": "array", "items": { "type": "string" } }, "negated": { "type": "boolean", "default": false } }, "required": [ "values" ] }, "CatalogsProductGroupMultipleStringListCriteria": { "title": "catalogs_product_group_multiple_string_list_criteria", "type": "object", "additionalProperties": false, "properties": { "values": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } }, "negated": { "type": "boolean", "default": false } }, "required": [ "values" ] }, "CatalogsProductGroupPricingCriteria": { "title": "catalogs_product_group_pricing_criteria", "type": "object", "additionalProperties": false, "properties": { "inclusion": { "type": "boolean", "default": true }, "values": { "type": "number", "minimum": 0 }, "negated": { "type": "boolean", "default": false } }, "required": [ "values" ] }, "CatalogsProductGroupProductCounts": { "title": "catalogs_product_group_product_counts", "description": "Product counts for a CatalogsProductGroup", "type": "object", "properties": { "in_stock": { "type": "number", "minimum": 0 }, "out_of_stock": { "type": "number", "minimum": 0 }, "preorder": { "type": "number", "minimum": 0 }, "total": { "type": "number", "minimum": 0 } }, "required": [ "in_stock", "out_of_stock", "preorder", "total" ] }, "CatalogsProductGroupStatus": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ] }, "CatalogsProductGroupType": { "type": "string", "title": "product_group_type", "description": "

Catalog product group type

\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_COLLECTION: Product groups created based on Shopify Product Collections.\n
I2PC: Product groups created based on predicted product category.

", "enum": [ "MERCHANT_CREATED", "ALL_PRODUCTS", "BEST_DEALS", "PINNER_FAVORITES", "TOP_SELLERS", "BACK_IN_STOCK", "NEW_ARRIVALS", "SHOPIFY_COLLECTIONS", "I2PC" ], "example": "TOP_SELLERS" }, "CatalogsProductGroupUpdateRequest": { "type": "object", "title": "retail", "description": "Request object for updating a product group.", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_featured": { "description": "boolean indicator of whether the product group is being featured or not", "type": "boolean" }, "filters": { "$ref": "#/components/schemas/CatalogsProductGroupFiltersRequest" } } }, "CatalogsProductMetadata": { "type": "object", "description": "Product metadata entity", "properties": { "item_id": { "description": "The user-created unique ID that represents the product.", "example": "DS0294-L", "type": "string" }, "item_group_id": { "description": "The parent ID of the product.", "example": "DS0294", "type": "string", "nullable": true }, "availability": { "$ref": "#/components/schemas/NonNullableProductAvailabilityType" }, "price": { "description": "The price of the product.", "example": 24.99, "type": "number" }, "sale_price": { "description": "The discounted price of the product.", "example": 14.99, "type": "number", "nullable": true }, "currency": { "$ref": "#/components/schemas/NonNullableCatalogsCurrency" } }, "required": [ "item_id", "item_group_id", "availability", "price", "sale_price", "currency" ] }, "CatalogsStatus": { "type": "string", "description": "Status for catalogs entities. Present in catalogs_feed values. When a feed is deleted, the response will inform DELETED as status.", "enum": [ "ACTIVE", "INACTIVE" ] }, "CatalogsType": { "description": "Type of the catalog entity.", "type": "string", "enum": [ "RETAIL", "HOTEL" ] }, "CatalogsVerticalBatchRequest": { "type": "object", "title": "operate on item batch", "description": "A request object that can have multiple operations on a single batch", "oneOf": [ { "$ref": "#/components/schemas/CatalogsRetailBatchRequest" }, { "$ref": "#/components/schemas/CatalogsHotelBatchRequest" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailBatchRequest", "HOTEL": "#/components/schemas/CatalogsHotelBatchRequest" } } }, "CatalogsHotelGuestRatings": { "type": "object", "description": "If specified, you must provide all properties", "properties": { "score": { "description": "Your hotel's rating.", "type": "number" }, "number_of_reviewers": { "description": "Total number of people who have rated this hotel.", "type": "integer" }, "max_score": { "description": "Max value for the hotel rating score.", "type": "number" }, "rating_system": { "description": "System you use for guest reviews.", "type": "string" } } }, "CatalogsHotelItemErrorResponse": { "type": "object", "description": "Object describing a hotel item error", "properties": { "catalog_type": { "$ref": "#/components/schemas/CatalogsType" }, "hotel_id": { "description": "The catalog hotel id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "errors": { "description": "Array with the errors for the item id requested", "items": { "$ref": "#/components/schemas/ItemValidationEvent" }, "type": "array" } }, "required": [ "catalog_type" ] }, "CatalogsHotelItemResponse": { "type": "object", "description": "Object describing a hotel record", "properties": { "catalog_type": { "$ref": "#/components/schemas/CatalogsType" }, "hotel_id": { "description": "The catalog hotel id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "pins": { "description": "The pins mapped to the item", "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Pin" }, "maxItems": 11 }, "attributes": { "$ref": "#/components/schemas/CatalogsHotelAttributes" } }, "required": [ "catalog_type" ] }, "CatalogsRetailBatchRequest": { "type": "object", "description": "A request object that can have multiple operations on a single retail batch", "additionalProperties": false, "properties": { "catalog_type": { "$ref": "#/components/schemas/CatalogsType" }, "country": { "$ref": "#/components/schemas/Country" }, "language": { "$ref": "#/components/schemas/Language" }, "items": { "minItems": 1, "maxItems": 1000, "type": "array", "description": "Array with catalogs item operations", "items": { "anyOf": [ { "$ref": "#/components/schemas/CatalogsCreateRetailItem" }, { "$ref": "#/components/schemas/CatalogsUpdateRetailItem" }, { "$ref": "#/components/schemas/CatalogsUpsertRetailItem" }, { "$ref": "#/components/schemas/CatalogsDeleteRetailItem" } ], "discriminator": { "propertyName": "operation", "mapping": { "CREATE": "#/components/schemas/CatalogsCreateRetailItem", "UPDATE": "#/components/schemas/CatalogsUpdateRetailItem", "UPSERT": "#/components/schemas/CatalogsUpsertRetailItem", "DELETE": "#/components/schemas/CatalogsDeleteRetailItem" } } } } }, "required": [ "catalog_type", "country", "language", "items" ] }, "CatalogsRetailItemErrorResponse": { "type": "object", "description": "Object describing a retail item error", "properties": { "catalog_type": { "$ref": "#/components/schemas/CatalogsType" }, "item_id": { "description": "The catalog item id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "errors": { "description": "Array with the errors for the item id requested", "items": { "$ref": "#/components/schemas/ItemValidationEvent" }, "type": "array" } }, "required": [ "catalog_type" ] }, "CatalogsRetailItemResponse": { "type": "object", "description": "Object describing a retail item record", "properties": { "catalog_type": { "$ref": "#/components/schemas/CatalogsType" }, "item_id": { "description": "The catalog retail item id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "pins": { "description": "The pins mapped to the item", "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Pin" }, "maxItems": 11 }, "attributes": { "$ref": "#/components/schemas/ItemAttributes" } }, "required": [ "catalog_type" ] }, "CatalogsCreateRetailItem": { "type": "object", "description": "An item to be created", "properties": { "item_id": { "description": "The catalog item id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "operation": { "type": "string", "enum": [ "CREATE", "UPDATE", "UPSERT", "DELETE" ] }, "attributes": { "$ref": "#/components/schemas/ItemAttributes" } }, "required": [ "item_id", "operation", "attributes" ] }, "CatalogsUpdateRetailItem": { "type": "object", "description": "An item to be updated", "properties": { "item_id": { "description": "The catalog item id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "operation": { "type": "string", "enum": [ "CREATE", "UPDATE", "UPSERT", "DELETE" ] }, "attributes": { "$ref": "#/components/schemas/UpdatableItemAttributes" }, "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.", "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" ], "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/UpdateMaskFieldType" } } }, "required": [ "item_id", "operation", "attributes" ] }, "CatalogsUpsertRetailItem": { "type": "object", "description": "An item to be upserted", "properties": { "item_id": { "description": "The catalog item id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "operation": { "type": "string", "enum": [ "CREATE", "UPDATE", "UPSERT", "DELETE" ] }, "attributes": { "$ref": "#/components/schemas/ItemAttributes" } }, "required": [ "item_id", "operation", "attributes" ] }, "CatalogsDeleteRetailItem": { "type": "object", "description": "An item to be deleted", "properties": { "item_id": { "description": "The catalog item id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "operation": { "type": "string", "enum": [ "CREATE", "UPDATE", "UPSERT", "DELETE" ] } }, "required": [ "item_id", "operation" ] }, "CatalogsHotelBatchRequest": { "description": "Request object to update catalogs hotel items", "type": "object", "additionalProperties": false, "properties": { "catalog_type": { "$ref": "#/components/schemas/CatalogsType" }, "country": { "$ref": "#/components/schemas/Country" }, "language": { "$ref": "#/components/schemas/Language" }, "items": { "minItems": 1, "maxItems": 1000, "type": "array", "description": "Array with catalogs item operations", "items": { "$ref": "#/components/schemas/CatalogsHotelBatchItem" } }, "catalog_id": { "description": "Catalog id pertaining to the hotel item. If not provided, default to oldest hotel catalog", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" } }, "required": [ "catalog_type", "country", "language", "items" ] }, "CatalogsDeleteHotelItem": { "type": "object", "description": "A hotel item to be deleted", "properties": { "hotel_id": { "description": "The catalog hotel id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "operation": { "type": "string", "enum": [ "DELETE" ] } }, "required": [ "hotel_id", "operation" ] }, "CatalogsCreateHotelItem": { "type": "object", "description": "A hotel item to be created.", "properties": { "hotel_id": { "description": "The catalog hotel id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "operation": { "type": "string", "enum": [ "CREATE" ] }, "attributes": { "$ref": "#/components/schemas/CatalogsHotelAttributes" } }, "required": [ "hotel_id", "operation", "attributes" ] }, "CatalogsUpdateHotelItem": { "type": "object", "description": "Object describing an hotel item batch record", "properties": { "hotel_id": { "description": "The catalog hotel item id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "operation": { "type": "string", "enum": [ "UPDATE" ] }, "attributes": { "$ref": "#/components/schemas/CatalogsUpdatableHotelAttributes" } }, "required": [ "hotel_id", "operation", "attributes" ] }, "CatalogsUpsertHotelItem": { "type": "object", "description": "A hotel item to be upserted.", "properties": { "hotel_id": { "description": "The catalog hotel id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "operation": { "type": "string", "enum": [ "UPSERT" ] }, "attributes": { "$ref": "#/components/schemas/CatalogsHotelAttributes" } }, "required": [ "hotel_id", "operation", "attributes" ] }, "CatalogsHotelAddress": { "type": "object", "properties": { "addr1": { "description": "Primary street address of hotel.", "type": "string" }, "city": { "description": "City where the hotel is located.", "type": "string" }, "region": { "description": "State, county, province, 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" } } }, "CatalogsUpdatableHotelAttributes": { "type": "object", "properties": { "name": { "description": "The hotel's name.", "type": "string", "nullable": true }, "link": { "description": "Link to the product page", "type": "string", "nullable": true }, "description": { "description": "Brief description of the hotel.", "type": "string", "nullable": true }, "brand": { "description": "The brand to which this hotel belongs to.", "type": "string", "nullable": true }, "latitude": { "description": "Latitude of the hotel.", "type": "number" }, "longitude": { "description": "Longitude of the hotel.", "type": "number", "nullable": true }, "neighborhood": { "description": "A list of neighborhoods where the hotel is located", "type": "array", "nullable": true, "items": { "type": "string" } }, "address": { "description": "Hotel address", "$ref": "#/components/schemas/CatalogsHotelAddress" }, "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 }, "category": { "description": "The type of property. The category can be any type of internal description desired.", "type": "string", "nullable": true }, "base_price": { "description": "Base price of the hotel room per night followed by the ISO currency code", "type": "string", "nullable": true, "example": "100 USD" }, "sale_price": { "description": "Sale price of a hotel room per night. Used to advertise discounts off the regular price of the hotel.", "type": "string", "nullable": true, "example": "90 USD" }, "guest_ratings": { "description": "If specified, you must provide all properties", "$ref": "#/components/schemas/CatalogsHotelGuestRatings" } } }, "CatalogsVerticalProductGroupCreateRequest": { "type": "object", "title": "hotel", "description": "Request object for creating a hotel product group.", "oneOf": [ { "$ref": "#/components/schemas/CatalogsHotelProductGroupCreateRequest" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "HOTEL": "#/components/schemas/CatalogsHotelProductGroupCreateRequest" } } }, "CatalogsVerticalProductGroupUpdateRequest": { "type": "object", "title": "hotel", "description": "Request object for updating a hotel product group.", "oneOf": [ { "$ref": "#/components/schemas/CatalogsHotelProductGroupUpdateRequest" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "HOTEL": "#/components/schemas/CatalogsHotelProductGroupUpdateRequest" } } }, "ConditionFilter": { "type": "object", "additionalProperties": false, "properties": { "CONDITION": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringCriteria" } }, "required": [ "CONDITION" ] }, "ConversionApiResponse": { "description": "Schema describing the object in the response, which contains information about the events that were received and processed.", "type": "object", "properties": { "num_events_received": { "description": "Total number of events received in the request.", "type": "integer" }, "num_events_processed": { "description": "Number of events that were successfully processed from the events.", "type": "integer" }, "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": { "type": "object", "properties": { "status": { "description": "Whether the event was processed successfully.", "type": "string", "example": "processed", "enum": [ "failed", "processed" ] }, "error_message": { "description": "Error message containing more information about why the event failed to be processed.", "type": "string", "nullable": true }, "warning_message": { "description": "Warning messages about any fields in the event which are not standard. These are not critical to event processing.", "type": "string", "nullable": true } }, "required": [ "status" ] } } }, "required": [ "num_events_received", "num_events_processed", "events" ] }, "ConversionAttributionWindowDays": { "type": "integer", "enum": [ 0, 1, 7, 14, 30, 60 ] }, "ConversionEventResponse": { "title": "ConversionEventResponse", "type": "object", "properties": { "conversion_event": { "type": "string", "$ref": "#/components/schemas/ConversionTagType" }, "conversion_tag_id": { "title": "conversion_tag_id", "description": "Id of the tag.", "type": "string", "pattern": "^\\d+$", "example": "2614324385652" }, "ad_account_id": { "title": "ad_account_id", "description": "Id of the ad account.", "type": "string", "pattern": "^\\d+$", "example": "549757463328" }, "created_time": { "title": "created_time", "description": "Creation date in epoch format.", "type": "integer", "example": 1564768710 } } }, "ConversionEvents": { "description": "A list of events (one or more) encapsulated by a data object.", "type": "object", "additionalProperties": false, "properties": { "data": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "object", "additionalProperties": false, "properties": { "event_name": { "description": "The type of the user event. Please use the right event_name otherwise the event won’t be accepted and show up correctly in reports.
  • add_to_cart
  • checkout
  • custom
  • lead
  • page_visit
  • search
  • signup
  • view_category
  • watch_video", "type": "string", "example": "checkout" }, "action_source": { "description": "The source indicating where the conversion event occurred.
  • app_android
  • app_ios
  • web
  • offline", "type": "string", "example": "app_ios" }, "event_time": { "description": "The time when the event happened. Unix timestamp in seconds.", "example": 1451431341, "type": "integer", "format": "int64" }, "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", "example": "eventId0001" }, "event_source_url": { "description": "URL of the web conversion event.", "type": "string", "example": "https://www.my-clothing-shop.org/", "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", "example": false }, "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", "example": "ss-partnername", "nullable": true }, "user_data": { "$ref": "#/components/schemas/ConversionEventsUserData" }, "custom_data": { "description": "Object containing other custom data.", "type": "object", "additionalProperties": false, "properties": { "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.", "example": "USD", "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.", "example": "72.39", "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 (Install the Pinterest tag section).", "type": "array", "items": { "type": "string" }, "example": [ "red-pinterest-shirt-logo-1", "purple-pinterest-shirt-logo-3" ] }, "content_name": { "description": "The name of the page or product associated with the event.", "type": "string", "nullable": true, "example": "pinterest-themed-clothing" }, "content_category": { "description": "The category of the content associated with the event.", "type": "string", "nullable": true, "example": "shirts" }, "content_brand": { "description": "The brand of the content associated with the event.", "type": "string", "nullable": true, "example": "pinterest-brand" }, "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 (Install the Pinterest tag section).", "type": "array", "items": { "type": "object", "additionalProperties": false, "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 (Install the Pinterest tag section).", "example": "red-pinterest-shirt-logo-1", "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 (Install the Pinterest tag section).", "example": "1325.12", "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 (Install the Pinterest tag section).", "type": "integer", "format": "int64", "example": 5 }, "item_name": { "description": "The name of a product.", "example": "pinterest-clothing-shirt", "type": "string" }, "item_category": { "description": "The category of a product.", "example": "pinterest-entertainment", "type": "string" }, "item_brand": { "description": "The brand of a product.", "example": "pinterest", "type": "string" } } } }, "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 (Install the Pinterest tag section).", "type": "integer", "format": "int64", "example": 2 }, "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, "example": "my_order_id" }, "search_string": { "description": "The search string related to the user conversion event.", "type": "string", "nullable": true, "example": "sample string" }, "opt_out_type": { "description": "Flags for different privacy rights laws to opt out users of sharing personal information. Values should be comma separated. Please follow the Help Center and dev site for specific opt_out_type set up.", "example": "LDP", "type": "string", "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, "example": "ss-company" } } }, "app_id": { "description": "The app store app ID.", "type": "string", "nullable": true, "example": "429047995" }, "app_name": { "description": "Name of the app.", "type": "string", "nullable": true, "example": "Pinterest" }, "app_version": { "description": "Version of the app.", "type": "string", "nullable": true, "example": "7.9" }, "device_brand": { "description": "Brand of the user device.", "type": "string", "nullable": true, "example": "Apple" }, "device_carrier": { "description": "User device's mobile carrier.", "type": "string", "nullable": true, "example": "T-Mobile" }, "device_model": { "description": "Model of the user device.", "type": "string", "nullable": true, "example": "iPhone X" }, "device_type": { "description": "Type of the user device.", "type": "string", "nullable": true, "example": "iPhone" }, "os_version": { "description": "Version of the device operating system.", "type": "string", "nullable": true, "example": "12.1.4" }, "wifi": { "description": "Whether the event occurred when the user device was connected to wifi.", "example": false, "type": "boolean" }, "language": { "description": "Two-character ISO-639-1 language code indicating the user's language.", "example": "en", "type": "string", "nullable": true } }, "required": [ "event_name", "action_source", "event_time", "user_data", "event_id" ] } } }, "required": [ "data" ] }, "ConversionEventsUserData": { "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.", "type": "object", "anyOf": [ { "properties": { "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.", "type": "array", "items": { "type": "string" }, "example": [ "411e44ce1261728ffd2c0686e44e3fffe413c0e2c5adc498bc7da883d476b9c8", "09831ea51bd1b7b32a836683a00a9ccaf3d05f59499f42d9883412ed79289969" ] }, "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.", "type": "array", "items": { "type": "string" }, "example": [ "0192518eb84137ccfe82c8b6322d29631dae7e28ed9d0f6dd5f245d73a58c5f1", "837b850ac46d62b2272a71de73c27801ff011ac1e36c5432620c8755cf90db46" ] }, "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", "example": "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" } }, "required": [ "em" ] }, { "properties": { "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.", "type": "array", "items": { "type": "string" }, "example": [ "411e44ce1261728ffd2c0686e44e3fffe413c0e2c5adc498bc7da883d476b9c8", "09831ea51bd1b7b32a836683a00a9ccaf3d05f59499f42d9883412ed79289969" ] }, "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.", "type": "array", "items": { "type": "string" }, "example": [ "0192518eb84137ccfe82c8b6322d29631dae7e28ed9d0f6dd5f245d73a58c5f1", "837b850ac46d62b2272a71de73c27801ff011ac1e36c5432620c8755cf90db46" ] }, "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", "example": "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" } }, "required": [ "hashed_maids" ] }, { "properties": { "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.", "type": "array", "items": { "type": "string" }, "example": [ "411e44ce1261728ffd2c0686e44e3fffe413c0e2c5adc498bc7da883d476b9c8", "09831ea51bd1b7b32a836683a00a9ccaf3d05f59499f42d9883412ed79289969" ] }, "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.", "type": "array", "items": { "type": "string" }, "example": [ "0192518eb84137ccfe82c8b6322d29631dae7e28ed9d0f6dd5f245d73a58c5f1", "837b850ac46d62b2272a71de73c27801ff011ac1e36c5432620c8755cf90db46" ] }, "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", "example": "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" } }, "required": [ "client_ip_address", "client_user_agent" ] } ], "properties": { "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.", "type": "array", "items": { "type": "string" }, "example": [ "45df139772a81b6011bdc1c9cc3d1cb408fc0b10ec0c5cb9d4d4e107f0ddc49d" ] }, "ge": { "description": "Sha256 hashes of user's gender, in lowercase. Either \"f\" or \"m\" or \"n\" for non-binary gender.", "type": "array", "items": { "type": "string" }, "example": [ "0d248e82c62c9386878327d491c762a002152d42ab2c391a31c44d9f62675ddf" ] }, "db": { "description": "Sha256 hashes of user's date of birthday, given as year, month, and day.", "type": "array", "items": { "type": "string" }, "example": [ "d4426a0086d10f12ad265539ae8d54221dc67786053d511407204b76e99d7739" ] }, "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.", "type": "array", "items": { "type": "string" }, "example": [ "7e546b3aa43f989dd359672e6c3409d4f9d4e8f155ae1e9b90ee060985468c19" ] }, "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.", "type": "array", "items": { "type": "string" }, "example": [ "ec1e6a072231703f1bc41429052fff8c00a7e0c6aaec2e7107241ca8f3ceb6b2" ] }, "ct": { "description": "Sha256 hashes of user's city, in lowercase, and without spaces or punctuation. User residency city (mostly billing).", "type": "array", "items": { "type": "string" }, "example": [ "4ac01a129bfd10385c9278c2cf2c46fac5ab57350841234f587c8522a2e4ce36" ] }, "st": { "description": "Sha256 hashes of user's state, given as a two-letter code in lowercase. User residency state (mostly billing).", "type": "array", "items": { "type": "string" }, "example": [ "49a6d05b8e4b516656e464271d9dd38d0a7e0142f7f49546f4dabd2720cafc34" ] }, "zp": { "description": "Sha256 hashes of user's zipcode, only digits. User residency zipcode (mostly billing).", "type": "array", "items": { "type": "string" }, "example": [ "fd5f56b40a79a385708428e7b32ab996a681080a166a2206e750eb4819186145" ] }, "country": { "description": "Sha256 hashes of two-character ISO-3166 country code indicating the user's country, in lowercase.", "type": "array", "items": { "type": "string" }, "example": [ "9b202ecbc6d45c6d8901d989a918878397a3eb9d00e8f48022fc051b19d21a1d" ] }, "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.", "type": "array", "items": { "type": "string" }, "example": [ "6a7a73766627eb611720883d5a11cc62b5bfee237b00a6658d78c50032ec4aee" ] }, "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 }, "partner_id": { "description": "A unique identifier of visitors' information defined by third party partners. e.g RampID", "type": "string", "example": "BUJrTlRRzGJmWhRXFZdkioV6wKPBve7Lom__GU9J74hq2NIQj4O3nOZJrp3mcUr5MptkXsI14juMOIM9mNZnM4zEUFT2JLVaFhcOfuuWz3IWEDtBf6I0DPc", "nullable": true } } }, "ConversionReportAttributionType": { "type": "string", "description": "Attribution type. Refers to the Pinterest Tag endpoints", "example": "INDIVIDUAL", "enum": [ "INDIVIDUAL", "HOUSEHOLD" ] }, "ConversionReportTimeType": { "type": "string", "description": "Conversion report time type", "example": "TIME_OF_AD_ACTION", "enum": [ "TIME_OF_AD_ACTION", "TIME_OF_CONVERSION" ] }, "ConversionTagCommon": { "type": "object", "properties": { "ad_account_id": { "description": "Ad account ID.", "example": "549755885175", "title": "ad_account_id", "type": "string" }, "code_snippet": { "description": "Tag code snippet.", "example": "