{ "openapi": "3.0.3", "info": { "version": "5.14.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": "advanced_auction", "description": "View, create, or update advanced auction item bid options." }, { "name": "audience_insights", "description": "View audience insights." }, { "name": "audience_sharing", "description": "View, share, or revoke shared audiences.
\nAudience Sharing endpoints are not available to all apps,\nif you are interested in using them, reach out to us on our help center page.\nLearn more." }, { "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": "leads_export", "description": "Create and export leads information from lead ads." }, { "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": "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": "targeting_template", "description": "View, create or update targeting templates." }, { "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." } ], "x-tagGroups": [ { "name": "Pin and Boards", "tags": [ "pins", "boards", "media", "aggregated_comments", "aggregated_pin_data", "user_account" ] }, { "name": "Campaign Management", "tags": [ "ad_accounts", "campaigns", "ad_groups", "ads", "product_group_promotions", "bulk" ] }, { "name": "Targeting", "tags": [ "audiences", "customer_lists", "keywords", "targeting_template", "audience_insights", "audience_sharing" ] }, { "name": "Ad Formats", "tags": [ "lead_forms", "lead_ads", "leads_export" ] }, { "name": "Billing", "tags": [ "billing", "order_lines", "terms_of_service" ] }, { "name": "Business Access", "tags": [ "business_access_assets", "business_access_invite", "business_access_relationships" ] }, { "name": "Conversions", "tags": [ "conversion_events", "conversion_tags" ] }, { "name": "Others", "tags": [ "advanced_auction", "integrations", "oauth", "resources", "search", "terms" ] }, { "name": "Shopping", "tags": [ "catalogs" ] } ], "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" }, { "type": "object", "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" }, { "type": "object", "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": { "post": { "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. Collection ads are not currently supported ad preview.", "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" }, { "type": "object", "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- The request must contain either ad_ids or both campaign_ids and pin_ids.\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" }, { "$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" }, { "name": "pin_ids", "description": "List of Pin IDs.", "in": "query", "required": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, { "$ref": "#/components/parameters/query_campaign_ids" } ], "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" }, { "type": "object", "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_ad_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": "Filter 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" }, { "type": "object", "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/{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}/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/shared/accounts": { "get": { "summary": "List accounts with access to an audience owned by an ad account", "description": "List all ad accounts and/or businesses that have access to a specific audience. The audience must be owned by the requesting ad account.", "operationId": "ad_accounts_audiences_shared_accounts/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_audience_id" }, { "$ref": "#/components/parameters/query_account_type" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SharedAudienceAccount" } } } } ] } } } }, "400": { "description": "Invalid ad account audiences shared accounts parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account audiences shared accounts parameters." } } } }, "404": { "description": "Shared accounts not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "audience_sharing" ] } }, "/ad_accounts/{ad_account_id}/audiences/ad_accounts/shared": { "patch": { "summary": "Update audience sharing between ad accounts", "description": "From an ad account, share a specific audience with another ad account, or revoke access to a previously shared audience. Only the audience owner account can share the audience. The recipient ad account(s) must be in the same Pinterest Business Hierarchy as the business owner of the ad account.
This endpoint is not available to all apps.Learn more.", "operationId": "update_ad_account_to_ad_account_shared_audience", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedAudience" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedAudienceResponse" } } }, "description": "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": [ "audience_sharing" ] } }, "/ad_accounts/{ad_account_id}/audiences/businesses/shared": { "patch": { "summary": "Update audience sharing from an ad account to businesses", "description": "From an ad account, share a specific audience with a business account, or revoke access to a previously shared audience. Only the audience owner account can share the audience. The recipient business account must be in the same business hierarchy as the business owner of the ad account.
This endpoint is not available to all apps.Learn more.", "operationId": "update_ad_account_to_business_shared_audience", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessSharedAudience" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessSharedAudienceResponse" } } }, "description": "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": [ "audience_sharing" ] } }, "/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" }, { "type": "object", "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" }, { "type": "object", "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_campaign_targeting_types" }, { "$ref": "#/components/parameters/query_columns" }, { "$ref": "#/components/parameters/query_granularity" }, { "$ref": "#/components/parameters/query_conversion_attribution_click_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_engagement_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_view_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_conversion_report_time" }, { "$ref": "#/components/parameters/query_attribution_types" } ], "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" }, { "type": "object", "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" }, { "type": "object", "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\n to 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. (Note that the authorization header required is Authorization: Bearer <access_token>).\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" }, { "type": "object", "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": "List lead forms", "description": "This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.\n\nList lead forms associated with an ad account ID.\n\nFor more, see Lead ads.", "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" }, { "type": "object", "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" ] }, "post": { "x-sandbox": "disabled", "description": "This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.\n\nCreate lead forms. Lead forms are used in lead ads and allow you to control what text appears on the lead form’ s description, questions and confirmation sections.\n\nFor more, see Lead ads.", "summary": "Create lead forms", "operationId": "lead_forms/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/LeadFormCreateRequest" }, "maxItems": 30, "minItems": 1, "type": "array" } } }, "description": "List of lead forms to create, size limit [1, 30].", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadFormArrayResponse" } } }, "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" ] }, "patch": { "x-sandbox": "disabled", "description": "This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.\n\nUpdate lead forms. Lead ads help you reach people who are actively looking for, and interested in, your goods and services. The lead form can be associated with an ad to allow people to fill out the form.\n\nFor more, see Lead ads.", "summary": "Update lead forms", "operationId": "lead_forms/update", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "items": { "$ref": "#/components/schemas/LeadFormUpdateRequest" }, "maxItems": 30, "minItems": 1, "type": "array" } } }, "description": "List of lead forms to update, size limit [1, 30].", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadFormArrayResponse" } } }, "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": "This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.\n\nGets a lead form given it's ID. It must also be associated with the provided ad account ID.\n\nFor more, see Lead ads.", "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.\nSubscriptions allow Pinterest to deliver lead data from Ads Manager directly to the subscriber. Subscriptions can exist for a specific lead form or at ad account level.\n- Only requests for the OWNER or ADMIN of the ad_account will be allowed.\n- Advertisers can set up multiple integrations using ad_account_id + lead_form_id but only one integration per unique records.\n- For data security, egress lead data is encrypted with AES-256-GCM.\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" }, { "type": "object", "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}/leads_export": { "post": { "x-sandbox": "disabled", "description": "This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.\n\nCreate an export of leads collected from a lead ad. This returns a lead_export_id token that you can use to download the export when it is ready.\n\nNote: Lead ad data will be available up to 30 days after the lead has been submitted.\n\nFor more, see Lead ads.", "summary": "Create a request to export leads collected from a lead ad", "operationId": "leads_export/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/LeadsExportCreateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadsExportCreateResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account parameter." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "leads_export" ] } }, "/ad_accounts/{ad_account_id}/leads_export/{leads_export_id}": { "get": { "x-sandbox": "disabled", "description": "This feature is currently in beta and not available to all apps, if you're interested in joining the beta, please reach out to your Pinterest account manager.\n\nGet the export of leads collected from a lead ad. This returns a URL to a list of lead export given a lead_export_id token returned from the create a lead export call. You can use the URL to download the report.\n\nNote: Lead ad data will be available up to 30 days after the lead has been submitted.\n\nFor more, see Lead ads.", "summary": "Get the lead export from the lead export create call", "operationId": "leads_export/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "name": "leads_export_id", "in": "path", "description": "lead_export_id token returned from the create a lead export endpoint", "example": "123755885175", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadsExportResponseData" } } }, "description": "Success" }, "400": { "description": "Invalid ad account parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account parameter." } } } }, "404": { "description": "Invalid leads export id parameter.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Invalid leads export id parameter." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "leads_export" ] } }, "/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" }, { "type": "object", "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" }, { "type": "object", "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}/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 /docs/developer-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" }, { "type": "object", "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" }, { "type": "object", "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}/targeting_templates": { "get": { "summary": "List targeting templates", "description": "Get a list of the targeting templates in the specified ad_account_id", "operationId": "targeting_template/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_order" }, { "in": "query", "description": "Include audience sizing in result or not", "name": "include_sizing", "required": false, "schema": { "type": "boolean", "default": false } }, { "description": "Search keyword for targeting templates", "in": "query", "name": "search_query", "example": "gaming", "required": false, "schema": { "type": "string" } }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/TargetingTemplateResponseData" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid ad account id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account id" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "targeting_template" ] }, "post": { "summary": "Create targeting templates", "description": "

Targeting templates allow advertisers to save a set of targeting details including audience lists,\n keywords & interest, demographics, and placements to use more than once during the campaign creation process.

\n

Templates can be used to build out basic targeting criteria that you plan to use across campaigns and to reuse\n performance targeting from prior campaigns for new campaigns.

", "operationId": "targeting_template/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "description": "targeting template creation entity", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetingTemplateCreate" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetingTemplateGetResponseData" } } }, "description": "Success" }, "400": { "description": "Invalid ad account id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account id" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "targeting_template" ] }, "patch": { "summary": "Update targeting templates", "description": "

Update the targeting template given advertiser ID and targeting template ID

", "operationId": "targeting_template/update", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "description": "Operation type and targeting template ID", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetingTemplateUpdateRequest" } } } }, "responses": { "200": { "description": "Success" }, "400": { "description": "Invalid ad account id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account id" } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "targeting_template" ] } }, "/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" }, { "type": "object", "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" ] } }, "/advanced_auction/items/get": { "post": { "summary": "Get item bid options (POST)", "description": "Get the bid options for a batch of retail catalog items.\n\nThe catalog must be owned by the \"operation user_account\". See detailed documentation here. 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`.\n\nThis endpoint is not available to all users.", "operationId": "advanced_auction_items_get/post", "x-ratelimit-category": "advanced_auction_read", "x-sandbox": "enabled", "security": [ { "pinterest_oauth2": [ "ads:read", "catalogs:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "description": "Request object used to get bid options values for a batch of retail catalog items", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvancedAuctionItemsGetRequest" } } } }, "responses": { "200": { "description": "Response containing the bid option values for the requested retail catalog items. Items that don't exist or do not have bid options set won't be present in the response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvancedAuctionItems" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "Invalid request: {'catalog_id': '1234'} list of retail catalog items not provided" } } } } } }, "401": { "description": "Not authenticated to get item bid options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthenticatedAccess": { "value": { "code": 2, "message": "Authentication failed." } } } } } }, "403": { "description": "Not authorized to get item bid options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "advanced_auction" ] } }, "/advanced_auction/items/submit": { "post": { "summary": "Operate on item level bid options", "description": "This endpoint supports multiple operations on a set of one or more bid options (bid price and bid adjustments for targeting categories) for retail catalog items. These advanced auction settings are applied in campaigns using objective_type `CATALOG_SALES` and ad groups using bid_strategy_type `MAX_BID`.\n\nThe catalog must be owned by the \"operation user_account\". See detailed documentation here. 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`.\n\nThis endpoint is not available to all users.", "operationId": "advanced_auction_items_submit/post", "x-ratelimit-category": "advanced_auction_write", "x-sandbox": "enabled", "security": [ { "pinterest_oauth2": [ "ads:write", "catalogs:read" ] } ], "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "description": "Request object used to upsert or delete bid options for a batch of retail catalog items", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvancedAuctionItemsSubmitRequest" } } } }, "responses": { "200": { "description": "Response containing the results of the item bid options operations", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdvancedAuctionProcessedItems" } } } }, "400": { "description": "Invalid request parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "Invalid request: {'catalog_id': '1234'} list of item bid option operations not provided" } } } } } }, "401": { "description": "Not authenticated to post item bid options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthenticatedAccess": { "value": { "code": 2, "message": "Authentication failed." } } } } } }, "403": { "description": "Not authorized to post item bid options", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "advanced_auction" ] } }, "/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" ] }, { "client_credentials": [ "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" }, { "type": "object", "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" ] }, { "client_credentials": [ "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# /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# /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# /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# /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# /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# /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# /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# /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# /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" ] }, { "client_credentials": [ "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" }, { "type": "object", "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" ] }, { "client_credentials": [ "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" }, { "type": "object", "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" ] }, { "client_credentials": [ "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" }, { "type": "object", "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" } } } } } } }, "/businesses/employers": { "get": { "summary": "List business employers for user", "description": "Get all of the viewing user's business employers.", "operationId": "get/business_employers", "security": [ { "pinterest_oauth2": [ "biz_access:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "items": { "type": "array", "description": "List of employers.", "items": { "$ref": "#/components/schemas/UserBusinessRoleBinding" } } } } ] } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_relationships" ] } }, "/businesses/invites": { "patch": { "summary": "Accept or decline an invite/request", "description": "Accept or decline invites or requests.", "operationId": "respond_business_access_invites", "security": [ { "pinterest_oauth2": [ "biz_access:read", "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthRespondInvitesBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RespondToInvitesResponseArray" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_invite" ] } }, "/businesses/{business_id}/assets/{asset_id}/members": { "get": { "summary": "Get members with access to asset", "description": "Get all the members the requesting business has granted access to on the given asset.", "operationId": "business_asset_members/get", "security": [ { "pinterest_oauth2": [ "biz_access:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" }, { "$ref": "#/components/parameters/path_asset_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_business_access_start_index" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "items": { "type": "array", "description": "List of members with permissions to the asset.", "items": { "$ref": "#/components/schemas/UserSingleAssetBinding" } } } } ] } } }, "description": "Sucess" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_assets" ] } }, "/businesses/{business_id}/assets/{asset_id}/partners": { "get": { "summary": "Get partners with access to asset", "description": "Get all the partners the requesting business has granted access to on the given asset.\nNote: If the asset has been shared with you, an empty array will be returned. This is because an asset shared with\nyou cannot be shared with a different partner.", "operationId": "business_asset_partners/get", "security": [ { "pinterest_oauth2": [ "biz_access:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" }, { "$ref": "#/components/parameters/path_asset_id" }, { "$ref": "#/components/parameters/query_business_access_start_index" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "items": { "type": "array", "description": "List of partners with permissions to the asset.", "items": { "$ref": "#/components/schemas/UserSingleAssetBinding" } } } } ] } } }, "description": "Sucess" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_assets" ] } }, "/businesses/{business_id}/invites/assets/access": { "post": { "summary": "Update invite/request with an asset permission", "description": "Assign asset permissions information to an existing invite/request. Can be used to:\n- Request access to a partner's asset. Note: This is only for when no existing partnership exists. If an existing\n partnership exists, use \"Create a request to access an existing partner's assets\" to request access to your\n partner's assets.\n - invite_type=\"PARTNER_REQUEST\"\n- Invite a partner to access your business assets. Note: This is only for when there is no existing partnership.\n If there is an existing partnership, use \"Assign/Update partner asset permissions\" to assign a partner access to\n new assets.\n - invite_type=\"PARTNER_INVITE\"\n- Invite a member to access your business assets. Note: This is only for when there is no existing membership.\n If there is an existing membership, use \"Assign/Update member asset permissions\" to assign a member access to new\n assets.\n - invite_type=\"MEMBER_INVITE\"\n\nTo learn more about permission levels, visit https://help.pinterest.com/en/business/article/business-manager-overview.", "operationId": "create_asset_invites", "security": [ { "pinterest_oauth2": [ "biz_access:read", "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssetInvitesRequest" } } }, "description": "A list of invites/requests together with the asset permissions to be assigned to the invite/request.\n", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateInvitesResultsResponseArray" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_invite" ] } }, "/businesses/{business_id}/requests/assets/access": { "post": { "summary": "Create a request to access an existing partner's assets.", "description": "Create a request to access an existing partner's assets with the specified permissions. The request will be sent to the partner for approval. The assets that can be requested are ad accounts and profiles.", "operationId": "asset_access_requests/create", "security": [ { "pinterest_oauth2": [ "biz_access:read", "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssetAccessRequestBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssetAccessRequestResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_invite" ] } }, "/businesses/{business_id}/members": { "get": { "summary": "Get business members", "description": "Get all members of the specified business.\nThe return response will include the member's business_role and assets they have access to if assets_summary=TRUE", "operationId": "get/business_members", "security": [ { "pinterest_oauth2": [ "biz_access:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" }, { "$ref": "#/components/parameters/query_assets_summary" }, { "name": "business_roles", "in": "query", "description": "A list of business roles to filter the members by. Only members whose roles are in the specified roles will be returned.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MemberBusinessRole" } } }, { "name": "member_ids", "in": "query", "description": "A list of business members ids separated by comma.", "example": "00101010101,2222220101", "required": false, "schema": { "type": "string", "maxLength": 500 } }, { "$ref": "#/components/parameters/query_business_access_start_index" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "items": { "type": "array", "description": "List of business members.", "items": { "$ref": "#/components/schemas/UserBusinessRoleBinding" } } } } ] } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_relationships" ] }, "patch": { "description": "Update a member's business role within the business.", "summary": "Update member's business role", "operationId": "update/business_memberships", "security": [ { "pinterest_oauth2": [ "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_id" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/UpdateMemberBusinessRoleBody" } } } }, "description": "List of objects with the member id and the business_role.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberResultsResponseArray" } } }, "description": "response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_relationships" ] }, "delete": { "description": "Terminate memberships between the specified members and your business.", "summary": "Terminate business memberships", "operationId": "delete_business_membership", "security": [ { "pinterest_oauth2": [ "biz_access:read", "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_business_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MembersToDeleteBody" } } }, "description": "List of members with role to delete.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedMembersResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_relationships" ] } }, "/businesses/{business_id}/assets": { "get": { "summary": "List business assets", "description": "Get all the assets the requesting business has access to. This includes assets the business owns and assets the business has access to through partnerships.", "operationId": "business_assets/get", "security": [ { "pinterest_oauth2": [ "biz_access:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" }, { "name": "permissions", "in": "query", "description": "A list of asset permissions used to filter the assets. Only assets where the requesting business has at least one of the specified permissions will be returned.", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PermissionsWithOwner" } } }, { "name": "child_asset_id", "in": "query", "description": "A child asset unique identifier. Used to fetch asset groups that contain the asset id as a child.", "required": false, "schema": { "type": "string", "pattern": "^\\d+$", "example": "549764894835", "minLength": 1, "maxLength": 20 } }, { "name": "asset_group_id", "in": "query", "description": "An asset group unique identifier. Used to fetch assets contained within the specified asset group.", "required": false, "schema": { "type": "string", "pattern": "^\\d+$", "example": "7078106104032", "minLength": 1, "maxLength": 20 } }, { "$ref": "#/components/parameters/query_resource_type" }, { "$ref": "#/components/parameters/query_business_access_start_index" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "items": { "type": "array", "description": "List of assets the requesting business has access to.", "items": { "$ref": "#/components/schemas/GetBusinessAssetsResponse" } } } } ] } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_assets" ] } }, "/businesses/{business_id}/members/{member_id}/assets": { "get": { "summary": "Get assets assigned to a member", "description": "Get assets on which you assigned asset permissions to the given member. Can be used to:\n- get all assets, regardless of asset type or\n- get assets of one asset type by using the asset_type query.\nThe return response will include the permissions the member has to that asset and the asset type.", "operationId": "business_member_assets/get", "security": [ { "pinterest_oauth2": [ "biz_access:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" }, { "$ref": "#/components/parameters/path_business_member_user" }, { "$ref": "#/components/parameters/query_resource_type" }, { "$ref": "#/components/parameters/query_business_access_start_index" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "items": { "type": "array", "description": "List asset permissions the given member was granted.", "items": { "$ref": "#/components/schemas/AssetIdPermissions" } } } } ] } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_assets" ] } }, "/businesses/{business_id}/members/assets/access": { "patch": { "description": "Grant multiple members access to assets and/or update multiple member's exisiting permissions to an asset.\nNote: Not all listed permissions are applicable to each asset type. For example, PROFILE_PUBLISHER would not be applicable to an asset of type AD_ACCOUNT. The permission level PROFILE_PUBLISHER is only available to an asset of the type PROFILE.\n", "summary": "Assign/Update member asset permissions", "operationId": "business_members_asset_access/update", "security": [ { "pinterest_oauth2": [ "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberAssetAccessBody" } } }, "description": "List of member asset permissions to create or update.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberAssetsResultsResponseArray" } } }, "description": "response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_assets" ] }, "delete": { "description": "Terminate multiple members' access to an asset.", "summary": "Delete member access to asset", "operationId": "business_members_asset_access/delete", "security": [ { "pinterest_oauth2": [ "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "accesses" ], "properties": { "accesses": { "type": "array", "minItems": 1, "maxItems": 100, "description": "List of members asset access to be deleted", "items": { "type": "object", "required": [ "asset_id", "member_id" ], "properties": { "asset_id": { "type": "string", "description": "Id of the asset on which to remove member permissions.", "example": "549755885175", "maxLength": 25, "pattern": "^\\d+$" }, "member_id": { "type": "string", "description": "Unique identifier of the member on which to perform the asset permission removal", "example": "140943737684417", "maxLength": 25, "pattern": "^\\d+$" } } } } } } } }, "description": "List member assset permissions to delete.", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMemberAccessResultsResponseArray" } } }, "description": "response" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_assets" ] } }, "/businesses/{business_id}/invites": { "get": { "summary": "Get invites/requests", "description": "Get the membership/partnership invites and/or requests for the authorized user.", "operationId": "get/invites", "security": [ { "pinterest_oauth2": [ "biz_access:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" }, { "$ref": "#/components/parameters/query_is_member" }, { "$ref": "#/components/parameters/query_invite_status" }, { "$ref": "#/components/parameters/query_invite_type" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "items": { "type": "array", "description": "List of invite and request data.", "items": { "$ref": "#/components/schemas/InviteResponse" } } } } ] } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_invite" ] }, "post": { "summary": "Create invites or requests", "description": "Create batch invites or requests. Can create batch invites or requests as described below.\n- Invite members to join the business. This would required specifying the following:\n - invite_type=\"MEMBER_INVITE\"\n - business_role=\"EMPLOYEE\" OR business_role=\"BIZ_ADMIN\" (To learn more about business roles, visit\n https://help.pinterest.com/en/business/article/profile-permissions-in-business-access.)\n - members\n- Invite partners to access your business assets. This would require specifying the following:\n - invite_type=\"PARTNER_INVITE\"\n - business_role=\"PARTNER\"\n - partners\n- Request to be a partner so you can access their assets. This would require specifying the following:\n - invite_type=\"PARTNER_REQUEST\"\n - business_role=\"PARTNER\"\n - partners", "operationId": "create_membership_or_partnership_invites", "security": [ { "pinterest_oauth2": [ "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMembershipOrPartnershipInvitesBody" } } }, "description": "An object with the properties: invite_type, partners, members, business_role" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvitesResultsResponseArray" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_invite" ] }, "delete": { "summary": "Cancel invites/requests", "description": "Cancel membership/partnership invites and/or requests.", "operationId": "cancel_invites_or_requests", "security": [ { "pinterest_oauth2": [ "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelInvitesBody" } } }, "description": "A list with invite ids" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteInvitesResultsResponseArray" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_invite" ] } }, "/businesses/{business_id}/partners/assets": { "patch": { "summary": "Assign/Update partner asset permissions", "description": "Grant multiple partners access to assets and/or update multiple partner's exisiting permissions to an asset.\nIf your partner already had permissions on the asset, they will be overriden with the new permissions you assign to them.\nTo learn more about permission levels, visit https://help.pinterest.com/en/business/article/business-manager-overview\n\nNote: Not all listed permissions are applicable to each asset type. For example, PROFILE_PUBLISHER would not be\napplicable to an asset of type AD_ACCOUNT. The permission level PROFILE_PUBLISHER is only available to an asset of\nthe type PROFILE.", "operationId": "update_partner_asset_access_handler_impl", "security": [ { "pinterest_oauth2": [ "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" } ], "requestBody": { "description": "A list of assets and permissions to assign to your partners.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePartnerAssetAccessBody" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePartnerAssetsResultsResponseArray" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_assets" ] }, "delete": { "summary": "Delete partner access to asset", "description": "Terminate multiple partners' access to an asset. If\n- partner_type=INTERNAL: You will terminate a partner's asset access to your business assets.\n- partner_type=EXTERNAL: You will terminate your own access to your partner's business assets.", "operationId": "delete_partner_asset_access_handler_impl", "security": [ { "pinterest_oauth2": [ "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePartnerAssetAccessBody" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePartnerAssetsResultsResponseArray" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_assets" ] } }, "/businesses/{business_id}/partners/{partner_id}/assets": { "get": { "summary": "Get assets assigned to a partner or assets assigned by a partner", "description": "Can be used to get the business assets your partner has granted you access to or the business assets you have\ngranted your partner access to. If you specify:\n- partner_type=INTERNAL, you will retrieve your business assets that the partner has access to.\n- partner_type=EXTERNAL, you will retrieve the partner's business assets that the partner has granted you access to.", "operationId": "business_partner_asset_access/get", "security": [ { "pinterest_oauth2": [ "biz_access:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" }, { "$ref": "#/components/parameters/path_business_partner_user" }, { "name": "partner_type", "in": "query", "description": "Specifies whether to fetch internal or external (shared) partners.\nIf partner_type=INTERNAL, the asset being queried is for accesses the partner has to your business assets.
\nIf partner_type=EXTERNAL, the asset being queried is for the accesses you have to the partner's business asset.", "example": "INTERNAL", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/PartnerType" }, { "default": "INTERNAL" } ] } }, { "$ref": "#/components/parameters/query_resource_type" }, { "$ref": "#/components/parameters/query_business_access_start_index" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "items": { "type": "array", "description": "List assets on which you granted access to your partner or assets on which your partner has granted you access.", "items": { "$ref": "#/components/schemas/GetPartnerAssetsResponse" } } } } ] } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_assets" ] } }, "/businesses/{business_id}/partners": { "get": { "summary": "Get business partners", "description": "Get all partners of the specified business.\n\nIf the assets_summary=TRUE and:\n- partner_type=INTERNAL, the business assets returned are your business assets the partner has access to.\n- partner_type=EXTERNAL, the business assets returned are your partner's business assets the partner has granted you\n access to.", "operationId": "get/business_partners", "security": [ { "pinterest_oauth2": [ "biz_access:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" }, { "$ref": "#/components/parameters/query_assets_summary" }, { "$ref": "#/components/parameters/query_business_partner_type" }, { "name": "partner_ids", "in": "query", "description": "A list of business partner ids separated by commas used to filter the results. Only partners with the specified ids will be returned.", "example": "00101010101,2222220101", "required": false, "schema": { "type": "string", "maxLength": 500 } }, { "$ref": "#/components/parameters/query_business_access_start_index" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "items": { "type": "array", "description": "List of business partners.", "items": { "$ref": "#/components/schemas/UserBusinessRoleBinding" } } } } ] } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_relationships" ] }, "delete": { "summary": "Terminate business partnerships", "description": "Terminate partnerships between the specified partners and your business.\nNote: You may only batch terminate partners of the same partner type.", "operationId": "delete_business_partners", "security": [ { "pinterest_oauth2": [ "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePartnersRequest" } } }, "description": "An object containing a \"partner_ids\" property composed of a list of partner IDs and a \"partners_type\" property specifying the type of partners to delete.\n" }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletePartnersResponse" } } }, "description": "Success" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "A supplied partner id doesn't exist" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_relationships" ] } }, "/businesses/{business_id}/audiences": { "get": { "summary": "List received audiences for a business", "description": "Get a list of received audiences for the given business.", "operationId": "shared_audiences_for_business/list", "security": [ { "pinterest_oauth2": [ "biz_access:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Audience" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "audience_sharing" ] } }, "/businesses/{business_id}/audiences/shared/accounts": { "get": { "summary": "List accounts with access to an audience owned by a business", "description": "List all ad accounts and/or businesses that have access to a specific audience.\nThe audience must either be owned by an ad account in the requesting business, or it must have been shared with the requesting business.\nIf the requesting business is not the owner of the audience, only ad accounts owned by the requesting business will be returned.", "operationId": "business_account_audiences_shared_accounts/list", "security": [ { "pinterest_oauth2": [ "biz_access:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" }, { "$ref": "#/components/parameters/query_audience_id" }, { "$ref": "#/components/parameters/query_account_type" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SharedAudienceAccount" } } } } ] } } } }, "400": { "description": "Invalid business audiences shared accounts parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid business audiences shared accounts parameters." } } } }, "404": { "description": "Shared accounts not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "audience_sharing" ] } }, "/businesses/{business_id}/audiences/ad_accounts/shared": { "patch": { "summary": "Update audience sharing from a business to ad accounts", "description": "From a business, share a specific audience with other ad account(s), or revoke access to a previously shared audience.
  • If the business is the owner of the audience, it can share with any ad account within the same business hierarchy.
  • If the business is the recipient of the audience, it can share with any of its owned ad accounts.
This endpoint is not available to all apps.Learn more.", "operationId": "update_business_to_ad_account_shared_audience", "security": [ { "pinterest_oauth2": [ "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedAudience" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SharedAudienceResponse" } } }, "description": "Success" }, "400": { "description": "Invalid parameters.", "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": [ "audience_sharing" ] } }, "/businesses/{business_id}/audiences/businesses/shared": { "patch": { "summary": "Update audience sharing between businesses", "description": "From a business, share a specific audience with another business account, or revoke access to a previously shared audience. Only the audience owner can share the audience with other businesses, and the recipient business must be within the same business hierarchy.
This endpoint is not available to all apps.Learn more.", "operationId": "update_business_to_business_shared_audience", "security": [ { "pinterest_oauth2": [ "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessSharedAudience" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BusinessSharedAudienceResponse" } } }, "description": "Success" }, "400": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid business id" } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "audience_sharing" ] } }, "/businesses/{business_id}/asset_groups": { "post": { "summary": "Create a new asset group.", "description": "Create a new asset group with the specified parameters.\n- An asset group is a custom group of assets based on how you’d like to manage your accounts.", "operationId": "asset_group/create", "security": [ { "pinterest_oauth2": [ "biz_access:read", "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssetGroupBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAssetGroupResponse" } } }, "description": "Success" }, "400": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid parameters." } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_assets" ] }, "patch": { "summary": "Update asset groups.", "description": "Update a batch of asset groups with the specified parameters.", "operationId": "asset_group/update", "security": [ { "pinterest_oauth2": [ "biz_access:read", "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAssetGroupBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAssetGroupResponse" } } }, "description": "Success" }, "400": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid parameters." } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_assets" ] }, "delete": { "summary": "Delete asset groups.", "description": "Delete a batch of asset groups.", "operationId": "asset_group/delete", "security": [ { "pinterest_oauth2": [ "biz_access:read", "biz_access:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_business_user" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAssetGroupBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteAssetGroupResponse" } } }, "description": "Success" }, "400": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid parameters." } } } }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "business_access_assets" ] } }, "/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" }, { "type": "object", "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" ] }, "post": { "x-ratelimit-category": "catalogs_write", "summary": "Create catalog", "description": "Create a new catalog owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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\n\nNote: this API only supports the catalog type of HOTEL for now.", "operationId": "catalogs/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 feed.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsCreateRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" } } }, "description": "Success" }, "400": { "description": "Invalid 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." } } } } } }, "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" ] }, { "client_credentials": [ "catalogs:read" ] } ], "x-sandbox": "enabled", "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" }, { "type": "object", "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.\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf you require access, please reach out to your partner manager.", "operationId": "feeds/create", "security": [ { "pinterest_oauth2": [ "catalogs:read", "catalogs:write" ] }, { "client_credentials": [ "catalogs:read", "catalogs:write" ] } ], "x-sandbox": "enabled", "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 as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/" } } } } } }, "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" ] }, { "client_credentials": [ "catalogs:read" ] } ], "x-sandbox": "enabled", "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.\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf you require access, please reach out to your partner manager.", "operationId": "feeds/update", "security": [ { "pinterest_oauth2": [ "catalogs:read", "catalogs:write" ] }, { "client_credentials": [ "catalogs:read", "catalogs:write" ] } ], "x-sandbox": "enabled", "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 as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/" } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/" } } } } } }, "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" ] }, { "client_credentials": [ "catalogs:read", "catalogs:write" ] } ], "x-sandbox": "enabled", "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 as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/" } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/" } } } } } }, "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}/ingest": { "post": { "x-ratelimit-category": "catalogs_write", "summary": "Ingest feed items", "description": "Ingest items for a given feed owned by the \"operation user_account\".\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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\n\nNote: This endpoint is restricted to a specific group of users. If you require access, please reach out to your partner manager.", "operationId": "feeds/ingest", "security": [ { "pinterest_oauth2": [ "catalogs:write" ] } ], "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_catalogs_feed_id" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "description": "The ingestion process was successfully started.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsFeedIngestion" } } } }, "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 as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/" } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/" } } } } } }, "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" ] } }, "/catalogs/feeds/{feed_id}/processing_results": { "get": { "x-ratelimit-category": "catalogs_read", "summary": "List feed processing results", "description": "Fetch a feed processing results owned by the \"operation user_account\". Please note that for now the bookmark parameter is not functional and only the first page will be available until it is implemented in some release in the near future.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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": "enabled", "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" }, { "type": "object", "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", "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\nNote: To get a list of all affected items instead of sampled issues, please refer to Build catalogs report and Get catalogs report endpoints. Moreover, they support multiple types of catalogs.\n\nLearn more", "operationId": "items_issues/list", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-sandbox": "enabled", "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" }, { "type": "object", "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": { "deprecated": true, "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.\n\nNote: this endpoint is deprecated and will be deleted soon. Please use Get catalogs items (POST) instead.", "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" ] }, "post": { "summary": "Get catalogs items (POST)", "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.\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf you require access, please reach out to your partner manager.", "operationId": "items/post", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-ratelimit-category": "catalogs_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "description": "Request object used to get catalogs items", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsItemsRequest" } } } }, "responses": { "200": { "description": "Response containing the requested catalogs items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsItems" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "Invalid request: {'country': 'US', 'language': 'EN', 'filters': {'catalog_type': 'RETAIL', 'item_ids': 'test0'}} ('test0' is not of type array)" } } } } } }, "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.\n\nNote:\n- Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf you require access, please reach out to your partner manager.\n- The item UPSERT operation is restricted to users without a feed data source. If you plan to migrate item ingestion from feeds to the API, please reach out to your partner manager to get assistance.", "operationId": "items_batch/post", "x-ratelimit-category": "catalogs_write", "x-sandbox": "enabled", "security": [ { "pinterest_oauth2": [ "catalogs:read", "catalogs:write" ] }, { "client_credentials": [ "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 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" ] }, { "client_credentials": [ "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/multiple": { "delete": { "x-ratelimit-category": "catalogs_write", "summary": "Delete product groups", "description": "Delete product groups owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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_many", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_catalogs_product_group_ids_required" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "security": [ { "pinterest_oauth2": [ "catalogs:write" ] } ], "responses": { "204": { "description": "Catalogs Product Groups deleted successfully." }, "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 as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/" } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/" } } } } } }, "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" ] }, "post": { "x-ratelimit-category": "catalogs_write", "summary": "Create product groups", "description": "Create product group to use in Catalogs owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf you require access, please reach out to your partner manager.", "operationId": "catalogs_product_groups/create_many", "security": [ { "pinterest_oauth2": [ "catalogs:write" ] } ], "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "description": "Request object used to create one or more catalogs product groups.", "required": true, "content": { "application/json": { "schema": { "type": "array", "title": "multiple product groups", "items": { "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", "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\"", "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 } } ] } } ] }, "CatalogBasedRetailFewFiltersUsingAllOf": { "summary": "A simple catalog based 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 retail to be included in the Product Group.\n", "value": [ { "catalog_type": "RETAIL", "name": "Few Filters using \"all_of\"", "catalog_id": "4866935934774", "country": "US", "locale": "en-US", "filters": { "all_of": [ { "ITEM_ID": { "values": [ "item1", "item2" ] } }, { "CUSTOM_LABEL_1": { "values": [ "shoes" ], "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": { "type": "array", "items": { "description": "ID of a created catalog product group.", "example": "443727193917", "type": "string", "pattern": "^\\d+$" } } } }, "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 as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/" } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/" } } } } } }, "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": { "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_product_group_ids" }, { "$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" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$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 as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/" } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/" } } } } } }, "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\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf you require access, please reach out to your partner manager.", "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 create a single catalogs product groups.", "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", "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\"", "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 } } ] } } }, "CatalogBasedRetailFewFiltersUsingAllOf": { "summary": "A simple catalog based 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 retail to be included in the Product Group.\n", "value": { "catalog_type": "RETAIL", "name": "Few Filters using \"all_of\"", "catalog_id": "4866935934774", "country": "US", "locale": "en-US", "filters": { "all_of": [ { "ITEM_ID": { "values": [ "item1", "item2" ] } }, { "CUSTOM_LABEL_1": { "values": [ "shoes" ], "negated": false } } ] } } } } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$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 as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/" } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/" } } } } } }, "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": { "$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 as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/" } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/" } } } } } }, "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 as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/" } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/" } } } } } }, "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 single product group", "description": "Update product group owned by the \"operation user_account\" to use in Catalogs.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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\n\nNote: Access to the Creative Assets catalog type is restricted to a specific group of users.\nIf you require access, please reach out to your partner manager.", "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": { "$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 as your account has been disapproved. Please see business hub for more details. https://www.pinterest.com/business/hub/" } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "We are reviewing your account. Please see business hub for more details. https://www.pinterest.com/business/hub/" } } } } } }, "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", "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/CatalogsProductGroupProductCountsVertical" } } }, "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 by product group", "description": "Get a list of product pins for a given Catalogs Product Group Id owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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" }, { "$ref": "#/components/parameters/query_pin_metrics" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "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 products by filter", "description": "List products Pins owned by the \"operation user_account\" that meet the criteria specified in the Catalogs Product Group Filter given in the request.\n- This endpoint has been implemented in POST to allow for complex filters. This specific POST endpoint is designed to be idempotent.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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\nNote: This endpoint only supports RETAIL catalog at the moment.\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" }, { "$ref": "#/components/parameters/query_pin_metrics" } ], "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" }, { "type": "object", "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" ] } }, "/catalogs/reports": { "post": { "summary": "Build catalogs report", "description": "Async request to create a report of the catalog owned by the \"operation user_account\". This endpoint generates a report upon receiving the first approved request of the day. Any following requests with identical parameters will yield the same report even if data has changed.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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": "reports/create", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-ratelimit-category": "catalogs_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" } ], "requestBody": { "description": "Request object to asynchronously create a report.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsReportParameters" } } } }, "responses": { "200": { "description": "Response containing the report token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsCreateReportResponse" } } } }, "404": { "description": "Entity (e.g., catalog, feed or processing_result) not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogNotFound": { "value": { "code": 678, "message": "Sorry! We couldn't find that catalog. Please ensure you have access to a valid catalog id." } }, "FeedNotFound": { "value": { "code": 4161, "message": "Sorry! We could not find your catalogs feed." } }, "CatalogsProcessingResultNotFound": { "value": { "code": 4184, "message": "Sorry! We could not find your processing result" } } } } } }, "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" ] }, "get": { "summary": "Get catalogs report", "description": "This returns a URL to a report given a token returned from Build catalogs report. You can use the URL to download the report.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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": "reports/get", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-ratelimit-category": "catalogs_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" }, { "$ref": "#/components/parameters/query_catalogs_report_token" } ], "responses": { "200": { "description": "Response that contains a link to download the report", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsReport" } } } }, "400": { "description": "The token you provided is not valid or has expired.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidReportingToken": { "value": { "code": 1104, "message": "The token you provided is not valid or has expired." } } } } } }, "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/reports/stats": { "get": { "summary": "List report stats", "description": "List aggregated numbers of issues for a catalog owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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": "reports/stats", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-ratelimit-category": "catalogs_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_catalogs_report_stats_parameters" } ], "responses": { "200": { "description": "Response containing the diagnostics aggregated counters", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogsReportStats" } } } } ] } } } }, "401": { "description": "Not authorized to access catalogs", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 2, "message": "Authentication failed." } } } } } }, "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" }, { "type": "object", "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" }, { "type": "object", "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.\n\nGrant type client_credentials and its corresponding response type are not fully available. You will likely get a default error if you attempt to use this grant_type.", "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\".\n\nDisclaimer: there are known performance issues when filtering by field creative_type and including protected pins. If your\nrequest is timing out in this scenario we encourage you to use GET List Pins on Board.", "operationId": "pins/list", "security": [ { "pinterest_oauth2": [ "boards:read", "pins:read" ] }, { "client_credentials": [ "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" }, { "type": "object", "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# /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# /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# /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" ] }, { "client_credentials": [ "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# /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# /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# /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# /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# /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# /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# /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# /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" ] }, { "client_credentials": [ "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/analytics": { "get": { "summary": "Get multiple Pin analytics", "description": "This endpoint is currently in beta and not available to all apps. Learn more.\n\nGet analytics for multiple pins owned by the \"operation user_account\" - or on a group board that has been shared with this account.\n- The maximum number of pins supported in a single request is 100.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) 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": "multi_pins/analytics", "security": [ { "pinterest_oauth2": [ "boards:read", "pins:read" ] }, { "client_credentials": [ "boards:read", "pins:read" ] } ], "x-ratelimit-category": "org_analytics", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/query_required_pin_ids" }, { "$ref": "#/components/parameters/query_start_date" }, { "$ref": "#/components/parameters/query_end_date" }, { "$ref": "#/components/parameters/query_app_types" }, { "description": "Pin metric types to get data for.", "explode": false, "in": "query", "name": "metric_types", "required": true, "schema": { "type": "array", "items": { "oneOf": [ { "description": "Standard Pin metric types", "type": "string", "enum": [ "IMPRESSION", "OUTBOUND_CLICK", "PIN_CLICK", "SAVE", "SAVE_RATE", "TOTAL_COMMENTS", "TOTAL_REACTIONS", "USER_FOLLOW", "PROFILE_VISIT" ] }, { "description": "Video Pin metric types", "type": "string", "enum": [ "IMPRESSION", "OUTBOUND_CLICK", "PIN_CLICK", "SAVE", "SAVE_RATE", "VIDEO_MRC_VIEW", "VIDEO_10S_VIEW", "QUARTILE_95_PERCENT_VIEW", "VIDEO_V50_WATCH_TIME", "VIDEO_START", "VIDEO_AVG_WATCH_TIME", "TOTAL_COMMENTS", "TOTAL_REACTIONS" ] } ] } }, "style": "form" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkPinAnalyticsResponse" } } } }, "400": { "description": "Invalid pins analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 1, "message": "Invalid multi_pins analytics parameters." } } } }, "401": { "description": "Not authorized to access board or Pin.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 7, "message": "Not authorized to access board or 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}/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# /docs/api/v5/#operation/pins/list\nPIN_ID=\"\"\n\n# Board information can be fetched from profile page or from list board method here:\n# /docs/api/v5/#operation/boards/list\nNEW_BOARD_ID=\"\"\n\npin_save = Pin(pin_id=PIN_ID)\npin_save.save(board_id=NEW_BOARD_ID)\nprint(\"Pin Id: %s, Board Id:%s\" %(pin_save.id, pin_save.board_id))\n" }, { "lang": "cURL", "label": "curl", "source": "# Pin and Board information can be fetched from profile page or from create/list pin method here:\n# /docs/api/v5/#operation/pins/list\n# /docs/api/v5/#operation/boards/list\n\ncurl --request DELETE 'https://api.pinterest.com/v5/pins//save' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"board_id\": \n}'\n" }, { "lang": "cURL", "label": "curl (Sandbox)", "source": "# Pin and Board information can be fetched from profile page or from create/list pin method here:\n# /docs/api/v5/#operation/pins/list\n# /docs/api/v5/#operation/boards/list\n\ncurl --request DELETE 'https://api-sandbox.pinterest.com/v5/pins//save' \\\n--header 'Authorization: Bearer ' \\\n--header 'Content-Type: application/json' \\\n--data-raw '{\n \"board_id\": \n}'\n" } ], "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" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "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" ] }, { "client_credentials": [ "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" }, { "type": "object", "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" }, { "type": "object", "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" }, { "type": "object", "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.

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

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

For an interactive way to explore this data, please visit trends.pinterest.com.\n", "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" }, { "name": "include_keywords", "description": "If set, filters the results to top trends which include at least one of the specified keywords.
\nIf unset, no keyword filtering logic is applied.", "example": [ "recipes", "dessert" ], "in": "query", "required": false, "schema": { "$ref": "#/components/schemas/KeywordList" } }, { "$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" ] }, { "client_credentials": [ "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" ] }, { "client_credentials": [ "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" ] }, { "client_credentials": [ "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" ] }, { "client_credentials": [ "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" ] }, { "client_credentials": [ "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" }, { "type": "object", "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" ] }, { "client_credentials": [ "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" }, { "type": "object", "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" ] }, { "client_credentials": [ "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" }, { "type": "object", "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", "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" } ], "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" }, { "type": "object", "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", "parameters": [ { "$ref": "#/components/parameters/query_ad_account_id" } ], "security": [ { "pinterest_oauth2": [ "user_accounts:read" ] }, { "client_credentials": [ "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" ] }, { "client_credentials": [ "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" }, { "type": "object", "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" }, "client_credentials": { "flows": { "clientCredentials": { "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" }, "tokenUrl": "https://api.pinterest.com/v3/oauth/access_token/" } }, "type": "oauth2" } }, "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" }, "partner_metadata": { "description": "Partner metadata. Only for clients that requires special handling. We recommend to avoid this param.", "type": "object", "properties": { "subscriber_key": { "description": "Text field value that uniquely identifies a subscriber.", "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", "nullable": true }, "cryptographic_algorithm": { "description": "Lead data encryption algorithm.", "example": "AES-256-GCM", "type": "string", "nullable": true }, "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", "nullable": true }, "cryptographic_algorithm": { "description": "Lead data encryption algorithm.", "example": "AES-256-GCM", "type": "string", "nullable": true }, "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.", "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.", "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_SITE, 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_SITE", "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": { "type": "object", "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" ] } ] }, "AdvancedAuctionItemsGetRequest": { "type": "object", "description": "Request object used to get bid options values for a batch of retail catalog items", "additionalProperties": false, "properties": { "catalog_id": { "description": "Catalog id pertaining to the retail item", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" }, "items": { "type": "array", "minItems": 1, "maxItems": 10000, "description": "A list of retail catalog items to fetch bid options for", "items": { "$ref": "#/components/schemas/AdvancedAuctionItemsGetRecord" } } }, "required": [ "catalog_id", "items" ] }, "AdvancedAuctionItemsGetRecord": { "description": "Object uniquely identifying a retail catalog item", "allOf": [ { "$ref": "#/components/schemas/AdvancedAuctionKey" } ] }, "AdvancedAuctionItems": { "type": "object", "description": "Response object containing item bid options", "properties": { "catalog_id": { "description": "Response object of item bid options", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" }, "items": { "type": "array", "description": "Array with item bid options", "items": { "$ref": "#/components/schemas/AdvancedAuctionItem" } } } }, "AdvancedAuctionItemsSubmitRequest": { "type": "object", "description": "Request containing operations to perform on bid prices and bid multipliers for a batch of retail catalog items", "additionalProperties": false, "properties": { "catalog_id": { "description": "Catalog id pertaining to all items", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" }, "items": { "type": "array", "minItems": 1, "maxItems": 10000, "description": "Array of item bid option operations", "items": { "$ref": "#/components/schemas/AdvancedAuctionItemsSubmitRecord" } } }, "required": [ "catalog_id", "items" ] }, "AdvancedAuctionItemsSubmitRecord": { "type": "object", "description": "Object describing an item bid option operation", "oneOf": [ { "$ref": "#/components/schemas/AdvancedAuctionItemsSubmitUpsertRecord" }, { "$ref": "#/components/schemas/AdvancedAuctionItemsSubmitDeleteRecord" } ], "discriminator": { "propertyName": "operation", "mapping": { "UPSERT": "#/components/schemas/AdvancedAuctionItemsSubmitUpsertRecord", "DELETE": "#/components/schemas/AdvancedAuctionItemsSubmitDeleteRecord" } }, "properties": { "operation": { "$ref": "#/components/schemas/AdvancedAuctionOperation" } }, "required": [ "operation" ] }, "AdvancedAuctionItemsSubmitUpsertRecord": { "description": "Object describing an item bid option upsert operation", "example": { "item_id": "DS0294-M", "country": "US", "language": "EN", "operation": "UPSERT", "bid_options": { "bid_in_micro_currency": 5000000, "app_type_multipliers": { "android_mobile": 1.1, "android_tablet": 1.1, "ipad": 1.2, "iphone": 1.2, "web": 0.9, "web_mobile": 0.8 } }, "update_mask": [ "BID", "APP_TYPE_BID_MULTIPLIER_SET" ] }, "allOf": [ { "$ref": "#/components/schemas/AdvancedAuctionItem" }, { "type": "object", "properties": { "update_mask": { "type": "array", "description": "The list of item bid option fields to be set or updated. Fields specified in the updated mask without a value specified in the `bid_options` object in the body will be set to `null`. If an item bid option record is being created, fields not specified in the update mask will be initialized to `null`.", "example": [ "BID", "APP_TYPE_BID_MULTIPLIER_SET" ], "nullable": true, "items": { "$ref": "#/components/schemas/UpdateMaskBidOptionField" } } }, "required": [ "update_mask" ] } ] }, "AdvancedAuctionItemsSubmitDeleteRecord": { "description": "Object describing an item bid option deletion operation", "example": { "item_id": "DS0294-M", "country": "US", "language": "EN", "operation": "DELETE" }, "allOf": [ { "$ref": "#/components/schemas/AdvancedAuctionKey" } ] }, "AdvancedAuctionProcessedItems": { "type": "object", "description": "Response object containing the results of an operation on an item bid option", "properties": { "catalog_id": { "description": "Catalog id pertaining to all items", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" }, "items": { "type": "array", "description": "Array of advanced auction processed items", "items": { "$ref": "#/components/schemas/AdvancedAuctionProcessedItem" } } } }, "AdvancedAuctionProcessedItem": { "description": "Object describing the result of an operation on an item bid option", "type": "object", "allOf": [ { "$ref": "#/components/schemas/AdvancedAuctionItemsSubmitRecord" }, { "type": "object", "properties": { "errors": { "type": "array", "description": "Array with validation errors for the supplied item bid option modification operation.\nA non empty errors list means this single item operation was not applied.", "items": { "$ref": "#/components/schemas/AdvancedAuctionOperationError" } } } } ] }, "AdvancedAuctionItem": { "title": "Advanced Auction Item", "allOf": [ { "$ref": "#/components/schemas/AdvancedAuctionKey" }, { "type": "object", "properties": { "bid_options": { "$ref": "#/components/schemas/AdvancedAuctionBidOptions" } }, "required": [ "bid_options" ] } ] }, "AdvancedAuctionKey": { "type": "object", "description": "Object uniquely identifying a retail catalog item", "properties": { "item_id": { "description": "The catalog retail item id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "country": { "$ref": "#/components/schemas/Country" }, "language": { "$ref": "#/components/schemas/Language" } }, "required": [ "item_id", "country", "language" ] }, "AdvancedAuctionOperation": { "type": "string", "enum": [ "UPSERT", "DELETE" ] }, "AdvancedAuctionBidOptions": { "type": "object", "description": "Object describing a retail catalog item's bid options (bid price and bid multipliers).", "properties": { "bid_in_micro_currency": { "$ref": "#/components/schemas/BidInMicroCurrency" }, "app_type_multipliers": { "$ref": "#/components/schemas/AppTypeMultipliers" }, "placement_multipliers": { "$ref": "#/components/schemas/PlacementMultipliers" } } }, "AdvancedAuctionOperationError": { "description": "Error which occurred when applying a bid options operation to a specific item.", "type": "object", "properties": { "code": { "description": "The error code for the item bid option operation validation error", "type": "integer", "example": 6 }, "message": { "description": "Message describing the item bid option operation validation error", "type": "string", "example": "Bid in micro currency should be non-negative" } } }, "BidInMicroCurrency": { "type": "integer", "format": "int64", "description": "Bid price in micro currency. A value of 0 will stop distribution for this item in `MAX_BID` ad groups in `CATALOG_SALES` campaigns. A value of `null` will fallback to the ad group's `bid_in_micro_currency`.", "example": 5000000, "nullable": true }, "AppTypeMultipliers": { "type": "object", "description": "This represents a mapping from app type targeting criteria to a bid price adjustment.\n\nMultiplier values must be between 0 and 10. A value of 10 represents a 900% increase in bid price (from $1 to $10 for example). A value of 0 will stop distribution for this item on the specified app type in `MAX_BID` ad groups in `CATALOG_SALES` campaigns. All app type multipliers must be set at the same time. If a multiplier is not provided it is assumed to be 1 (no bid adjustment).", "example": { "android_mobile": 1.1, "android_tablet": 1.1, "ipad": 1.2, "iphone": 1.2, "web": 0.9, "web_mobile": 0.8 }, "properties": { "APP_TYPE": { "$ref": "#/components/schemas/TargetingSpecAppType" } }, "additionalProperties": { "type": "number", "format": "double" }, "nullable": true }, "TargetingSpecAppType": { "type": "string", "enum": [ "android_mobile", "android_tablet", "ipad", "iphone", "web", "web_mobile" ] }, "PlacementMultipliers": { "type": "object", "description": "This represents a mapping from placement to a bid price adjustment.\n\nMultiplier values must be between 0 and 10. A value of 10 represents a 900% increase in bid price (from $1 to $10 for example). A value of 0 will stop distribution for this item on the specified placement in `MAX_BID` ad groups in `CATALOG_SALES` campaigns. All placement multipliers must be set at the same time. If a multiplier is not provided it is assumed to be 1 (no bid adjustment).", "example": { "browse": 0.9, "search": 1.2 }, "properties": { "PLACEMENT": { "type": "string", "enum": [ "SEARCH", "BROWSE" ] } }, "additionalProperties": { "type": "number", "format": "double" }, "nullable": true }, "UpdateMaskBidOptionField": { "type": "string", "description": "bid option field to apply operation updates to", "example": "BID", "enum": [ "BID", "APP_TYPE_BID_MULTIPLIER_SET", "PLACEMENT_BID_MULTIPLIER_SET" ] }, "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. For Campaigns with Video Completion objectives, the only supported bid strategy type is AUTOMATIC_BID.", "enum": [ "AUTOMATIC_BID", "MAX_BID", "TARGET_AVG", null ], "example": "MAX_BID", "title": "BidStrategyType", "type": "string" }, "targeting_template_ids": { "type": "array", "description": "Targeting template IDs applied to the ad group. We currently only support 1 targeting template per ad group. To use targeting templates, do not set any other targeting fields: targeting_spec, tracking_urls, auto_targeting_enabled, placement_group. To clear all targeting template IDs, set this field to ['0'].", "items": { "description": "Targeting template ID.", "type": "string", "pattern": "^\\d+$", "example": "643" }, "maxItems": 1, "nullable": true } } }, "AdGroupCreateRequest": { "type": "object", "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": { "type": "object", "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": { "type": "object", "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" ] } ] }, "AdsAnalyticsAdTargetingType": { "type": "string", "description": "Reporting targeting type for ads", "example": "APPTYPE", "enum": [ "KEYWORD", "APPTYPE", "GENDER", "LOCATION", "PLACEMENT", "COUNTRY", "TARGETED_INTEREST", "PINNER_INTEREST", "AUDIENCE_INCLUDE", "GEO", "AGE_BUCKET", "REGION", "QUIZ_RESULT", "AGE_BUCKET_AND_GENDER" ] }, "AdsAnalyticsCampaignTargetingType": { "type": "string", "description": "Reporting targeting type for campaigns", "example": "APPTYPE", "enum": [ "KEYWORD", "APPTYPE", "GENDER", "LOCATION", "PLACEMENT", "COUNTRY", "TARGETED_INTEREST", "PINNER_INTEREST", "AUDIENCE_INCLUDE", "GEO", "AGE_BUCKET", "REGION", "CREATIVE_TYPE", "AGE_BUCKET_AND_GENDER" ] }, "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": 7, "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" }, "primary_sort": { "type": "string", "allOf": [ { "type": "string", "description": "Whether to first sort the report by date or by entity ID of the reporting entity level. Date will be used as the first level key for JSON reports that use BY_DATE. BY_DATE is recommended for large requests.", "example": "BY_ID", "enum": [ "BY_ID", "BY_DATE" ] } ], "default": "BY_ID" }, "start_hour": { "description": "Which hour of the start date to begin the report. The entire day will be included if no start hour is provided. Only allowed for hourly reports.", "type": "integer", "minimum": 0, "maximum": 23 }, "end_hour": { "description": "Which hour of the end date to stop the report (inclusive). For example, with an end_date of '2020-01-01' and end_hour of '15', the report will contain metrics up to '2020-01-01 14:59:59'. The entire day will be included if no end hour is provided. Only allowed for hourly reports.", "type": "integer", "minimum": 0, "maximum": 23 } } } ] }, "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", "AGE_BUCKET_AND_GENDER" ] }, "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" } }, "AssetIdPermissions": { "type": "object", "description": "An object containing the permissions a business member has on the asset.", "properties": { "asset_id": { "description": "Unique identifier of a business asset.", "example": "549755885175", "pattern": "^\\d+$", "type": "string", "maxLength": 20, "minLength": 1 }, "asset_type": { "$ref": "#/components/schemas/AssetTypeResponse" }, "permissions": { "$ref": "#/components/schemas/PermissionsResponse" }, "asset_group_info": { "nullable": true, "description": "An object containing all the information specific to the provided asset group. This field will be populated only if asset_type equals 'ASSET_GROUP'.", "$ref": "#/components/schemas/AssetGroupBinding" } } }, "AssetIdToPermissions": { "description": "An object mapping asset ids to lists of business permissions. This can be used to setting/requesting permissions on various assets. If accepting an invite or request, this object would be used to grant asset permissions to the member or partner.\n", "type": "object", "minProperties": 1, "additionalProperties": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/Permissions" } }, "example": { "549760723247": [ "ANALYST" ], "549760723248": [ "ANALYST", "ADMIN" ], "809944451643622187": [ "PROFILE_PUBLISHER" ] } }, "AssetTypeResponse": { "description": "Type of asset. Currently we only support AD_ACCOUNT and PROFILE, and ASSET_GROUP.", "example": "AD_ACCOUNT", "type": "string" }, "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" }, "AudienceShareType": { "type": "string", "default": "SHARED", "enum": [ "SHARED", "RECEIVED" ] }, "AudienceAccountType": { "type": "string", "default": "AD_ACCOUNT", "enum": [ "AD_ACCOUNT", "BUSINESS_ACCOUNT" ] }, "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": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/AudienceCommon" }, { "title": "AudienceUpdateRequest", "type": "object", "properties": { "description": { "$ref": "#/components/schemas/AudienceDescription" }, "operation_type": { "$ref": "#/components/schemas/AudienceUpdateOperationType" } } } ] }, "AuthRespondInvitesBody": { "description": "An object with a list of all the invites the user would like to respond to and the action to take.", "type": "object", "required": [ "invites" ], "properties": { "invites": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "properties": { "action": { "type": "object", "properties": { "accept_invite": { "description": "Whether the invite/request is accepted.", "type": "boolean" }, "asset_id_to_permissions": { "$ref": "#/components/schemas/AssetIdToPermissions" } }, "required": [ "accept_invite" ] }, "invite_id": { "description": "Unique identifier of an invite.", "pattern": "^\\d+$", "type": "string", "minLength": 1, "maxLength": 25 } }, "required": [ "invite_id", "action" ], "type": "object" } } } }, "AvailabilityFilter": { "type": "object", "additionalProperties": false, "properties": { "AVAILABILITY": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringCriteria" } }, "required": [ "AVAILABILITY" ] }, "BaseInviteDataResponse": { "type": "object", "nullable": true, "properties": { "id": { "type": "string", "description": "Unique identifier of the invite/request.", "example": "383791336903426391", "pattern": "^\\d+$" }, "invite_data": { "type": "object", "description": "Metadata for the invite/request.", "properties": { "invite_expiration": { "type": "integer", "description": "The date and time when the invite/request will expire. Returned in milliseconds.", "example": 1709748104775 }, "invite_status": { "type": "string", "description": "The current status of the invite. The invite can be in one of the following states PENDING, ACCEPTED, DECLINED, CANCELLED, EXPIRED.", "example": "PENDING" }, "invite_type": { "type": "string", "description": "The type of invite.
'MEMBER_INVITE' is to invite a member to access your business assets.
'PARTNER_INVITE' is to invite a partner to access your business assets.
'PARTNER_REQUEST' is to request access a partner's business assets.", "example": "MEMBER_INVITE" }, "last_updated_time": { "type": "integer", "description": "The date and time the invite/request was last updated. Returned in milliseconds.", "example": 1646767577816 }, "sent_at": { "type": "integer", "description": "The date and time the invite/request was sent/created. Returned in milliseconds.", "example": 1646767577816 } } }, "is_received_invite": { "type": "boolean", "description": "Indicates whether the invite/request was received." }, "user": { "type": "object", "description": "Metadata for the member/partner that was sent the invite/request.", "allOf": [ { "$ref": "#/components/schemas/BusinessAccessUserSummary" } ] } } }, "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", "FAILED" ] }, "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/(...)" } } }, "BusinessAccessError": { "nullable": true, "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "BusinessAccessUserSummary": { "type": "object", "description": "Metadata of the member/partner that has access to the asset.", "properties": { "email": { "description": "Email of the business member/partner.", "example": "business0101@business.com", "type": "string", "nullable": true }, "id": { "description": "Unique identifier of the business member/partner.", "example": "383791336903426391", "type": "string", "nullable": true, "minLength": 1, "maxLength": 20 }, "username": { "description": "Username of the business member/partner.", "example": "business0101", "nullable": true, "type": "string" } } }, "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" ] }, "BusinessMemberAssetsSummary": { "type": "object", "description": "Ad accounts and profiles the business member/partner has access to.", "nullable": true, "properties": { "ad_accounts": { "type": "array", "description": "List of ad account IDs and respective permission levels.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of a business ad account.", "example": "549755885175", "pattern": "^\\d+$", "minLength": 1, "maxLength": 20 }, "permissions": { "$ref": "#/components/schemas/PermissionsResponse" } } } }, "profiles": { "type": "array", "description": "List of profile IDs and respective permission levels.", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of a business profile.", "example": "383791336903426391", "pattern": "^\\d+$", "minLength": 1, "maxLength": 20 }, "permissions": { "$ref": "#/components/schemas/PermissionsResponse" } } } } } }, "BusinessRoleCheckMode": { "description": "Specifies if the partner is internal or external.", "enum": [ "INTERNAL", "EXTERNAL" ], "example": "INTERNAL", "type": "string" }, "BusinessRole": { "type": "string", "description": "The access level a member/partner has to the business. Values are case-sensitive.\n
- EMPLOYEE: Can only view and access assets you assign to them.\nThey cannot see details about other employees, partners, or other assets.\n
- BIZ_ADMIN: Have full control of roles and can add employees and partners as well as grant asset access.\n
- PARTNER: Can only view and access assets you assign them to/or they assign to you.", "example": "BIZ_ADMIN", "enum": [ "EMPLOYEE", "BIZ_ADMIN", "PARTNER" ] }, "BusinessRoleForMembers": { "type": "string", "description": "The access level a member has to the business. Values are case-sensitive.\n
- EMPLOYEE: Can only view and access assets you assign to them.\nThey cannot see details about other employees, partners, or other assets.\n
- BIZ_ADMIN: Have full control of roles and can add employees and partners as well as grant asset access.", "example": "BIZ_ADMIN", "enum": [ "EMPLOYEE", "BIZ_ADMIN" ] }, "BusinessRoleResponse": { "type": "string", "description": "The access level a member/partner has to the business. Values are case-sensitive.\n
- EMPLOYEE: Can only view and access assets you assign to them.\nThey cannot see details about other employees, partners, or other assets.\n
- BIZ_ADMIN: Have full control of roles and can add employees or external partners as well as grant asset access.\n
- PARTNER: Can only view and access assets you assign them to/or they assign to you.", "example": "BIZ_ADMIN" }, "UpdatePartnerAssetAccessBody": { "type": "object", "required": [ "accesses" ], "properties": { "accesses": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "required": [ "partner_id", "asset_id", "permissions" ], "properties": { "partner_id": { "type": "string", "description": "Unique identifier of a business partner to update asset access to.", "example": "1234567890123", "maxLength": 25, "pattern": "^\\d+$" }, "asset_id": { "type": "string", "description": "Unique identifier of the business asset.", "example": "549755885175", "maxLength": 25, "pattern": "^\\d+$" }, "permissions": { "type": "array", "description": "A non-empty array of permissions to assign to the partner.", "example": [ "ANALYST", "ADMIN" ], "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/Permissions" } } } } } } }, "DeletePartnerAssetAccessBody": { "type": "object", "required": [ "accesses" ], "properties": { "accesses": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "properties": { "partner_id": { "type": "string", "description": "Unique identifier of a business partner to update asset access to.", "example": "1234567890123", "maxLength": 25, "pattern": "^\\d+$" }, "asset_id": { "type": "string", "description": "Unique identifier of the business asset.", "example": "549755885175", "maxLength": 25, "pattern": "^\\d+$" }, "partner_type": { "enum": [ "INTERNAL", "EXTERNAL" ], "example": "INTERNAL", "description": "If partner_type=INTERNAL, the deleted asset access is for the access the partner has to your business asset.
\nIf partner_type=EXTERNAL, the deleted asset access is for the access you have to the partner's business asset.", "default": "INTERNAL", "type": "string" } }, "required": [ "partner_id", "asset_id" ] } } } }, "DeletePartnerAssetsResult": { "type": "object", "description": "The terminated asset access.", "properties": { "asset_id": { "description": "Unique identifier of a business asset.", "example": "549755885175", "pattern": "^\\d+$", "type": "string" }, "asset_type": { "$ref": "#/components/schemas/AssetTypeResponse" }, "permissions": { "$ref": "#/components/schemas/PermissionsResponse" }, "is_shared_partner": { "type": "boolean", "description": "If is_shared_partner=FALSE, you terminated a partner's asset access to your business asset.
If is_shared_partner=TRUE, you terminated your asset access to your partner's business asset.", "example": false }, "partner_id": { "description": "Unique identifier of a business partner.", "example": "140943737684417", "pattern": "^\\d+$", "type": "string" } } }, "DeletePartnerAssetsResultsResponseArray": { "type": "object", "properties": { "items": { "type": "array", "description": "List of terminated asset access.", "items": { "type": "object", "$ref": "#/components/schemas/DeletePartnerAssetsResult" } } } }, "UpdateMemberResult": { "type": "object", "properties": { "business_role": { "type": "string", "description": "The access level a member has to the business. Values are case-sensitive.\n
- EMPLOYEE: Can only view and access assets you assign to them.\nThey cannot see details about other employees, partners, or other assets.\n
- BIZ_ADMIN: Have full control of roles and can add employees and partners as well as grant asset access.", "example": "EMPLOYEE" }, "member_id": { "type": "string", "description": "Unique identifier of the business member.", "example": "140943737684417", "pattern": "^\\d+$" } } }, "UpdateMemberResultsResponseArray": { "type": "object", "properties": { "items": { "type": "array", "description": "List of members with updated business access role.", "items": { "$ref": "#/components/schemas/UpdateMemberResult" } } } }, "UpdateMemberBusinessRoleBody": { "description": "Single instance of a business member to have its role updated", "properties": { "business_role": { "$ref": "#/components/schemas/BusinessRoleForMembers" }, "member_id": { "type": "string", "description": "Unique identifier of the member", "maxLength": 25, "example": "140943737684417", "pattern": "^\\d+$" } }, "required": [ "member_id", "business_role" ], "type": "object" }, "UpdateMemberAssetAccessBody": { "type": "object", "description": "An object with a list of all the new accesses.", "required": [ "accesses" ], "properties": { "accesses": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "object", "required": [ "asset_id", "member_id", "permissions" ], "properties": { "asset_id": { "type": "string", "description": "Id of the asset to update.", "example": "549755885175", "maxLength": 25, "pattern": "^\\d+$" }, "member_id": { "type": "string", "description": "Unique identifier of the member on which to perform the update", "example": "140943737684417", "maxLength": 25, "pattern": "^\\d+$" }, "permissions": { "type": "array", "description": "A non-empty array of permissions to assign to the member.", "example": [ "ANALYST", "ADMIN" ], "minItems": 1, "maxItems": 50, "items": { "$ref": "#/components/schemas/Permissions" } } } } } } }, "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 }, "is_flexible_daily_budgets": { "$ref": "#/components/schemas/CampaignIsFlexibleDailyBudgets" } } }, "CampaignCreateCommon": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CampaignCommon" }, { "type": "object", "properties": { "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": { "$ref": "#/components/schemas/CampaignIsAutomatedCampaign" } } } ] }, "CampaignCreateRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CampaignCreateCommon" }, { "type": "object", "properties": { "is_flexible_daily_budgets": { "type": "boolean", "default": false, "allOf": [ { "$ref": "#/components/schemas/CampaignIsFlexibleDailyBudgets" } ] }, "is_automated_campaign": { "type": "boolean", "default": false, "allOf": [ { "$ref": "#/components/schemas/CampaignIsAutomatedCampaign" } ] }, "status": { "type": "string", "default": "ACTIVE", "allOf": [ { "$ref": "#/components/schemas/EntityStatus" } ] }, "objective_type": { "$ref": "#/components/schemas/ObjectiveType" } }, "required": [ "name", "objective_type", "ad_account_id" ] } ] }, "CampaignCreateResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignCreateResponseItem" } } } }, "CampaignCreateResponseData": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CampaignCreateCommon" }, { "$ref": "#/components/schemas/CampaignResponse" }, { "type": "object", "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, "nullable": true }, "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, "nullable": true }, "CampaignIsFlexibleDailyBudgets": { "type": "boolean", "description": "Determine if a campaign has flexible daily budgets setup.", "example": true, "nullable": true }, "CampaignResponse": { "type": "object", "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_campaign_budget_optimization": { "$ref": "#/components/schemas/CampaignIsCampaignBudgetOptimization" }, "summary_status": { "$ref": "#/components/schemas/CampaignSummaryStatus" } } } ] }, "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/CampaignCreateCommon" }, { "type": "object", "properties": { "is_campaign_budget_optimization": { "$ref": "#/components/schemas/CampaignIsCampaignBudgetOptimization" }, "objective_type": { "type": "string", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/ObjectiveType" } ] } }, "required": [ "id", "ad_account_id" ] } ] }, "CampaignUpdateResponse": { "type": "object", "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 } } }, "CancelInvitesBody": { "description": "Request body used to cancel invites", "type": "object", "required": [ "invite_ids" ], "properties": { "invite_ids": { "description": "List of invite/request ids to be cancelled", "example": [ "1234567890123456789", "1122334455667788991" ], "items": { "type": "string", "maxLength": 25, "pattern": "^\\d+$" }, "type": "array", "minItems": 1, "maxItems": 50 } } }, "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" ] } ] }, "CatalogsCreateRequest": { "type": "object", "title": "catalogs_create_request", "description": "Request object for creating a catalog.", "additionalProperties": false, "properties": { "catalog_type": { "description": "Type of the catalog entity.", "type": "string", "enum": [ "HOTEL" ] }, "name": { "description": "A human-friendly name associated to a given catalog.", "type": "string" } }, "required": [ "catalog_type", "name" ] }, "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" } }, "required": [ "id", "created_at", "updated_at" ] }, "CatalogsCreateReportResponse": { "type": "object", "properties": { "token": { "type": "string", "description": "Token to be used to get the report" } } }, "CatalogsReport": { "type": "object", "properties": { "report_status": { "type": "string", "enum": [ "FINISHED", "IN_PROGRESS" ] }, "url": { "type": "string", "nullable": true, "description": "URL to download the report" }, "size": { "type": "number", "nullable": true, "description": "Size of the report in bytes" } } }, "CatalogsReportStats": { "type": "object", "description": "Diagnostics aggregated numbers", "oneOf": [ { "$ref": "#/components/schemas/CatalogsReportFeedIngestionStats" }, { "$ref": "#/components/schemas/CatalogsReportDistributionStats" } ], "discriminator": { "propertyName": "report_type", "mapping": { "FEED_INGESTION_ISSUES": "#/components/schemas/CatalogsReportFeedIngestionStats", "DISTRIBUTION_ISSUES": "#/components/schemas/CatalogsReportDistributionStats" } }, "properties": { "report_type": { "type": "string", "enum": [ "FEED_INGESTION_ISSUES", "DISTRIBUTION_ISSUES" ] } }, "required": [ "report_type" ] }, "CatalogsReportFeedIngestionStats": { "type": "object", "properties": { "report_type": { "type": "string", "enum": [ "FEED_INGESTION_ISSUES" ] }, "catalog_id": { "type": "string", "pattern": "^\\d+$", "description": "ID of the catalog entity." }, "code": { "description": "The event code that a diagnostics aggregated number references", "type": "integer", "example": 112 }, "code_label": { "description": "A human-friendly label for the event code (e.g, 'AVAILABILITY_INVALID')", "type": "string", "example": "AVAILABILITY_INVALID" }, "message": { "description": "Title message describing the diagnostic issue", "type": "string" }, "occurrences": { "description": "Number of occurrences of the issue", "example": 10, "type": "integer" }, "severity": { "description": "An ERROR means that items have been dropped, while a WARN denotes that items have been ingested despite an issue", "type": "string", "enum": [ "WARN", "ERROR" ] } } }, "CatalogsReportDistributionStats": { "type": "object", "properties": { "report_type": { "type": "string", "enum": [ "DISTRIBUTION_ISSUES" ] }, "catalog_id": { "type": "string", "pattern": "^\\d+$", "description": "ID of the catalog entity." }, "code": { "description": "The event code that a diagnostics aggregated number references", "type": "integer" }, "code_label": { "description": "A human-friendly label for the event code (e.g, 'SPAM')", "type": "string", "example": "SPAM" }, "message": { "description": "Title message describing the diagnostic issue", "type": "string" }, "occurrences": { "description": "Number of occurrences of the issue", "example": 10, "type": "integer" }, "ineligible_for_ads": { "description": "Indicates if issue makes items ineligible for ads distribution", "example": true, "type": "boolean" }, "ineligible_for_organic": { "description": "Indicates if issue makes items ineligible for organic distribution", "example": true, "type": "boolean" } } }, "CatalogsReportParameters": { "type": "object", "description": "Report parameters", "properties": { "catalog_type": { "$ref": "#/components/schemas/CatalogsType" } }, "required": [ "catalog_type" ], "oneOf": [ { "$ref": "#/components/schemas/CatalogsRetailReportParameters" }, { "$ref": "#/components/schemas/CatalogsHotelReportParameters" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailReportParameters", "HOTEL": "#/components/schemas/CatalogsHotelReportParameters" } } }, "CatalogsHotelReportParameters": { "type": "object", "description": "Parameters for hotel report", "properties": { "catalog_type": { "type": "string", "enum": [ "HOTEL" ] }, "report": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/CatalogsReportFeedIngestionFilter" }, { "$ref": "#/components/schemas/CatalogsReportDistributionIssueFilter" } ], "discriminator": { "propertyName": "report_type", "mapping": { "FEED_INGESTION_ISSUES": "#/components/schemas/CatalogsReportFeedIngestionFilter", "DISTRIBUTION_ISSUES": "#/components/schemas/CatalogsReportDistributionIssueFilter" } }, "properties": { "report_type": { "type": "string", "enum": [ "FEED_INGESTION_ISSUES", "DISTRIBUTION_ISSUES" ] } } } }, "required": [ "catalog_type", "report" ] }, "CatalogsRetailReportParameters": { "type": "object", "description": "Parameters for retail report", "properties": { "catalog_type": { "type": "string", "enum": [ "RETAIL" ] }, "report": { "type": "object", "oneOf": [ { "$ref": "#/components/schemas/CatalogsReportFeedIngestionFilter" }, { "$ref": "#/components/schemas/CatalogsReportDistributionIssueFilter" } ], "discriminator": { "propertyName": "report_type", "mapping": { "FEED_INGESTION_ISSUES": "#/components/schemas/CatalogsReportFeedIngestionFilter", "DISTRIBUTION_ISSUES": "#/components/schemas/CatalogsReportDistributionIssueFilter" } }, "properties": { "report_type": { "type": "string", "enum": [ "FEED_INGESTION_ISSUES", "DISTRIBUTION_ISSUES" ] } } } }, "required": [ "catalog_type", "report" ] }, "CatalogsReportFeedIngestionFilter": { "type": "object", "additionalProperties": false, "properties": { "report_type": { "type": "string", "enum": [ "FEED_INGESTION_ISSUES" ] }, "feed_id": { "type": "string", "pattern": "^\\d+$", "description": "ID of the feed entity." }, "processing_result_id": { "type": "string", "pattern": "^\\d+$", "description": "Unique identifier of a feed processing result. It can be acquired from the \"id\" field of the \"items\" array within the response of the [List processing results for a given feed](/docs/api/v5/#operation/feed_processing_results/list). If not provided, default to most recent completed processing result." } }, "required": [ "report_type", "feed_id" ] }, "CatalogsReportDistributionIssueFilter": { "type": "object", "additionalProperties": false, "properties": { "report_type": { "type": "string", "enum": [ "DISTRIBUTION_ISSUES" ] }, "catalog_id": { "type": "string", "description": "Unique identifier of a catalog. If not given, oldest catalog will be used", "pattern": "^\\d+$" } }, "required": [ "report_type" ] }, "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" }, { "$ref": "#/components/schemas/CatalogsCreativeAssetsFeed" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailFeed", "HOTEL": "#/components/schemas/CatalogsHotelFeed", "CREATIVE_ASSETS": "#/components/schemas/CatalogsCreativeAssetsFeed" } } }, "CatalogsCreativeAssetsFeed": { "type": "object", "title": "catalogs_creative_assets_feed", "description": "Catalogs Creative Asset 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" }, "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", "default_country", "catalog_id" ] } ] }, "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." } } }, "CatalogsFeedIngestion": { "type": "object", "properties": { "id": { "type": "string", "example": "01234" }, "feed_id": { "type": "string", "example": "56789" }, "created_at": { "type": "string", "format": "date-time", "example": "2022-03-14T15:16:34Z" }, "status": { "$ref": "#/components/schemas/CatalogsFeedProcessingStatus" } }, "required": [ "id", "feed_id", "created_at", "status" ] }, "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", "FAILED", "PROCESSING" ] }, "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" }, "status": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/CatalogsStatus" }, { "default": "ACTIVE" } ] } }, "required": [ "format", "location", "name" ] }, "CatalogsHotelAttributes": { "type": "object", "allOf": [ { "type": "object", "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" }, "status": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/CatalogsStatus" }, { "default": "ACTIVE" } ] } }, "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" ] }, "CatalogsRetailItemsPostFilter": { "type": "object", "properties": { "catalog_type": { "type": "string", "enum": [ "RETAIL" ] }, "item_ids": { "type": "array", "minItems": 1, "maxItems": 1000, "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+$" }, "status": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/CatalogsStatus" }, { "default": "ACTIVE" } ] } }, "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" ] }, "CatalogsHotelItemsPostFilter": { "type": "object", "properties": { "catalog_type": { "type": "string", "enum": [ "HOTEL" ] }, "hotel_ids": { "type": "array", "minItems": 1, "maxItems": 1000, "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" ] }, "CatalogsCreativeAssetsItemsFilter": { "type": "object", "properties": { "catalog_type": { "type": "string", "enum": [ "CREATIVE_ASSETS" ] }, "creative_assets_ids": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "string" } }, "catalog_id": { "type": "string", "pattern": "^\\d+$", "description": "Catalog id pertaining to the creative assets item. If not provided, default to oldest creative assets catalog" } }, "required": [ "catalog_type", "creative_assets_ids" ] }, "CatalogsCreativeAssetsItemsPostFilter": { "type": "object", "properties": { "catalog_type": { "type": "string", "enum": [ "CREATIVE_ASSETS" ] }, "creative_assets_ids": { "type": "array", "minItems": 1, "maxItems": 1000, "items": { "type": "string" } }, "catalog_id": { "type": "string", "pattern": "^\\d+$", "description": "Catalog id pertaining to the creative assets item. If not provided, default to oldest creative assets catalog" } }, "required": [ "catalog_type", "creative_assets_ids" ] }, "CatalogsCreativeAssetsFeedsCreateRequest": { "type": "object", "title": "feeds_creative_assets_create_request", "description": "Request object for creating 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" }, "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 } ] }, "default_country": { "$ref": "#/components/schemas/Country" }, "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 creative assets feeds but this will change in the future.", "nullable": true, "type": "string", "pattern": "^\\d+$" }, "status": { "type": "string", "allOf": [ { "$ref": "#/components/schemas/CatalogsStatus" }, { "default": "ACTIVE" } ] } }, "required": [ "format", "location", "name", "catalog_type", "default_country", "default_locale" ] }, "CatalogsVerticalFeedsCreateRequest": { "type": "object", "title": "feeds_create_request", "description": "Request object for creating a feed.", "oneOf": [ { "$ref": "#/components/schemas/CatalogsRetailFeedsCreateRequest" }, { "$ref": "#/components/schemas/CatalogsHotelFeedsCreateRequest" }, { "$ref": "#/components/schemas/CatalogsCreativeAssetsFeedsCreateRequest" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailFeedsCreateRequest", "HOTEL": "#/components/schemas/CatalogsHotelFeedsCreateRequest", "CREATIVE_ASSETS": "#/components/schemas/CatalogsCreativeAssetsFeedsCreateRequest" } } }, "CatalogsCreativeAssetsFeedsUpdateRequest": { "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" ] }, "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" }, { "$ref": "#/components/schemas/CatalogsCreativeAssetsFeedsUpdateRequest" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailFeedsUpdateRequest", "HOTEL": "#/components/schemas/CatalogsHotelFeedsUpdateRequest", "CREATIVE_ASSETS": "#/components/schemas/CatalogsCreativeAssetsFeedsUpdateRequest" } } }, "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" }, { "$ref": "#/components/schemas/CatalogsCreativeAssetsItemsBatch" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailItemsBatch", "HOTEL": "#/components/schemas/CatalogsHotelItemsBatch", "CREATIVE_ASSETS": "#/components/schemas/CatalogsCreativeAssetsItemsBatch" } } }, "CatalogsItemsFilters": { "type": "object", "properties": { "catalog_type": { "$ref": "#/components/schemas/CatalogsType" } }, "required": [ "catalog_type" ], "oneOf": [ { "$ref": "#/components/schemas/CatalogsRetailItemsFilter" }, { "$ref": "#/components/schemas/CatalogsHotelItemsFilter" }, { "$ref": "#/components/schemas/CatalogsCreativeAssetsItemsFilter" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailItemsFilter", "HOTEL": "#/components/schemas/CatalogsHotelItemsFilter", "CREATIVE_ASSETS": "#/components/schemas/CatalogsCreativeAssetsItemsFilter" } } }, "CatalogsItemsPostFilters": { "type": "object", "properties": { "catalog_type": { "$ref": "#/components/schemas/CatalogsType" } }, "required": [ "catalog_type" ], "oneOf": [ { "$ref": "#/components/schemas/CatalogsRetailItemsPostFilter" }, { "$ref": "#/components/schemas/CatalogsHotelItemsPostFilter" }, { "$ref": "#/components/schemas/CatalogsCreativeAssetsItemsPostFilter" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailItemsPostFilter", "HOTEL": "#/components/schemas/CatalogsHotelItemsPostFilter", "CREATIVE_ASSETS": "#/components/schemas/CatalogsCreativeAssetsItemsPostFilter" } } }, "CatalogsCreativeAssetsItemsBatch": { "type": "object", "description": "Object describing the catalogs creative assets items batch", "properties": { "batch_id": { "description": "Id of the catalogs items batch", "example": "595953100599279259-66753b9bb65c46c49bd8503b27fecf9e", "type": "string" }, "created_time": { "description": "Date and time (UTC) of the batch creation: YYYY-MM-DD'T'hh:mm:ss", "example": "2024-01-01T20:10:40", "type": "string", "format": "date-time", "readOnly": true }, "completed_time": { "description": "Date and time (UTC) of the batch completion: YYYY-MM-DD'T'hh:mm:ss", "example": "2024-01-01T20:20: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/CreativeAssetsProcessingRecord" }, "type": "array" } }, "required": [ "catalog_type" ] }, "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": "Date and time (UTC) of the batch creation: YYYY-MM-DD'T'hh:mm:ss", "example": "2024-01-01T20:10:40", "type": "string", "format": "date-time", "readOnly": true }, "completed_time": { "description": "Date and time (UTC) of the batch completion: YYYY-MM-DD'T'hh:mm:ss", "example": "2024-01-01T20:20: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": "Date and time (UTC) of the batch creation: YYYY-MM-DD'T'hh:mm:ss", "example": "2024-01-01T20:10:40", "type": "string", "format": "date-time", "readOnly": true }, "completed_time": { "description": "Date and time (UTC) of the batch completion: YYYY-MM-DD'T'hh:mm:ss", "example": "2024-01-01T20:20: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" ] }, "CatalogsItemsRequest": { "type": "object", "additionalProperties": false, "description": "Request object of catalogs items", "properties": { "country": { "$ref": "#/components/schemas/Country" }, "language": { "description": "We recommend using the CatalogsLocale values.", "anyOf": [ { "$ref": "#/components/schemas/CatalogsLocale" }, { "$ref": "#/components/schemas/Language" } ] }, "filters": { "$ref": "#/components/schemas/CatalogsItemsPostFilters" } }, "required": [ "country", "language", "filters" ] }, "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": { "description": "We recommend using the CatalogsLocale values.", "anyOf": [ { "$ref": "#/components/schemas/CatalogsLocale" }, { "$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": { "description": "We recommend using the CatalogsLocale values.", "anyOf": [ { "$ref": "#/components/schemas/CatalogsLocale" }, { "$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": { "description": "We recommend using the CatalogsLocale values.", "anyOf": [ { "$ref": "#/components/schemas/CatalogsLocale" }, { "$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": { "description": "We recommend using the CatalogsLocale values.", "anyOf": [ { "$ref": "#/components/schemas/CatalogsLocale" }, { "$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": { "description": "We recommend using the CatalogsLocale values.", "anyOf": [ { "$ref": "#/components/schemas/CatalogsLocale" }, { "$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": [ { "$ref": "#/components/schemas/CatalogsListProductsByFeedBasedFilter" }, { "$ref": "#/components/schemas/CatalogsVerticalsListProductsByCatalogBasedFilterRequest" } ] }, "CatalogsListProductsByFeedBasedFilter": { "title": "feed based product group", "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" ] }, "CatalogsVerticalsListProductsByCatalogBasedFilterRequest": { "type": "object", "title": "catalog based product group", "description": "Request object to list products for a given catalog_id and product group filter.", "oneOf": [ { "$ref": "#/components/schemas/CatalogsRetailListProductsByCatalogBasedFilterRequest" }, { "$ref": "#/components/schemas/CatalogsHotelListProductsByCatalogBasedFilterRequest" }, { "$ref": "#/components/schemas/CatalogsCreativeAssetsListProductsByCatalogBasedFilterRequest" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailListProductsByCatalogBasedFilterRequest", "HOTEL": "#/components/schemas/CatalogsHotelListProductsByCatalogBasedFilterRequest", "CREATIVE_ASSETS": "#/components/schemas/CatalogsCreativeAssetsListProductsByCatalogBasedFilterRequest" } } }, "CatalogsRetailListProductsByCatalogBasedFilterRequest": { "type": "object", "title": "retail_list_products_by_catalog_based_filter_request", "additionalProperties": false, "description": "Request object to list products for a given retail catalog_id and product group filter.", "properties": { "catalog_type": { "type": "string", "enum": [ "RETAIL" ], "description": "Retail catalog based product group is available only for selected partners at the moment. If you are not eligible, please use feed based one." }, "catalog_id": { "description": "Catalog id pertaining to the retail product group.", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" }, "filters": { "$ref": "#/components/schemas/CatalogsProductGroupFilters" }, "country": { "$ref": "#/components/schemas/Country" }, "locale": { "$ref": "#/components/schemas/CatalogsLocale" } }, "required": [ "catalog_type", "catalog_id", "filters", "country", "locale" ] }, "CatalogsHotelListProductsByCatalogBasedFilterRequest": { "type": "object", "title": "hotel_list_products_by_catalog_based_filter_request", "additionalProperties": false, "description": "Request object to list products for a given hotel catalog_id and product group filter.", "properties": { "catalog_type": { "type": "string", "enum": [ "HOTEL" ] }, "catalog_id": { "description": "Catalog id pertaining to the hotel product group.", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" }, "filters": { "$ref": "#/components/schemas/CatalogsHotelProductGroupFilters" } }, "required": [ "catalog_type", "catalog_id", "filters" ] }, "CatalogsCreativeAssetsListProductsByCatalogBasedFilterRequest": { "type": "object", "title": "creative_assets_list_products_by_catalog_based_filter_request", "additionalProperties": false, "description": "Request object to list products for a given creative assets catalog_id and product group filter.", "properties": { "catalog_type": { "type": "string", "enum": [ "CREATIVE_ASSETS" ] }, "catalog_id": { "description": "Catalog id pertaining to the creative assets product group.", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" }, "filters": { "$ref": "#/components/schemas/CatalogsCreativeAssetsProductGroupFilters" } }, "required": [ "catalog_type", "catalog_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", "description": "Catalogs product for all verticals", "properties": { "catalog_type": { "$ref": "#/components/schemas/CatalogsType" } }, "required": [ "catalog_type" ], "oneOf": [ { "$ref": "#/components/schemas/CatalogsRetailProduct" }, { "$ref": "#/components/schemas/CatalogsHotelProduct" }, { "$ref": "#/components/schemas/CatalogsCreativeAssetsProduct" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailProduct", "HOTEL": "#/components/schemas/CatalogsHotelProduct", "CREATIVE_ASSETS": "#/components/schemas/CatalogsCreativeAssetsProduct" } } }, "CatalogsVerticalProductGroup": { "type": "object", "title": "product_group", "oneOf": [ { "$ref": "#/components/schemas/CatalogsRetailProductGroup" }, { "$ref": "#/components/schemas/CatalogsHotelProductGroup" }, { "$ref": "#/components/schemas/CatalogsCreativeAssetsProductGroup" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailProductGroup", "HOTEL": "#/components/schemas/CatalogsHotelProductGroup", "CREATIVE_ASSETS": "#/components/schemas/CatalogsCreativeAssetsProductGroup" } } }, "CatalogsCreativeAssetsProductGroup": { "type": "object", "title": "creative_assets_product_group", "properties": { "catalog_type": { "type": "string", "enum": [ "CREATIVE_ASSETS" ] }, "id": { "description": "ID of the creative assets product group.", "example": "443727193917", "type": "string", "pattern": "^\\d+$" }, "name": { "description": "Name of creative assets product group", "example": "Most Popular", "type": "string" }, "description": { "type": "string", "nullable": true }, "filters": { "$ref": "#/components/schemas/CatalogsCreativeAssetsProductGroupFilters" }, "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": { "description": "Catalog id pertaining to the creative assets product group.", "type": "string", "pattern": "^\\d+$" } }, "required": [ "id", "filters", "catalog_type", "catalog_id" ] }, "CatalogsCreativeAssetsProductGroupFilters": { "description": "Object holding a group of filters for a creative assets product group", "title": "catalogs_product_group_filters", "type": "object", "anyOf": [ { "$ref": "#/components/schemas/CatalogsCreativeAssetsProductGroupFiltersAnyOf" }, { "$ref": "#/components/schemas/CatalogsCreativeAssetsProductGroupFiltersAllOf" } ] }, "CatalogsCreativeAssetsProductGroupFiltersAllOf": { "type": "object", "additionalProperties": false, "properties": { "all_of": { "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/CatalogsCreativeAssetsProductGroupFilterKeys" } } }, "required": [ "all_of" ] }, "CatalogsCreativeAssetsProductGroupFiltersAnyOf": { "type": "object", "additionalProperties": false, "properties": { "any_of": { "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/CatalogsCreativeAssetsProductGroupFilterKeys" } } }, "required": [ "any_of" ] }, "CatalogsCreativeAssetsProductGroupFilterKeys": { "title": "catalogs_product_group_keys", "anyOf": [ { "$ref": "#/components/schemas/CreativeAssetsIdFilter" }, { "$ref": "#/components/schemas/CustomLabel0Filter" }, { "$ref": "#/components/schemas/CustomLabel1Filter" }, { "$ref": "#/components/schemas/CustomLabel2Filter" }, { "$ref": "#/components/schemas/CustomLabel3Filter" }, { "$ref": "#/components/schemas/CustomLabel4Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory6Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory5Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory4Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory3Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory2Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory1Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory0Filter" }, { "$ref": "#/components/schemas/MediaTypeFilter" } ] }, "CatalogsCreativeAssetsProductGroupCreateRequest": { "type": "object", "title": "creative_assets_product_groups_create_request", "additionalProperties": false, "description": "Request object for creating a creative assets product group.", "properties": { "catalog_type": { "type": "string", "enum": [ "CREATIVE_ASSETS" ] }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "filters": { "$ref": "#/components/schemas/CatalogsCreativeAssetsProductGroupFilters" }, "catalog_id": { "description": "Catalog id pertaining to the creative assets product group.", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" } }, "required": [ "name", "filters", "catalog_id", "catalog_type" ] }, "CatalogsCreativeAssetsProductGroupUpdateRequest": { "type": "object", "title": "creative_assets_product_groups_update_request", "additionalProperties": false, "description": "Request object for updating a creative assets product group.", "properties": { "catalog_type": { "type": "string", "enum": [ "CREATIVE_ASSETS" ] }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "filters": { "$ref": "#/components/schemas/CatalogsCreativeAssetsProductGroupFilters" } } }, "CatalogsHotelProductGroup": { "type": "object", "title": "hotel_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": { "description": "Catalog id pertaining to the hotel product group.", "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": "retail_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": { "deprecated": true, "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" }, "catalog_id": { "description": "Catalog id pertaining to the retail product group.", "type": "string", "pattern": "^\\d+$" }, "feed_id": { "description": "id of the catalogs feed belonging to this catalog product group", "example": "2680059592705", "type": "string", "pattern": "^\\d+$", "nullable": true }, "country": { "type": "string", "nullable": true }, "locale": { "type": "string", "nullable": true } }, "required": [ "filters", "id", "catalog_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" ] }, "CatalogsRetailProductGroupCreateRequest": { "type": "object", "title": "retail_product_groups_create_request", "additionalProperties": false, "description": "Request object for creating a product group.", "properties": { "catalog_type": { "type": "string", "enum": [ "RETAIL" ], "description": "Retail catalog based product group is available only for selected partners at the moment. If you are not eligible, please use feed based one." }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "filters": { "$ref": "#/components/schemas/CatalogsProductGroupFiltersRequest" }, "catalog_id": { "description": "Catalog id pertaining to the retail product group.", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" }, "country": { "$ref": "#/components/schemas/Country" }, "locale": { "$ref": "#/components/schemas/CatalogsLocale" } }, "required": [ "name", "filters", "catalog_id", "catalog_type", "country", "locale" ] }, "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" } } }, "CatalogsRetailProductGroupUpdateRequest": { "type": "object", "title": "retail_product_groups_update_request", "additionalProperties": false, "description": "Request object for updating a retail product group.", "properties": { "catalog_type": { "type": "string", "enum": [ "RETAIL" ], "description": "Retail catalog based product group is available only for selected partners at the moment. If you are not eligible, please use feed based one." }, "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "filters": { "$ref": "#/components/schemas/CatalogsProductGroupFiltersRequest" }, "country": { "$ref": "#/components/schemas/Country" }, "locale": { "$ref": "#/components/schemas/CatalogsLocale" } } }, "CatalogsProductGroupCreateRequest": { "type": "object", "title": "retail feed based", "description": "Request object for creating a product group.", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_featured": { "deprecated": true, "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/MediaTypeFilter" }, { "$ref": "#/components/schemas/ProductType4Filter" }, { "$ref": "#/components/schemas/ProductType3Filter" }, { "$ref": "#/components/schemas/ProductType2Filter" }, { "$ref": "#/components/schemas/ProductType1Filter" }, { "$ref": "#/components/schemas/ProductType0Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory6Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory5Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory4Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory3Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory2Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory1Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory0Filter" }, { "$ref": "#/components/schemas/ProductGroupReferenceFilter" } ] }, "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" ] }, "CatalogsProductGroupMultipleMediaTypesCriteria": { "title": "catalogs_product_group_multiple_media_type_criteria", "type": "object", "additionalProperties": false, "properties": { "values": { "type": "array", "items": { "$ref": "#/components/schemas/MediaType" } }, "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" ] }, "CatalogsProductGroupProductCountsVertical": { "type": "object", "description": "Product counts for a CatalogsProductGroup", "properties": { "catalog_type": { "$ref": "#/components/schemas/CatalogsType" } }, "required": [ "catalog_type" ], "oneOf": [ { "$ref": "#/components/schemas/CatalogsRetailProductGroupProductCounts" }, { "$ref": "#/components/schemas/CatalogsHotelProductGroupProductCounts" }, { "$ref": "#/components/schemas/CatalogsCreativeAssetsProductGroupProductCounts" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailProductGroupProductCounts", "HOTEL": "#/components/schemas/CatalogsHotelProductGroupProductCounts", "CREATIVE_ASSETS": "#/components/schemas/CatalogsCreativeAssetsProductGroupProductCounts" } } }, "CatalogsHotelProductGroupProductCounts": { "title": "catalogs_hotel_product_group_product_counts", "description": "Product counts for a Hotel CatalogsProductGroup", "type": "object", "properties": { "catalog_type": { "type": "string", "enum": [ "HOTEL" ] }, "total": { "type": "number", "minimum": 0 } }, "required": [ "catalog_type", "total" ] }, "CatalogsCreativeAssetsProductGroupProductCounts": { "title": "catalogs_creative_assets_product_group_product_counts", "description": "Product counts for a Creative Assets CatalogsProductGroup", "type": "object", "properties": { "catalog_type": { "type": "string", "enum": [ "CREATIVE_ASSETS" ] }, "total": { "type": "number", "minimum": 0 }, "videos": { "type": "number", "minimum": 0 } }, "required": [ "catalog_type", "total", "videos" ] }, "CatalogsRetailProductGroupProductCounts": { "title": "catalogs_retail_product_group_product_counts", "description": "Product counts for a Retail CatalogsProductGroup", "type": "object", "properties": { "catalog_type": { "type": "string", "enum": [ "RETAIL" ] }, "in_stock": { "type": "number", "minimum": 0 }, "out_of_stock": { "type": "number", "minimum": 0 }, "preorder": { "type": "number", "minimum": 0 }, "total": { "type": "number", "minimum": 0 }, "videos": { "type": "number", "minimum": 0 } }, "required": [ "catalog_type", "in_stock", "out_of_stock", "preorder", "total" ] }, "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 feed based", "additionalProperties": false, "description": "Request object for updating a product group.", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_featured": { "deprecated": true, "description": "boolean indicator of whether the product group is being featured or not", "type": "boolean" }, "filters": { "$ref": "#/components/schemas/CatalogsProductGroupFiltersRequest" } } }, "CatalogsRetailProduct": { "type": "object", "properties": { "catalog_type": { "type": "string", "enum": [ "RETAIL" ] }, "metadata": { "$ref": "#/components/schemas/CatalogsRetailProductMetadata" }, "pin": { "$ref": "#/components/schemas/Pin" } }, "required": [ "catalog_type", "metadata", "pin" ] }, "CatalogsRetailProductMetadata": { "type": "object", "description": "Retail 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", "CREATIVE_ASSETS" ] }, "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" }, { "$ref": "#/components/schemas/CatalogsCreativeAssetsBatchRequest" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailBatchRequest", "HOTEL": "#/components/schemas/CatalogsHotelBatchRequest", "CREATIVE_ASSETS": "#/components/schemas/CatalogsCreativeAssetsBatchRequest" } } }, "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" ] }, "CatalogsCreativeAssetsItemErrorResponse": { "type": "object", "description": "Object describing a creative assets item error", "properties": { "catalog_type": { "$ref": "#/components/schemas/CatalogsType" }, "creative_assets_id": { "description": "The catalog creative assets 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" ] }, "CatalogsCreativeAssetsItemResponse": { "type": "object", "description": "Object describing a hotel record", "properties": { "catalog_type": { "$ref": "#/components/schemas/CatalogsType" }, "creative_assets_id": { "description": "The catalog creative assets 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/CatalogsCreativeAssetsAttributes" } }, "required": [ "catalog_type" ] }, "CreativeAssetsProcessingRecord": { "type": "object", "description": "Object describing an item processing record", "properties": { "creative_assets_id": { "description": "The catalog creative assets id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "errors": { "description": "Array with the validation errors for the item processing record.\nA non empty errors list causes the item processing to fail.", "items": { "$ref": "#/components/schemas/ItemValidationEvent" }, "type": "array" }, "warnings": { "description": "Array with the validation warnings for the item processing record", "items": { "$ref": "#/components/schemas/ItemValidationEvent" }, "type": "array" }, "status": { "$ref": "#/components/schemas/ItemProcessingStatus" } } }, "CatalogsRetailBatchRequest": { "type": "object", "description": "A request object that can have multiple operations on a single retail batch", "additionalProperties": false, "properties": { "catalog_type": { "type": "string", "enum": [ "RETAIL" ] }, "country": { "$ref": "#/components/schemas/Country" }, "language": { "description": "We recommend using the CatalogsLocale values.", "anyOf": [ { "$ref": "#/components/schemas/CatalogsLocale" }, { "$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" ] }, "attributes": { "$ref": "#/components/schemas/ItemAttributesRequest" } }, "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": [ "UPDATE" ] }, "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": [ "UPSERT" ] }, "attributes": { "$ref": "#/components/schemas/ItemAttributesRequest" } }, "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": [ "DELETE" ] } }, "required": [ "item_id", "operation" ] }, "CatalogsHotelBatchRequest": { "description": "Request object to update catalogs hotel items", "type": "object", "additionalProperties": false, "properties": { "catalog_type": { "type": "string", "enum": [ "HOTEL" ] }, "country": { "$ref": "#/components/schemas/Country" }, "language": { "description": "We recommend using the CatalogsLocale values.", "anyOf": [ { "$ref": "#/components/schemas/CatalogsLocale" }, { "$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" } } }, "CatalogsHotelProduct": { "type": "object", "properties": { "catalog_type": { "type": "string", "enum": [ "HOTEL" ] }, "metadata": { "$ref": "#/components/schemas/CatalogsHotelProductMetadata" }, "pin": { "$ref": "#/components/schemas/Pin" } }, "required": [ "catalog_type", "metadata", "pin" ] }, "CatalogsHotelProductMetadata": { "type": "object", "description": "Hotel product metadata entity", "properties": { "hotel_id": { "description": "The user-created unique ID that represents the hotel item.", "example": "123abc", "type": "string" } }, "required": [ "hotel_id" ] }, "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" } } }, "CatalogsCreativeAssetsProductMetadata": { "type": "object", "description": "Creative assets product metadata entity", "properties": { "creative_assets_id": { "description": "The user-created unique ID that represents the creative assets item.", "example": "123abc", "type": "string" }, "visibility": { "$ref": "#/components/schemas/CreativeAssetsVisibilityType" } }, "required": [ "creative_assets_id", "visibility" ] }, "CatalogsCreativeAssetsProduct": { "type": "object", "properties": { "catalog_type": { "type": "string", "enum": [ "CREATIVE_ASSETS" ] }, "metadata": { "$ref": "#/components/schemas/CatalogsCreativeAssetsProductMetadata" }, "pin": { "$ref": "#/components/schemas/Pin" } }, "required": [ "catalog_type", "metadata", "pin" ] }, "CreativeAssetsVisibilityType": { "description": "Creative assets visibility.", "nullable": false, "type": "string", "enum": [ "VISIBLE", "HIDDEN" ] }, "CatalogsCreativeAssetsBatchRequest": { "description": "Request object to update catalogs creative assets items", "type": "object", "additionalProperties": false, "properties": { "catalog_type": { "type": "string", "enum": [ "CREATIVE_ASSETS" ] }, "country": { "$ref": "#/components/schemas/Country" }, "language": { "description": "We recommend using the CatalogsLocale values.", "anyOf": [ { "$ref": "#/components/schemas/CatalogsLocale" }, { "$ref": "#/components/schemas/Language" } ] }, "items": { "minItems": 1, "maxItems": 1000, "type": "array", "description": "Array with creative assets item operations", "items": { "$ref": "#/components/schemas/CatalogsCreativeAssetsBatchItem" } }, "catalog_id": { "description": "Catalog id pertaining to the creative assets item. If not provided, default to oldest creative assets catalog", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" } }, "required": [ "catalog_type", "country", "language", "items" ] }, "CatalogsCreativeAssetsBatchItem": { "description": "Creative assets batch item", "type": "object", "anyOf": [ { "$ref": "#/components/schemas/CatalogsCreateCreativeAssetsItem" }, { "$ref": "#/components/schemas/CatalogsUpsertCreativeAssetsItem" }, { "$ref": "#/components/schemas/CatalogsUpdateCreativeAssetsItem" }, { "$ref": "#/components/schemas/CatalogsDeleteCreativeAssetsItem" } ], "discriminator": { "propertyName": "operation", "mapping": { "CREATE": "#/components/schemas/CatalogsCreateCreativeAssetsItem", "UPSERT": "#/components/schemas/CatalogsUpsertCreativeAssetsItem", "UPDATE": "#/components/schemas/CatalogsUpdateCreativeAssetsItem", "DELETE": "#/components/schemas/CatalogsDeleteCreativeAssetsItem" } } }, "CatalogsCreateCreativeAssetsItem": { "type": "object", "description": "A creative assets item to be created.", "properties": { "creative_assets_id": { "description": "The catalog creative assets id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "operation": { "type": "string", "enum": [ "CREATE" ] }, "attributes": { "$ref": "#/components/schemas/CatalogsCreativeAssetsAttributes" } }, "required": [ "creative_assets_id", "operation", "attributes" ] }, "CatalogsUpdateCreativeAssetsItem": { "type": "object", "description": "A creative assets item to be updated.", "properties": { "creative_assets_id": { "description": "The catalog creative assets item id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "operation": { "type": "string", "enum": [ "UPDATE" ] }, "attributes": { "$ref": "#/components/schemas/CatalogsUpdatableCreativeAssetsAttributes" } }, "required": [ "creative_assets_id", "operation", "attributes" ] }, "CatalogsUpsertCreativeAssetsItem": { "type": "object", "description": "A creative assets item to be upserted.", "properties": { "creative_assets_id": { "description": "The catalog creative assets id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "operation": { "type": "string", "enum": [ "UPSERT" ] }, "attributes": { "$ref": "#/components/schemas/CatalogsCreativeAssetsAttributes" } }, "required": [ "creative_assets_id", "operation", "attributes" ] }, "CatalogsDeleteCreativeAssetsItem": { "type": "object", "description": "A creative assets item to be deleted", "properties": { "creative_assets_id": { "description": "The catalog creative assets id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "operation": { "type": "string", "enum": [ "DELETE" ] } }, "required": [ "creative_assets_id", "operation" ] }, "CatalogsUpdatableCreativeAssetsAttributes": { "type": "object", "properties": { "title": { "description": "The name of the creative assets.", "type": "string" }, "description": { "description": "Brief description of the creative assets.", "type": "string" }, "link": { "description": "Link to the creative assets page.", "type": "string" }, "ios_deep_link": { "description": "IOS deep link to the creative assets page.", "type": "string", "nullable": true }, "android_deep_link": { "description": "Link to the creative assets page.", "type": "string", "nullable": true }, "google_product_category": { "description": "The categorization of the product based on the standardized Google Product Taxonomy. This is a set taxonomy. Both the text values and numeric codes are accepted.", "type": "string", "nullable": true }, "custom_label_0": { "description": "Custom grouping of creative assets.", "type": "string", "nullable": true }, "custom_label_1": { "description": "Custom grouping of creative assets.", "type": "string", "nullable": true }, "custom_label_2": { "description": "Custom grouping of creative assets.", "type": "string", "nullable": true }, "custom_label_3": { "description": "Custom grouping of creative assets.", "type": "string", "nullable": true }, "custom_label_4": { "description": "Custom grouping of creative assets.", "type": "string", "nullable": true }, "visibility": { "description": "Visibility of the creative assets. Must be one of the following values (upper or lowercase): ‘visible’, ‘hidden’.", "type": "string", "nullable": true } } }, "CatalogsCreativeAssetsAttributes": { "type": "object", "allOf": [ { "type": "object", "properties": { "image_link": { "type": "string", "description": "The creative assets image.", "example": "https://scene.example.com/image/image_v2.jpg" }, "video_link": { "type": "string", "description": "The creative assets video.", "example": "https://scene.example.com/image/image_v2.mp4" } } }, { "$ref": "#/components/schemas/CatalogsUpdatableCreativeAssetsAttributes" } ] }, "CatalogsVerticalProductGroupCreateRequest": { "type": "object", "title": "catalog based", "description": "Request object for creating a catalog based product group.", "oneOf": [ { "$ref": "#/components/schemas/CatalogsRetailProductGroupCreateRequest" }, { "$ref": "#/components/schemas/CatalogsHotelProductGroupCreateRequest" }, { "$ref": "#/components/schemas/CatalogsCreativeAssetsProductGroupCreateRequest" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailProductGroupCreateRequest", "HOTEL": "#/components/schemas/CatalogsHotelProductGroupCreateRequest", "CREATIVE_ASSETS": "#/components/schemas/CatalogsCreativeAssetsProductGroupCreateRequest" } } }, "CatalogsVerticalProductGroupUpdateRequest": { "type": "object", "title": "catalog based", "description": "Request object for updating a catalog based product group.", "oneOf": [ { "$ref": "#/components/schemas/CatalogsRetailProductGroupUpdateRequest" }, { "$ref": "#/components/schemas/CatalogsHotelProductGroupUpdateRequest" }, { "$ref": "#/components/schemas/CatalogsCreativeAssetsProductGroupUpdateRequest" } ], "discriminator": { "propertyName": "catalog_type", "mapping": { "RETAIL": "#/components/schemas/CatalogsRetailProductGroupUpdateRequest", "HOTEL": "#/components/schemas/CatalogsHotelProductGroupUpdateRequest", "CREATIVE_ASSETS": "#/components/schemas/CatalogsCreativeAssetsProductGroupUpdateRequest" } } }, "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.\n

    \n
  • add_to_cart
    • \n
  • checkout
    • \n
  • custom
    • \n
  • lead
    • \n
  • page_visit
    • \n
  • search
    • \n
  • signup
    • \n
  • view_category
    • \n
  • watch_video
    • \n
\n

\n", "type": "string", "example": "checkout" }, "action_source": { "description": "

\n The source indicating where the conversion event occurred.\n

    \n
  • app_android
    • \n
  • app_ios
    • \n
  • web
    • \n
  • offline
    • \n
\n

\n", "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. The string should be in the UTF-8 format.", "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. The string should be in the UTF-8 format.", "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. The string should be in the UTF-8 format.", "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. The string should be in the UTF-8 format.", "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. The string should be in the UTF-8 format.", "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. The string should be in the UTF-8 format.", "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. The string should be in the UTF-8 format.", "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. The string should be in the UTF-8 format.", "type": "array", "items": { "type": "string" }, "example": [ "0d248e82c62c9386878327d491c762a002152d42ab2c391a31c44d9f62675ddf" ] }, "db": { "description": "Sha256 hashes of user's date of birthday, given as year, month, and day. The string should be in the UTF-8 format.", "type": "array", "items": { "type": "string" }, "example": [ "d4426a0086d10f12ad265539ae8d54221dc67786053d511407204b76e99d7739" ] }, "ln": { "description": "Sha256 hashes of user's last name, in lowercase. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA. The string should be in the UTF-8 format.", "type": "array", "items": { "type": "string" }, "example": [ "7e546b3aa43f989dd359672e6c3409d4f9d4e8f155ae1e9b90ee060985468c19" ] }, "fn": { "description": "Sha256 hashes of user's first name, in lowercase. We highly recommend this on checkout events at least. It may improve reporting performance such as ROAS/CPA. The string should be in the UTF-8 format.", "type": "array", "items": { "type": "string" }, "example": [ "ec1e6a072231703f1bc41429052fff8c00a7e0c6aaec2e7107241ca8f3ceb6b2" ] }, "ct": { "description": "Sha256 hashes of user's city, in lowercase, and without spaces or punctuation. User residency city (mostly billing). The string should be in the UTF-8 format.", "type": "array", "items": { "type": "string" }, "example": [ "4ac01a129bfd10385c9278c2cf2c46fac5ab57350841234f587c8522a2e4ce36" ] }, "st": { "description": "Sha256 hashes of user's state, given as a two-letter code in lowercase. User residency state (mostly billing). The string should be in the UTF-8 format.", "type": "array", "items": { "type": "string" }, "example": [ "49a6d05b8e4b516656e464271d9dd38d0a7e0142f7f49546f4dabd2720cafc34" ] }, "zp": { "description": "Sha256 hashes of user's zipcode, only digits. User residency zipcode (mostly billing). The string should be in the UTF-8 format.", "type": "array", "items": { "type": "string" }, "example": [ "fd5f56b40a79a385708428e7b32ab996a681080a166a2206e750eb4819186145" ] }, "country": { "description": "Sha256 hashes of two-character ISO-3166 country code indicating the user's country, in lowercase. The string should be in the UTF-8 format.", "type": "array", "items": { "type": "string" }, "example": [ "9b202ecbc6d45c6d8901d989a918878397a3eb9d00e8f48022fc051b19d21a1d" ] }, "external_id": { "description": "Sha256 hashes of the unique id from the advertiser that identifies a user in their space, e.g. user id, loyalty id, etc. We highly recommend this on all events. It may improve reporting performance such as ROAS/CPA. The string should be in the UTF-8 format.", "type": "array", "items": { "type": "string" }, "example": [ "6a7a73766627eb611720883d5a11cc62b5bfee237b00a6658d78c50032ec4aee" ] }, "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": "