{ "openapi": "3.0.3", "info": { "version": "5.5.0", "title": "Pinterest REST API", "description": "Pinterest's REST API", "contact": { "name": "Pinterest, Inc.", "url": "https://developers.pinterest.com/", "email": "pinterest-api@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": "audiences", "description": "View, create, or update audiences." }, { "name": "boards", "description": "View, create, update, or delete information about boards." }, { "name": "campaigns", "description": "View, create or update campaigns." }, { "name": "catalogs", "description": "Manage information about shopping product catalogs and items." }, { "name": "customer_lists", "description": "View, create, or update customer lists." }, { "name": "keywords", "description": "View, create or update keywords." }, { "name": "media", "description": "Register and manage media uploads." }, { "name": "oauth", "description": "Generating and refreshing OAuth access tokens." }, { "name": "pins", "description": "View, create, update, or delete information about Pins." }, { "name": "product_group_promotions", "description": "Product Group Promotion" }, { "name": "resources", "description": "View, create or update resources." }, { "name": "terms", "description": "Get related and suggested terms." }, { "name": "terms_of_service", "description": "Get Terms Of Service" }, { "name": "user_account", "description": "Read-only information about user accounts associated with a given access token." } ], "paths": { "/oauth/token": { "post": { "summary": "Generate OAuth access token", "description": "Generate an OAuth access token by using an authorization code or a refresh token.\n\nSee Authentication for more.", "tags": [ "oauth" ], "operationId": "oauth/token", "security": [ { "basic": [] } ], "x-ratelimit-category": "org_read", "x-sandbox": { "enabled": false }, "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" } } } } } } }, "/user_account": { "get": { "summary": "Get user account", "description": "Get account information for the \"operation user_account\"\n- By default, the \"operation user_account\" is the token user_account.\n\nIf using Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\". See Understanding Business Access for more information.", "tags": [ "user_account" ], "operationId": "user_account/get", "security": [ { "pinterest_oauth2": [ "user_accounts:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": { "enabled": false }, "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": { "enabled": false }, "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_metric_types" }, { "$ref": "#/components/parameters/query_split_field_user_account" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsResponse" } } }, "description": "Success" }, "400": { "description": "Invalid user accounts analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid user accounts analytics parameters." } } } }, "403": { "description": "Not authorized to access the user account analytics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access the user account analytics." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user_account/analytics/top_pins": { "get": { "summary": "Get user account top pins analytics", "description": "Gets analytics data about a user's top pins (limited to the top 50).\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\".", "tags": [ "user_account" ], "operationId": "user_account/analytics/top_pins", "security": [ { "pinterest_oauth2": [ "pins:read", "user_accounts:read" ] } ], "x-ratelimit-category": "org_analytics", "x-sandbox": { "enabled": false }, "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_metric_types" }, { "$ref": "#/components/parameters/query_num_of_pins" }, { "$ref": "#/components/parameters/query_created_in_last_n_days" }, { "$ref": "#/components/parameters/query_ad_account_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TopPinsAnalyticsResponse" } } }, "description": "Success" }, "403": { "description": "Not authorized to access the user account analytics.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access the user account analytics." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/user_account/analytics/top_video_pins": { "get": { "summary": "Get user account top video pins analytics", "description": "Gets analytics data about a user's top video pins (limited to the top 50).\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the \"operation user_account\".", "tags": [ "user_account" ], "operationId": "user_account/analytics/top_video_pins", "security": [ { "pinterest_oauth2": [ "pins:read", "user_accounts:read" ] } ], "x-ratelimit-category": "org_analytics", "x-sandbox": { "enabled": false }, "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_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" } } } } } } }, "/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": false }, "requestBody": { "description": "Create a new Pin.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pin" } } } }, "responses": { "201": { "description": "Successful pin creation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Pin" } } } }, "400": { "description": "Invalid Pin parameters response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidPinUrl": { "value": { "code": 1, "message": "Whoops! It looks like you entered an invalid URL. Try creating a Pin again with a valid URL." } } } } } }, "403": { "description": "The Pin's image is too small, too large or is broken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "PinImageTooSmall": { "value": { "code": 233, "message": "Your image is too small. Please choose a larger image and try again." } }, "PinImageBroken": { "value": { "code": 235, "message": "Sorry, this image is broken. Please pick a different image." } } } } } }, "404": { "description": "Board or section not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "BoardNotFound": { "value": { "code": 40, "message": "Board not found." } }, "BoardSectionNotFound": { "value": { "code": 2031, "message": "Sorry! We couldn't find this board section." } } } } } }, "429": { "description": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits or if multiple write operations are applied to\nan object within a short time window.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 8, "message": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits or if multiple write operations are applied to\nan object within a short time window." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/pins/{pin_id}": { "get": { "summary": "Get Pin", "description": "Get a Pin owned by the \"operation user_account\" - or on a group board that has been shared with this account.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account:\n\n- For Pins on public or protected boards: Owner, Admin, Analyst, Campaign Manager.\n- For Pins on secret boards: Owner, Admin.", "tags": [ "pins" ], "operationId": "pins/get", "security": [ { "pinterest_oauth2": [ "boards:read", "pins:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_pin_id" }, { "$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.", "tags": [ "pins" ], "operationId": "pins/delete", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write", "pins:read", "pins:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_pin_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" } } } } } } }, "/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.", "tags": [ "pins" ], "operationId": "pins/save", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write", "pins:read", "pins:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_pin_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+$" }, "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" } } } } } } }, "/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.", "tags": [ "pins" ], "operationId": "pins/analytics", "security": [ { "pinterest_oauth2": [ "boards:read", "pins:read" ] } ], "x-ratelimit-category": "org_analytics", "x-sandbox": { "enabled": false }, "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/AnalyticsResponse" } } } }, "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" } } } } } } }, "/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\n\nOptional: Specify a privacy type (public, protected, or secret) to indicate which boards to return.\n- If no privacy is specified, all boards that can be returned (based on the scopes of the token and ad_account role if applicable) will be returned.", "tags": [ "boards" ], "operationId": "boards/list", "security": [ { "pinterest_oauth2": [ "boards:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": { "enabled": false }, "parameters": [ { "$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": [ "PUBLIC", "PROTECTED", "SECRET" ] } } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Boards", "items": { "$ref": "#/components/schemas/Board" } } } } ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create board", "description": "Create a board owned by the \"operation user_account\".\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": false }, "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- By default, the \"operation user_account\" is the token user_account.", "tags": [ "boards" ], "operationId": "boards/get", "security": [ { "pinterest_oauth2": [ "boards:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_board_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\".", "tags": [ "boards" ], "operationId": "boards/update", "security": [ { "pinterest_oauth2": [ "boards:read", "boards:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_board_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- 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": false }, "parameters": [ { "$ref": "#/components/parameters/path_board_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}/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.\n- By default, the \"operation user_account\" is the token user_account.", "tags": [ "boards" ], "operationId": "board_sections/list", "security": [ { "pinterest_oauth2": [ "boards:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Board sections", "items": { "$ref": "#/components/schemas/BoardSection" } } } } ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create board section", "description": "Create a board section on a board owned by the \"operation user_account\" - or on a group board that has been shared with this account.\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": false }, "parameters": [ { "$ref": "#/components/parameters/path_board_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.\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": false }, "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/path_board_section_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.\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": false }, "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/path_board_section_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.\n- By default, the \"operation user_account\" is the token user_account.", "tags": [ "boards" ], "operationId": "board_sections/list_pins", "security": [ { "pinterest_oauth2": [ "boards:read", "pins:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/path_board_section_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Pins", "items": { "$ref": "#/components/schemas/Pin" } } } } ] } } } }, "403": { "description": "Not authorized to access Pins on board section.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 403, "message": "Not authorized to access Pins on board section." } } } }, "404": { "description": "Board or section not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 404, "message": "Board or section not found." } } } }, "409": { "description": "Board section conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 409, "message": "Board section conflict." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/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- By default, the \"operation user_account\" is the token user_account.", "tags": [ "boards" ], "operationId": "boards/list_pins", "security": [ { "pinterest_oauth2": [ "boards:read", "pins:read" ] } ], "x-ratelimit-category": "org_read", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_board_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Pins", "items": { "$ref": "#/components/schemas/Pin" } } } } ] } } } }, "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" } } } } } } }, "/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": false }, "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Media", "items": { "$ref": "#/components/schemas/MediaUploadDetails" } } } } ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Register media upload", "description": "Register your intent to upload media\n\nThe response includes all of the information needed to upload the media\nto Pinterest.\n\nTo upload the media, make an HTTP POST request (using curl, for\nexample) to upload_url using the Content-Type header\nvalue. Send the media file's contents as the request's file\nparameter and also include all of the parameters from\nupload_parameters.\n\nLearn more about video Pin creation.", "tags": [ "media" ], "operationId": "media/create", "security": [ { "pinterest_oauth2": [ "pins:read", "pins:write" ] } ], "x-ratelimit-category": "org_write", "x-sandbox": { "enabled": false }, "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": false }, "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" } } } } } } }, "/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": false }, "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_include_shared_accounts" } ], "responses": { "200": { "description": "response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Ad accounts", "items": { "$ref": "#/components/schemas/AdAccount" } } } } ] } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "summary": "Create ad account", "description": "Create a new ad account. Different ad accounts can support different currencies, payment methods, etc.\nAn ad account is needed to create campaigns, ad groups, and ads; other accounts (your employees or partners) can be assigned business access and appropriate roles to access an ad account.

\nYou can set up up to 50 ad accounts per user. (The user must have a business account to create an ad account.)

\nFor more, see Create an advertiser account.", "tags": [ "ad_accounts" ], "operationId": "ad_accounts/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": { "enabled": false }, "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": false }, "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}/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.", "operationId": "ad_account/analytics", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": { "enabled": false }, "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}/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": false }, "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_campaign_ids" }, { "$ref": "#/components/parameters/query_entity_statuses" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignResponse" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid ad account campaign parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account campaign parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "campaigns" ] }, "post": { "summary": "Create campaigns", "description": "Create multiple new campaigns. Every campaign has its own campaign_id and houses one or more ad groups, which contain one or more ads.\nFor more, see Set up your campaign.

\nNote:\n- The values for 'lifetime_spend_cap' and 'daily_spend_cap' are microcurrency amounts based on the currency field set in the advertiser's profile. (e.g. USD)

\n

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

\n

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

\n

Equivalency equations, using dollars as an example currency:

\n\n

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

\n", "tags": [ "campaigns" ], "operationId": "campaigns/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "description": "Array of campaigns.", "required": true, "content": { "application/json": { "schema": { "type": "array", "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": false }, "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "description": "Array of campaigns.", "required": true, "content": { "application/json": { "schema": { "type": "array", "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/{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": false }, "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}/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.", "operationId": "campaigns/analytics", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": { "enabled": false }, "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}/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": false }, "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_campaign_ids" }, { "$ref": "#/components/parameters/query_ad_group_ids" }, { "$ref": "#/components/parameters/query_entity_statuses" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_translate_interests_to_names" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdGroupResponse" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid ad account group parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account group parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_groups" ] }, "post": { "summary": "Create ad groups", "description": "Create multiple new ad groups. All ads in a given ad group will have the same budget, bid, run dates, targeting, and placement (search, browse, other). For more information, click here.

\nNote:\n- 'bid_in_micro_currency' and 'budget_in_micro_currency' should be expressed in microcurrency amounts based on the currency field set in the advertiser's profile.

\n

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

\n

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

\n

Equivalency equations, using dollars as an example currency:

\n\n

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

\n\n- Ad groups belong to ad campaigns. Some types of campaigns (e.g. budget optimization) have limits on the number of ad groups they can hold. If you exceed those limits, you will get an error message.", "operationId": "ad_groups/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": { "enabled": false }, "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": false }, "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/{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": false }, "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_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.", "operationId": "ad_groups/analytics", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": { "enabled": false }, "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}/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": false }, "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_campaign_ids" }, { "$ref": "#/components/parameters/query_ad_group_ids" }, { "$ref": "#/components/parameters/query_ad_ids" }, { "$ref": "#/components/parameters/query_entity_statuses" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdResponse" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid ad account ads parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account ads parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ads" ] }, "post": { "description": "Create multiple new ads. Request must contain ad_group_id, creative_type, and the source Pin pin_id.", "operationId": "ads/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": { "enabled": false }, "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": false }, "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/{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": false }, "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}/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.", "operationId": "ads/analytics", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_start_date" }, { "$ref": "#/components/parameters/query_end_date" }, { "$ref": "#/components/parameters/query_ad_ids_required" }, { "$ref": "#/components/parameters/query_columns" }, { "$ref": "#/components/parameters/query_granularity" }, { "$ref": "#/components/parameters/query_conversion_attribution_click_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_engagement_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_view_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_conversion_report_time" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdsAnalyticsResponse" } } }, "description": "Success" }, "400": { "description": "Invalid ad account ads analytics parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account ads analytics parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ads" ] } }, "/ad_accounts/{ad_account_id}/ad_previews": { "post": { "summary": "Create ad preview with pin or image", "description": "Create an ad preview given an ad account ID and either an existing organic pin ID or the URL for an image to be used to create the Pin and the ad.

\nIf you are creating a preview from an existing Pin, that Pin must be promotable: that is, it must have a clickthrough link and meet other requirements. (See Ads Overview.)

\nYou can view the returned preview URL on a webpage or iframe for 7 days, after which the URL expires.", "tags": [ "ads" ], "operationId": "ad_previews/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": { "enabled": false }, "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}/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": false }, "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}/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.", "operationId": "product_groups/analytics", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": { "enabled": false }, "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 and it's valid for an 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": { "enabled": false }, "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.", "operationId": "analytics/create_report", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": { "enabled": false }, "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}/audiences": { "get": { "summary": "List audiences", "description": "This endpoint is currently in beta and not available to all apps. Learn more.

\nGet list of audiences for the ad account.", "operationId": "audiences/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_audience_ids" }, { "$ref": "#/components/parameters/query_audience_type" }, { "$ref": "#/components/parameters/query_audience_types" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_entity_statuses" }, { "$ref": "#/components/parameters/query_flatten_rule" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_order_by" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_search_query" }, { "$ref": "#/components/parameters/query_start_index" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Audience" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid ad account audience parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid ad account audience parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "audiences" ] }, "post": { "description": "This endpoint is currently in beta and not available to all apps. Learn more.

\nCreate 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": { "enabled": false }, "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": "This endpoint is currently in beta and not available to all apps. Learn more.

\nGet a specific audience given the audience ID.", "operationId": "audiences/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": { "enabled": false }, "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": "This endpoint is currently in beta and not available to all apps. Learn more.

\nUpdate (edit or remove) an existing targeting audience.", "operationId": "audiences/update", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": { "enabled": false }, "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}/customer_lists": { "post": { "description": "This endpoint is currently in beta and not available to all apps. Learn more.

\n

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": { "enabled": false }, "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": "This endpoint is currently in beta and not available to all apps. Learn more.

\n

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": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerList" } } } } ] } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Get customer lists", "tags": [ "customer_lists" ] } }, "/ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}": { "get": { "summary": "Get customer list", "description": "This endpoint is currently in beta and not available to all apps. Learn more.

\nGets 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": { "enabled": false }, "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": "This endpoint is currently in beta and not available to all apps. Learn more.

\n

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

\n

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

\n

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

", "operationId": "customer_lists/update", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": { "enabled": false }, "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 lists", "tags": [ "customer_lists" ] } }, "/ad_accounts/{ad_account_id}/keywords": { "get": { "summary": "Get keywords", "description": "This endpoint is currently in beta and not available to all apps. Learn more.

\n

Get a list of keywords based on the filters provided.

", "operationId": "keywords/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_campaign_id" }, { "$ref": "#/components/parameters/query_ad_group_id" }, { "$ref": "#/components/parameters/query_match_types" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Keywords", "items": { "$ref": "#/components/schemas/KeywordsResponse" } } } } ] } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "keywords" ] }, "post": { "summary": "Create keywords", "description": "This endpoint is currently in beta and not available to all apps. Learn more.

\nCreate keywords.", "operationId": "keywords/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": { "enabled": false }, "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": "This endpoint is currently in beta and not available to all apps. Learn more.

\n

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": false }, "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}/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": { "enabled": false }, "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/ProductGroupPromotionArrayResponse" } } }, "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": { "enabled": false }, "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": { "type": "array", "items": { "$ref": "#/components/schemas/ProductGroupPromotionUpdateResponseItem" } } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Update 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_promotion/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": { "enabled": false }, "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/ProductGroupPromotion" } } }, "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" ] } }, "/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": false }, "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" } } } } } } }, "/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": false }, "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" ] } }, "/catalogs/feeds": { "get": { "x-ratelimit-category": "catalogs_read", "summary": "List feeds", "description": "Fetch feeds owned by the \"operating user_account\".\n\nLearn more", "operationId": "feeds/list", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/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 \"operating user_account\".\n\nLearn more", "operationId": "feeds/create", "security": [ { "pinterest_oauth2": [ "catalogs:read", "catalogs:write" ] } ], "x-sandbox": { "enabled": false }, "requestBody": { "description": "Request object used to created a feed.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsFeedsCreateRequest" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsFeed" } } }, "description": "Success" }, "400": { "description": "Invalid feed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "Invalid request: ..." } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "403": { "description": "Business account required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "BusinessAccountRequired": { "value": { "code": 654, "message": "You must have a business account to operate as merchant." } }, "MerchantDisapproved": { "value": { "code": 2625, "message": "Sorry, you cannot perform this action. Account is disapproved." } } } } } }, "409": { "description": "User website required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UserWebsiteRequired": { "value": { "code": 4168, "message": "User does not have a website." } }, "UserWebsiteNotVerified": { "value": { "code": 4169, "message": "User does not have a verified website." } } } } } }, "422": { "description": "Unique feed name is required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "FeedDuplicatedName": { "value": { "code": 4170, "message": "The feed name already exists." } } } } } }, "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 \"operating user_account\".\n\nLearn more", "operationId": "feeds/get", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_catalogs_feed_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 \"operating user_account\".\n\nLearn more", "operationId": "feeds/update", "security": [ { "pinterest_oauth2": [ "catalogs:read", "catalogs:write" ] } ], "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_catalogs_feed_id" } ], "requestBody": { "description": "Request object used to update a feed.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsFeedsUpdateRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsFeed" } } }, "description": "Success" }, "400": { "description": "Invalid feed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "Invalid request: ..." } } } } } }, "403": { "description": "Forbidden. Account not approved for feed mutations yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MerchantDisapproved": { "value": { "code": 2625, "message": "Sorry, you cannot perform this action. Account is disapproved." } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "Sorry, you cannot perform this action. Account is under review." } } } } } }, "404": { "description": "Data feed not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "FeedNotFound": { "value": { "code": 4161, "message": "Sorry! We could not find your catalogs feed." } } } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] }, "delete": { "x-ratelimit-category": "catalogs_write", "summary": "Delete feed", "description": "Delete a feed owned by the \"operating user_account\".\n\nLearn more", "operationId": "feeds/delete", "security": [ { "pinterest_oauth2": [ "catalogs:read", "catalogs:write" ] } ], "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_catalogs_feed_id" } ], "responses": { "204": { "description": "Feed deleted successfully." }, "400": { "description": "Invalid feed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "'feed_id' value '1511851494501_' must match the pattern: ^\\d+$\"}" } } } } } }, "403": { "description": "Forbidden. Account not approved for feed mutations yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MerchantDisapproved": { "value": { "code": 2625, "message": "Sorry, you cannot perform this action. Account is disapproved." } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "Sorry, you cannot perform this action. Account is under review." } } } } } }, "404": { "description": "Data feed not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "FeedNotFound": { "value": { "code": 4161, "message": "Sorry! We could not find your catalogs feed." } } } } } }, "409": { "description": "Conflict. Can't delete a feed with active promotions.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "FeedHasActivePromotions": { "value": { "code": 4162, "message": "We can't disable a Product Group with active promotions." } } } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/feeds/{feed_id}/processing_results": { "get": { "x-ratelimit-category": "catalogs_read", "summary": "List processing results for a given feed", "description": "Fetch a feed processing results owned by the owner 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\nLearn more", "operationId": "feed_processing_results/list", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_catalogs_feed_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogsFeedProcessingResult" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "Parameter 'page_size' was not numeric (was 3e)\"" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "404": { "description": "Feed not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "FeedNotFound": { "value": { "code": 4161, "message": "Sorry! We could not find your catalogs feed." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/processing_results/{processing_result_id}/item_issues": { "get": { "x-ratelimit-category": "catalogs_read", "summary": "List item issues for a given processing result", "description": "List item validation issues for a given feed processing result. 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\nLearn more", "operationId": "items_issues/list", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-sandbox": { "enabled": false }, "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" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogsItemValidationIssues" } } } } ] } } }, "description": "Success" }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "404": { "description": "Processing Result not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "ProcessingResultFound": { "value": { "code": 4184, "message": "Sorry! We could not find your processing result." } } } } } }, "501": { "description": "Not implemented.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "NotImplemented": { "value": { "code": 4181, "message": "Not implemented at the moment. Please, see documentation." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/items": { "get": { "summary": "Get catalogs items", "description": "Get the items of the catalog created by the \"operating user_account\". See detailed documentation here.", "operationId": "items/get", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-ratelimit-category": "catalogs_read", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/query_catalogs_items_country" }, { "$ref": "#/components/parameters/query_catalogs_items" }, { "$ref": "#/components/parameters/query_catalogs_items_language" } ], "responses": { "200": { "description": "Response containing the requested catalogs items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsItems" } } } }, "401": { "description": "Not authorized to access catalogs items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "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/{batch_id}": { "get": { "summary": "Get catalogs items batch", "description": "Get a single catalogs items batch created by the \"operating user_account\". See detailed documentation here.", "operationId": "items_batch/get", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-ratelimit-category": "catalogs_read", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_catalogs_items_batch_id" } ], "responses": { "200": { "description": "Response containing the requested catalogs items batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsItemsBatch" } } } }, "401": { "description": "Not authorized to access catalogs items batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "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" } } } }, "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. See detailed documentation here.", "operationId": "items_batch/post", "x-ratelimit-category": "catalogs_write", "x-sandbox": { "enabled": false }, "security": [ { "pinterest_oauth2": [ "catalogs:read", "catalogs:write" ] } ], "requestBody": { "description": "Request object used to create catalogs items in a batch", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsItemsBatchRequest" } } } }, "responses": { "200": { "description": "Response containing the requested catalogs items batch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsItemsBatch" } } } }, "401": { "description": "Not authorized to post catalogs items", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "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/products/get_by_product_group_filters": { "post": { "x-ratelimit-category": "catalogs_read", "summary": "List filtered products", "description": "List products Pins that meet the criteria specified in the Catalogs Product Group Filter given in the request.\nNote: This endpoint has been implemented in POST to allow for complex filters. This specific POST endpoint is designed to be idempotent.\n\nLearn more", "operationId": "products_by_product_group_filter/list", "security": [ { "pinterest_oauth2": [ "boards:read", "catalogs:read", "pins:read" ] } ], "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "requestBody": { "description": "Object holding a group of filters for a catalog product group", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsListProductsByFilterRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Pins", "items": { "$ref": "#/components/schemas/CatalogsProduct" } } } } ] } } }, "description": "Success" }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "409": { "description": "Conflict. Can't get products.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsMerchantNotCreated": { "value": { "code": 4182, "message": "Can't acccess this feature without an existing catalog." } }, "CatalogsProductGroupFiltersInvalid": { "value": { "code": 4183, "message": "Catalog product group filters failed validation, please ensure all filters are set correctly." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/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.\n\nLearn more", "operationId": "catalogs_product_groups/get", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_catalogs_product_group_id" } ], "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsProductGroup" } } }, "description": "Success" }, "400": { "description": "Invalid catalogs product group id parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "'product_group_id' value '11851494501_' must match the pattern: ^\\d+$\"}" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "403": { "description": "Forbidden. Account not approved for catalog product group mutations yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MerchantDisapproved": { "value": { "code": 2625, "message": "Sorry, you cannot perform this action. Account is disapproved." } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "Sorry, you cannot perform this action. Account is under review." } } } } } }, "404": { "description": "Catalogs product group not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsProductGroupNotFound": { "value": { "code": 4180, "message": "Sorry! We could not find your catalogs product group." } } } } } }, "409": { "description": "Conflict. Can't get a catalogs product group without an existing catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsMerchantNotCreated": { "value": { "code": 4182, "message": "Can't acccess this feature without an existing catalog." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] }, "delete": { "x-ratelimit-category": "catalogs_write", "summary": "Delete product group", "description": "Delete a product group from being in use in Catalogs.\n\nLearn more", "operationId": "catalogs_product_groups/delete", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_catalogs_product_group_id" } ], "security": [ { "pinterest_oauth2": [ "catalogs:write" ] } ], "responses": { "204": { "description": "Catalogs Product Group deleted successfully." }, "400": { "description": "Invalid catalogs product group id parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "'product_group_id' value '11851494501_' must match the pattern: ^\\d+$\"}" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "403": { "description": "Forbidden. Account not approved for catalog product group mutations yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MerchantDisapproved": { "value": { "code": 2625, "message": "Sorry, you cannot perform this action. Account is disapproved." } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "Sorry, you cannot perform this action. Account is under review." } } } } } }, "404": { "description": "Catalogs product group not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsProductGroupNotFound": { "value": { "code": 4180, "message": "Sorry! We could not find your catalogs product group." } } } } } }, "409": { "description": "Conflict. Can't delete this catalogs product group.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsProductGroupHasActivePromotions": { "value": { "code": 4176, "message": "We can't delete a Catalogs Product Group with active promotions." } }, "CannotAlterAutoGeneratedCatalogsProductGroup": { "value": { "code": 4177, "message": "You cannot alter an auto generated catalogs product group." } }, "CatalogsMerchantNotCreated": { "value": { "code": 4182, "message": "Can't access this feature without an existing catalog." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] }, "patch": { "x-ratelimit-category": "catalogs_write", "summary": "Update product group", "description": "Update product group to use in Catalogs.\n\nLearn more", "operationId": "catalogs_product_groups/update", "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_catalogs_product_group_id" } ], "security": [ { "pinterest_oauth2": [ "catalogs:write" ] } ], "requestBody": { "description": "Request object used to Update a catalogs product group.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsProductGroupUpdateRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsProductGroup" } } }, "description": "Success" }, "400": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "'product_group_id' value '11851494501_' must match the pattern: ^\\d+$\"}" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "403": { "description": "Forbidden. Account not approved for catalog product group mutations yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MerchantDisapproved": { "value": { "code": 2625, "message": "Sorry, you cannot perform this action. Account is disapproved." } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "Sorry, you cannot perform this action. Account is under review." } } } } } }, "404": { "description": "Catalogs product group not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsProductGroupNotFound": { "value": { "code": 4180, "message": "Sorry! We could not find your catalogs product group." } } } } } }, "409": { "description": "Conflict. Can't update this catalogs product group to this value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CannotAlterAutoGeneratedCatalogsProductGroup": { "value": { "code": 4177, "message": "You cannot alter an auto generated catalogs product group." } }, "CatalogsProductGroupFiltersAlreadyExist": { "value": { "code": 4178, "message": "A catalogs product group with these filters already exists for this feed." } }, "CatalogsProductGroupNameAlreadyExist": { "value": { "code": 4179, "message": "A catalogs product group with this name already exists for this feed." } }, "CatalogsMerchantNotCreated": { "value": { "code": 4182, "message": "Can't access this feature without an existing catalog." } }, "CatalogsProductGroupFiltersInvalid": { "value": { "code": 4183, "message": "Catalog product group filters failed validation, please ensure all filters are set correctly." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/product_groups/{product_group_id}/products": { "get": { "x-ratelimit-category": "catalogs_read", "summary": "List products", "description": "Get a list of product pins for a given Catalogs Product Group Id.\n\nLearn more", "operationId": "catalogs_product_group_pins/list", "security": [ { "pinterest_oauth2": [ "boards:read", "catalogs:read", "pins:read" ] } ], "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/path_catalogs_product_group_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "description": "Pins", "items": { "$ref": "#/components/schemas/CatalogsProduct" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "'product_group_id' value '11851494501_' must match the pattern: ^\\d+$\"}" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "404": { "description": "Catalogs product group not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsProductGroupNotFound": { "value": { "code": 4180, "message": "Sorry! We could not find your catalogs product group." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/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.\n\nLearn more", "operationId": "catalogs_product_groups/product_counts_get", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/path_catalogs_product_group_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsProductGroupProductCounts" } } }, "description": "Success" }, "404": { "description": "Product Group Not Found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsProductGroupNotFound": { "value": { "code": 4180, "message": "Sorry! We could not find your catalogs product group." } } } } } }, "409": { "description": "Can't access this feature without an existing catalog.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsMerchantNotCreated": { "value": { "code": 4182, "message": "Can't access this feature without an existing catalog." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/catalogs/product_groups": { "get": { "x-ratelimit-category": "catalogs_read", "summary": "List product groups", "description": "Get a list of product groups for a given Catalogs Feed Id.\n\nLearn more", "operationId": "catalogs_product_groups/list", "security": [ { "pinterest_oauth2": [ "catalogs:read" ] } ], "x-sandbox": { "enabled": false }, "parameters": [ { "$ref": "#/components/parameters/query_catalogs_feed_id" }, { "$ref": "#/components/parameters/query_bookmark" }, { "$ref": "#/components/parameters/query_page_size" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogsProductGroup" } } } } ] } } }, "description": "Success" }, "400": { "description": "Invalid feed parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "'feed_id' value '1511851494501_' must match the pattern: ^\\d+$\"}" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "403": { "description": "Forbidden. Account not approved for catalog product group mutations yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MerchantDisapproved": { "value": { "code": 2625, "message": "Sorry, you cannot perform this action. Account is disapproved." } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "Sorry, you cannot perform this action. Account is under review." } } } } } }, "404": { "description": "Data feed not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "FeedNotFound": { "value": { "code": 4161, "message": "Sorry! We could not find your catalogs feed." } } } } } }, "409": { "description": "Conflict. Can't create this catalogs product group with this value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsMerchantNotCreated": { "value": { "code": 4182, "message": "Can't access this feature without an existing catalog." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] }, "post": { "x-ratelimit-category": "catalogs_write", "summary": "Create product group", "description": "Create product group to use in Catalogs.\n\nLearn more", "operationId": "catalogs_product_groups/create", "security": [ { "pinterest_oauth2": [ "catalogs:write" ] } ], "x-sandbox": { "enabled": false }, "requestBody": { "description": "Request object used to created a catalogs product group.", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsProductGroupCreateRequest" } } } }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogsProductGroup" } } }, "description": "Success" }, "400": { "description": "Invalid body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "InvalidRequest": { "value": { "code": 1, "message": "'feed_id' value '1511851494501_' must match the pattern: ^\\d+$\"}" } } } } } }, "401": { "description": "Unauthorized access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "UnauthorizedAccess": { "value": { "code": 29, "message": "You are not permitted to access that resource." } } } } } }, "403": { "description": "Forbidden. Account not approved for catalog product group mutations yet.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "MerchantDisapproved": { "value": { "code": 2625, "message": "Sorry, you cannot perform this action. Account is disapproved." } }, "MerchantUnderReview": { "value": { "code": 2626, "message": "Sorry, you cannot perform this action. Account is under review." } } } } } }, "409": { "description": "Conflict. Can't create this catalogs product group with this value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "CatalogsProductGroupFiltersAlreadyExist": { "value": { "code": 4178, "message": "A catalogs product group with these filters already exists for this feed." } }, "CatalogsProductGroupNameAlreadyExist": { "value": { "code": 4179, "message": "A catalogs product group with this name already exists for this feed." } }, "CatalogsMerchantNotCreated": { "value": { "code": 4182, "message": "Can't access this feature without an existing catalog." } }, "CatalogsProductGroupFiltersInvalid": { "value": { "code": 4183, "message": "Catalog product group filters failed validation, please ensure all filters are set correctly." } } } } } }, "default": { "description": "Unexpected error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "catalogs" ] } }, "/resources/ad_account_countries": { "get": { "summary": "Get ad accounts countries", "description": "This endpoint is currently in beta and not available to all apps. Learn more.

\nGet Ad Accounts countries", "operationId": "ad_account_countries/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": { "enabled": false }, "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/targeting/interests/{interest_id}": { "get": { "summary": "Get interest details", "description": "This endpoint is currently in beta and not available to all apps. Learn more.

\n

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": false }, "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": "This endpoint is currently in beta and not available to all apps. Learn more.

\n

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": false }, "parameters": [ { "$ref": "#/components/parameters/path_targeting_type" }, { "$ref": "#/components/parameters/query_client_id" }, { "$ref": "#/components/parameters/query_oauth_signature" }, { "$ref": "#/components/parameters/query_timestamp" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TargetingOptionResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "resources" ] } }, "/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": false }, "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" } } } } } } } }, "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.", "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" } } } }, "conversion_token": { "type": "http", "scheme": "bearer", "description": "This security scheme only applies to the conversion events endpoint (POST /ad_accounts/{ad_account_id}/events). This endpoint requires a bearer token generated via Ads Manager (ads.pinterest.com)." }, "basic": { "type": "http", "scheme": "basic" } }, "schemas": { "Error": { "title": "Error", "type": "object", "properties": { "code": { "type": "integer" }, "message": { "type": "string" } }, "required": [ "code", "message" ] }, "Paginated": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object" } }, "bookmark": { "type": "string", "nullable": true } }, "required": [ "items" ] }, "Account": { "type": "object", "readOnly": true, "properties": { "account_type": { "description": "Type of account", "type": "string", "enum": [ "PINNER", "BUSINESS" ] }, "profile_image": { "type": "string" }, "website_url": { "type": "string" }, "username": { "type": "string" } } }, "AdCommon": { "type": "object", "description": "Creation fields", "properties": { "ad_group_id": { "description": "ID of the ad group that contains the ad.", "example": "2680059592705", "type": "string", "pattern": "^(AG)?\\d+$" }, "android_deep_link": { "description": "Deep link URL for Android devices. Not currently available. Using this field will generate an error.", "nullable": true, "type": "string" }, "carousel_android_deep_links": { "description": "Comma-separated deep links for the carousel pin on Android.", "type": "array", "nullable": true, "items": { "type": "string" } }, "carousel_destination_urls": { "description": "Comma-separated destination URLs for the carousel pin to promote.", "type": "array", "nullable": true, "items": { "type": "string" } }, "carousel_ios_deep_links": { "description": "Comma-separated deep links for the carousel pin on iOS.", "type": "array", "nullable": true, "items": { "type": "string" } }, "click_tracking_url": { "description": "Tracking url for the ad clicks.", "type": "string", "nullable": true }, "creative_type": { "$ref": "#/components/schemas/CreativeType" }, "destination_url": { "description": "Destination URL.", "type": "string", "nullable": true }, "ios_deep_link": { "description": "Deep link URL for iOS devices. Not currently available. Using this field will generate an error.", "type": "string", "nullable": true }, "is_pin_deleted": { "description": "Is original pin deleted?", "example": false, "type": "boolean" }, "is_removable": { "description": "Is pin repinnable?", "example": false, "type": "boolean" }, "name": { "description": "Name of the ad - 255 chars max.", "type": "string", "nullable": true }, "pin_id": { "description": "Pin ID.", "example": "394205773611545468", "type": "string", "pattern": "^\\d+$" }, "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 } } }, "AdCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/AdCommon" }, { "type": "object", "title": "Request schema for creating ads", "required": [ "ad_group_id", "pin_id", "creative_type" ] } ] }, "AnalyticsResponse": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/AnalyticsMetricsResponse" } }, "AnalyticsMetricsResponse": { "type": "object", "properties": { "daily_metrics": { "description": "Array with the requested daily metric records", "items": { "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" } } }, "type": "array" }, "summary_metrics": { "description": "The metric name and value over the requested period for each requested metric", "type": "object", "additionalProperties": { "type": "number" }, "example": { "ENGAGEMENT": 100, "CLICKTHROUGH_RATE": 0.2, "CLICKTHROUGH": 200, "CLOSEUP": 37, "CLOSEUP_RATE": 0.5, "ENGAGEMENT_RATE": 0.2, "SAVE": 20, "SAVE_RATE": 0.18, "IMPRESSION": 240 } } } }, "AdGroupSummaryStatus": { "type": "string", "description": "Summary status for ad group", "example": "RUNNING", "enum": [ "RUNNING", "PAUSED", "NOT_STARTED", "COMPLETED", "ADVERTISER_DISABLED", "ARCHIVED" ] }, "AdResponse": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/AdCommon" }, { "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" } } } ] }, "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" } } }, "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" ] }, "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" ] }, "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", "AUDIENCE_EXCLUDE", "GEO", "AGE_BUCKET", "REGION" ] }, "ActionType": { "type": "string", "description": "Ad group billable event type.", "example": "CLICKTHROUGH", "enum": [ "CLICKTHROUGH", "IMPRESSION", "VIDEO_V_50_MRC", "BILLABLE_ENGAGEMENT" ] }, "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 }, "bid_strategy_type": { "type": "string", "enum": [ "AUTOMATIC_BID", "MAX_BID", "TARGET_AVG" ] }, "budget_type": { "$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": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Ad group targeting specification defining the ad group target audience. For example, '{\"APPTYPE\":[\"iphone\"], \"GENDER\":[\"male\"], \"LOCALE\":[\"en-US\"], \"LOCATION\":[\"501\"], \"AGE_BUCKET\":[\"25-34\"]}'" }, "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": { "description": "Enable auto-targeting for ad group. Also known as \"expanded targeting\".", "type": "boolean", "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" } ], "description": "Pacing delivery type. With ACCELERATED, an ad group budget is spent as fast as possible. With STANDARD, an ad group budget is spent smoothly over a day." }, "campaign_id": { "description": "Campaign ID of the ad group.", "type": "string", "pattern": "^[C]?\\d+$", "example": "626736533506" }, "billable_event": { "$ref": "#/components/schemas/ActionType" } } }, "AdGroupCreateRequest": { "allOf": [ { "$ref": "#/components/schemas/AdGroupCommon" }, { "type": "object", "properties": { "targeting_spec": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/TargetingSpec" } ] } }, "required": [ "billable_event", "campaign_id", "name" ] } ] }, "AdGroupArrayResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdGroupArrayResponseElement" } } } }, "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." } } } ] }, "AdGroupArrayResponseElement": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/AdGroupResponse" }, "exceptions": { "type": "array", "items": { "$ref": "#/components/schemas/Exception" } } } }, "AdGroupUpdateRequest": { "allOf": [ { "$ref": "#/components/schemas/AdGroupCommon" }, { "type": "object", "properties": { "id": { "description": "Ad group ID.", "type": "string", "pattern": "^\\d+$", "example": "2680060704746" } }, "required": [ "id" ] } ] }, "AdGroupsAnalyticsResponse": { "type": "array", "items": { "type": "object", "properties": { "AD_GROUP_ID": { "description": "The ID of the ad group that this metrics belongs to.", "type": "string", "pattern": "^\\d+$" }, "DATE": { "description": "Current metrics date. Only returned when granularity is a time-based value (`DAY`, `HOUR`, `WEEK`, `MONTH`)", "type": "string", "format": "date" } }, "required": [ "AD_GROUP_ID" ], "additionalProperties": true, "example": { "DATE": "2021-04-01", "AD_GROUP_ID": "547602124502", "SPEND_IN_DOLLAR": 30, "TOTAL_CLICKTHROUGH": 216 } } }, "AdAccountsCountryResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AdAccountsCountryResponseData" } } } }, "AdAccountsCountryResponseData": { "type": "object", "properties": { "code": { "$ref": "#/components/schemas/Country", "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" } } }, "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 24 hours. 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" }, "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" } } }, "country": { "$ref": "#/components/schemas/Country" }, "currency": { "$ref": "#/components/schemas/Currency" }, "permissions": { "title": "permissions", "type": "array", "items": { "type": "string", "nullable": true } } } }, "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" } } }, "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 } } }, "AdsAnalyticsGetAsyncResponse": { "type": "object", "properties": { "report_status": { "type": "string" }, "url": { "type": "string", "nullable": true }, "size": { "type": "number", "nullable": true } } }, "AdsAnalyticsCreateAsyncRequest": { "type": "object", "allOf": [ { "type": "object", "properties": { "start_date": { "description": "Metric report start date (UTC). Format: YYYY-MM-DD", "type": "string", "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$", "example": "2020-12-20" }, "end_date": { "description": "Metric report end date (UTC). Format: YYYY-MM-DD", "type": "string", "pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$", "example": "2020-12-20" }, "granularity": { "description": "TOTAL - metrics are aggregated over the specified date range.
DAY - metrics are broken down daily.
HOUR - metrics are broken down hourly.
WEEKLY - metrics are broken down weekly.
MONTHLY - metrics are broken down monthly", "type": "string", "allOf": [ { "$ref": "#/components/schemas/Granularity" } ] }, "click_window_days": { "description": "Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days.", "type": "integer", "allOf": [ { "$ref": "#/components/schemas/ConversionAttributionWindowDays" } ], "default": 30 }, "engagement_window_days": { "description": "Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days.", "type": "integer", "allOf": [ { "$ref": "#/components/schemas/ConversionAttributionWindowDays" } ], "default": 30 }, "view_window_days": { "description": "Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `1` day.", "type": "integer", "allOf": [ { "$ref": "#/components/schemas/ConversionAttributionWindowDays" } ], "default": 1 }, "conversion_report_time": { "description": "The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event.", "type": "string", "allOf": [ { "$ref": "#/components/schemas/ConversionReportTimeType" } ], "default": "TIME_OF_AD_ACTION" }, "attribution_types": { "description": "List of types of attribution for the conversion report", "type": "array", "items": { "$ref": "#/components/schemas/ConversionReportAttributionType" } } }, "required": [ "start_date", "end_date", "granularity" ] }, { "type": "object", "allOf": [ { "type": "object", "properties": { "campaign_ids": { "type": "array", "description": "List of campaign ids", "example": [ "12345678" ], "items": { "type": "string", "pattern": "^\\d+$" }, "maxItems": 500, "minItems": 1 } } }, { "type": "object", "properties": { "campaign_statuses": { "type": "array", "description": "List of status values for filtering", "example": [ "RUNNING", "PAUSED" ], "items": { "$ref": "#/components/schemas/CampaignSummaryStatus" }, "maxItems": 6, "minItems": 1 } } }, { "type": "object", "properties": { "campaign_objective_types": { "type": "array", "description": "List of values for filtering. [\"WEB_SESSIONS\"] in BETA.", "example": [ "AWARENESS", "VIDEO_VIEW" ], "items": { "$ref": "#/components/schemas/ObjectiveType" }, "maxItems": 6, "minItems": 1 } } }, { "type": "object", "properties": { "ad_group_ids": { "type": "array", "description": "List of ad group ids", "example": [ "12345678" ], "items": { "type": "string", "pattern": "^\\d+$" }, "maxItems": 500, "minItems": 1 } } }, { "type": "object", "properties": { "ad_group_statuses": { "type": "array", "description": "List of values for filtering", "example": [ "RUNNING", "PAUSED" ], "items": { "$ref": "#/components/schemas/AdGroupSummaryStatus" }, "maxItems": 6, "minItems": 1 } } }, { "type": "object", "properties": { "ad_ids": { "type": "array", "description": "List of ad ids", "example": [ "12345678" ], "items": { "type": "string", "pattern": "^\\d+$" }, "maxItems": 500, "minItems": 1 } } }, { "type": "object", "properties": { "ad_statuses": { "type": "array", "description": "List of values for filtering", "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", "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 report data", "type": "string", "allOf": [ { "$ref": "#/components/schemas/DataOutputFormat" } ], "default": "JSON" } } } ] }, "AdsAnalyticsCreateAsyncResponse": { "type": "object", "properties": { "report_status": { "type": "string" }, "token": { "type": "string" }, "message": { "type": "string", "nullable": true } } }, "AdUpdateRequest": { "allOf": [ { "$ref": "#/components/schemas/AdCommon" }, { "type": "object", "title": "AdUpdateRequest", "properties": { "id": { "type": "string", "example": "687195134316", "pattern": "^\\d+$", "description": "The ID of this ad.", "title": "id" } }, "required": [ "id" ] } ] }, "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 type", "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. 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" }, "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" } } }, "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 type. Values are case-sensitive." } ] } } } ] }, "AudienceDescription": { "title": "description", "description": "Audience description.", "type": "string", "example": "string" }, "AudienceInsightCategoryCommon": { "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" } } }, "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" ] } } }, "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": 30, "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" }, "AudienceType": { "description": "Audience type", "enum": [ "CUSTOMER_LIST", "VISITOR", "ENGAGEMENT", "ACTALIKE" ], "example": "ACTALIKE", "title": "AudienceType", "type": "string" }, "AudienceUpdateOperationType": { "title": "operation_type", "type": "string", "description": "Audience operation type (update or remove).", "example": "UPDATE", "default": "UPDATE", "enum": [ "UPDATE", "REMOVE" ] }, "AudienceUpdateRequest": { "allOf": [ { "$ref": "#/components/schemas/AudienceCommon" }, { "title": "AudienceUpdateRequest", "type": "object", "properties": { "description": { "$ref": "#/components/schemas/AudienceDescription" }, "operation_type": { "$ref": "#/components/schemas/AudienceUpdateOperationType" } } } ] }, "BatchOperation": { "description": "The operation performed by the batch", "example": "UPDATE", "type": "string", "enum": [ "UPDATE", "CREATE", "DELETE_DISCONTINUED" ] }, "BatchOperationStatus": { "description": "The status of the operation performed by the batch", "example": "PROCESSING", "type": "string", "enum": [ "PROCESSING", "COMPLETED" ] }, "BidFloor": { "example": { "bid_floors": [ 100000, 200000 ], "type": "bidfloor" }, "properties": { "bid_floors": { "description": "A list of bid floors in micro currency. For example, [100000, 200000]", "example": [ 100000, 200000 ], "items": { "type": "integer" }, "title": "bid_floors", "type": "array" }, "type": { "default": "bidfloor", "description": "Always the string 'bidfloor'", "example": "bidfloor", "title": "type", "type": "string" } }, "title": "BidFloor", "type": "object" }, "BidFloorRequest": { "example": { "targeting_spec": { "GEO": [ "BE-VOV" ], "LOCATION": [ "US" ], "LOCALE": [ "cs" ], "AGE_BUCKET": [ "25-34" ], "AUDIENCE_INCLUDE": [ "2542620905473" ], "SHOPPING_RETARGETING": [ { "lookback_window": 30, "exclusion_window": 14, "tag_types": [ 0, 6 ] }, { "lookback_window": 30, "exclusion_window": 14, "tag_types": [ 0, 6 ] } ], "GENDER": [ "male" ], "TARGETING_STRATEGY": [ "CHOOSE_YOUR_OWN" ], "APPTYPE": [ "iphone" ], "AUDIENCE_EXCLUDE": [ "2542620905475" ], "INTEREST": [ "925056443165" ] }, "bid_floor_specs": [ { "billable_event": "CLICKTHROUGH", "creative_type": "REGULAR", "currency": "USD", "countries": [ "US", "US" ], "optimization_goal_metadata": { "frequency_goal_metadata": { "timerange": "DAY", "frequency": 5 }, "conversion_tag_v3_goal_metadata": { "attribution_windows": { "view_window_days": 1, "click_window_days": 0, "engagement_window_days": 6 }, "conversion_tag_id": "conversion_tag_id", "learning_mode_type": "ACTIVE", "conversion_event": "PAGE_VISIT", "is_roas_optimized": true, "cpa_goal_value_in_micro_currency": "cpa_goal_value_in_micro_currency" }, "scrollup_goal_metadata": { "scrollup_goal_value_in_micro_currency": "scrollup_goal_value_in_micro_currency" } } }, { "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": "conversion_tag_id", "learning_mode_type": "ACTIVE", "conversion_event": "PAGE_VISIT", "is_roas_optimized": true, "cpa_goal_value_in_micro_currency": "cpa_goal_value_in_micro_currency" }, "scrollup_goal_metadata": { "scrollup_goal_value_in_micro_currency": "scrollup_goal_value_in_micro_currency" } } } ] }, "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": "conversion_tag_id", "learning_mode_type": "ACTIVE", "conversion_event": "PAGE_VISIT", "is_roas_optimized": true, "cpa_goal_value_in_micro_currency": "cpa_goal_value_in_micro_currency" }, "scrollup_goal_metadata": { "scrollup_goal_value_in_micro_currency": "scrollup_goal_value_in_micro_currency" } } }, "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": { "description": "Ad group targeting specification defining the ad group target audience. For example, '{\"APPTYPE\":[\"iphone\"], \"GENDER\":[\"male\"], \"LOCALE\":[\"en-US\"], \"LOCATION\":[\"501\"], \"AGE_BUCKET\":[\"25-34\"]}'", "example": { "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" ] }, "properties": { "AGE_BUCKET": { "description": "Values: [\"18-24\",\"21+\",\"25-34\",\"35-44\", \"45-49\",\"50-54\",\"55-64\",\"65+\"]", "example": [ "25-34" ], "items": { "type": "string" }, "title": "AGE_BUCKET", "type": "array" }, "APPTYPE": { "description": "Values: [\"android_mobile\", \"android_tablet\", \"ipad\", \"iphone\", \"web\", \"web_mobile\"]", "example": [ "iphone" ], "items": { "type": "string" }, "title": "APPTYPE", "type": "array" }, "AUDIENCE_EXCLUDE": { "description": "Excluded customer list IDs. Used to drive new customer acquisition goals. For example: [\"2542620905475\"]. Audience lists need to have at least 100 people with Pinterest accounts in them.", "example": [ "2542620905475" ], "items": { "type": "string" }, "title": "AUDIENCE_EXCLUDE", "type": "array" }, "AUDIENCE_INCLUDE": { "description": "Targeted customer list IDs. For example: [\"2542620905473\"]. Audience lists need to have at least 100 people with Pinterest accounts in them", "example": [ "2542620905473" ], "items": { "type": "string" }, "title": "AUDIENCE_INCLUDE", "type": "array" }, "GENDER": { "description": "Targeted genders. Values: [\"unknown\",\"male\",\"female\"]", "example": [ "male" ], "items": { "type": "string" }, "title": "GENDER", "type": "array" }, "GEO": { "description": "Location region codes, e.g., \"BE-VOV\" (East Flanders, Belgium) For complete list, click here or postal codes, e.g., \"US-94107\". Use either region codes or postal codes but not both.", "example": [ "BE-VOV" ], "items": { "type": "string" }, "title": "GEO", "type": "array" }, "INTEREST": { "description": "Interest object IDs.", "example": [ "925056443165" ], "items": { "type": "string" }, "title": "INTEREST", "type": "array" }, "LOCALE": { "description": "24 ISO 639-1 two letter language codes. Values: [\"cs\",\"da\",\"de\",\"el\",\"en\",\"es\",\"fi\",\"fr\",\"hu\", \"id\",\"in\",\"it\",\"ja\",\"ko\",\"no\",\"pl\",\"pt\",\"ro\",\"ru\",\"sk\",\"sv\",\"tr\",\"uk\",\"zh\"]", "example": [ "cs" ], "items": { "type": "string" }, "title": "LOCALE", "type": "array" }, "LOCATION": { "description": "22 ISO Alpha 2 two letter country codes or US Nielsen DMA (Designated Market Area) codes (location region codes) (e.g., [\"US\", \"807\"]). For complete list, click here. Location-Country and Location-Metro codes apply.", "example": [ "US" ], "items": { "type": "string" }, "title": "LOCATION", "type": "array" }, "SHOPPING_RETARGETING": { "items": { "example": { "lookback_window": 30, "exclusion_window": 14, "tag_types": [ 0, 6 ] }, "properties": { "lookback_window": { "description": "Number of days ago to start lookback timeframe for dynamic retargeting", "example": 30, "title": "lookback_window", "type": "integer" }, "tag_types": { "description": "Event types to target for dynamic retargeting", "example": [ 0, 6 ], "items": { "type": "integer" }, "title": "tag_types", "type": "array" }, "exclusion_window": { "description": "Number of days ago to stop lookback timeframe for dynamic retargeting", "example": 14, "title": "exclusion_window", "type": "integer" } }, "title": "TargetingSpec_SHOPPING_RETARGETING", "type": "object" }, "title": "SHOPPING_RETARGETING", "type": "array" }, "TARGETING_STRATEGY": { "description": "Values: [\"CHOOSE_YOUR_OWN\", \"FIND_NEW_CUSTOMERS\", \"RECONNECT_WITH_USERS\"]", "example": [ "CHOOSE_YOUR_OWN" ], "items": { "type": "string" }, "title": "TARGETING_STRATEGY", "type": "array" } }, "title": "TargetingSpec", "type": "object" } }, "required": [ "bid_floor_specs" ], "title": "BidFloorBody", "type": "object" }, "Board": { "title": "Board", "description": "Board", "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "example": "549755885175" }, "name": { "type": "string", "example": "Summer Recipes" }, "description": { "type": "string", "nullable": true, "example": "My favorite summer recipes" }, "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 } } }, "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" ] } } }, "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.", "example": "DAILY", "enum": [ "DAILY", "LIFETIME", "CBO_ADGROUP" ], "type": "string" }, "CampaignCommon": { "type": "object", "description": "Campaign Data", "properties": { "ad_account_id": { "description": "Campaign's Advertiser ID.", "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.", "example": 1432744744, "type": "integer", "nullable": true }, "daily_spend_cap": { "description": "Campaign daily spending cap.", "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 } } }, "CampaignCreateCommon": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CampaignCommon" }, { "properties": { "status": { "type": "string", "default": "ACTIVE", "allOf": [ { "$ref": "#/components/schemas/EntityStatus" } ] }, "is_campaign_budget_optimization": { "type": "boolean", "default": false, "allOf": [ { "$ref": "#/components/schemas/CampaignIsCampaignBudgetOptimization" } ] }, "is_flexible_daily_budgets": { "type": "boolean", "default": false, "allOf": [ { "$ref": "#/components/schemas/CampaignIsFlexibleDailyBudgets" } ] }, "default_ad_group_budget_in_micro_currency": { "type": "integer", "description": "When transitioning from campaign budget optimization to non-campaign budget optimization, the default_ad_group_budget_in_micro_currency will propagate to each child ad groups daily budget. Unit is micro currency of the associated advertiser account.", "example": 0, "nullable": true }, "is_automated_campaign": { "type": "boolean", "default": false, "allOf": [ { "$ref": "#/components/schemas/CampaignIsAutomatedCampaign" } ] } } } ] }, "CampaignCreateRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CampaignCreateCommon" }, { "required": [ "name", "objective_type", "ad_account_id" ], "properties": { "objective_type": { "$ref": "#/components/schemas/ObjectiveType" } } } ] }, "CampaignCreateResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CampaignCreateResponseItem" } } } }, "CampaignCreateResponseData": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CampaignCreateCommon" }, { "$ref": "#/components/schemas/CampaignResponse" }, { "properties": { "objective_type": { "$ref": "#/components/schemas/ObjectiveType" } } } ] }, "CampaignCreateResponseItem": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CampaignCreateResponseData" }, "exceptions": { "type": "array", "items": { "$ref": "#/components/schemas/Exception" } } } }, "CampaignId": { "properties": { "id": { "description": "Campaign ID.", "example": "549755885175", "type": "string", "pattern": "^\\d+$" } }, "type": "object" }, "CampaignIsCampaignBudgetOptimization": { "type": "boolean", "description": "Determines if a campaign automatically generate ad-group level budgets given a campaign budget to maximize campaign outcome. When transitioning from non-cbo to cbo, all previous child ad group budget will be cleared.", "example": true, "default": false }, "CampaignIsAutomatedCampaign": { "type": "boolean", "description": "Specifies whether the campaign was created in the automated campaign flow", "example": true, "default": false }, "CampaignIsFlexibleDailyBudgets": { "type": "boolean", "description": "Determine if a campaign has flexible daily budgets setup.", "example": true, "default": false }, "CampaignResponse": { "allOf": [ { "$ref": "#/components/schemas/CampaignId" }, { "$ref": "#/components/schemas/CampaignCommon" }, { "type": "object", "properties": { "objective_type": { "$ref": "#/components/schemas/ObjectiveType" }, "created_time": { "type": "integer", "description": "Campaign creation time. Unix timestamp in seconds.", "example": 1432744744 }, "updated_time": { "type": "integer", "description": "UTC timestamp. Last update time.", "example": 1432744744 }, "type": { "type": "string", "description": "Always \"campaign\".", "example": "campaign" }, "is_flexible_daily_budgets": { "type": "boolean", "description": "Determines if a campaign has flexible daily budgets setup.", "example": true, "nullable": true }, "is_campaign_budget_optimization": { "type": "boolean", "description": "Determines if a campaign automatically generate ad-group level budgets given a campaign budget to maximize campaign outcome. When transitioning from non-cbo to cbo, all previous child ad group budget will be cleared.", "example": true, "nullable": true } } } ] }, "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 } } }, "CampaignSummaryStatus": { "type": "string", "description": "Summary status for campaign", "example": "RUNNING", "enum": [ "RUNNING", "PAUSED", "NOT_STARTED", "COMPLETED", "ADVERTISER_DISABLED", "ARCHIVED" ] }, "CampaignUpdateResponse": { "allOf": [ { "$ref": "#/components/schemas/CampaignCreateResponse" } ] }, "CampaignUpdateRequest": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/CampaignId" }, { "$ref": "#/components/schemas/CampaignCommon" }, { "$ref": "#/components/schemas/CampaignCreateCommon" }, { "properties": { "is_campaign_budget_optimization": { "type": "boolean", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CampaignIsCampaignBudgetOptimization" } ] }, "is_flexible_daily_budgets": { "type": "boolean", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CampaignIsFlexibleDailyBudgets" } ] }, "is_automated_campaign": { "type": "boolean", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/CampaignIsAutomatedCampaign" } ] }, "status": { "type": "string", "nullable": true, "allOf": [ { "$ref": "#/components/schemas/EntityStatus" } ] } }, "required": [ "id", "ad_account_id" ] } ] }, "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" } } }, "CatalogsFeed": { "type": "object", "title": "catalogs_feed", "description": "Catalogs Feed object", "allOf": [ { "$ref": "#/components/schemas/CatalogsDbItem" }, { "type": "object", "title": "feed_fields", "properties": { "default_country": { "$ref": "#/components/schemas/Country" }, "default_availability": { "$ref": "#/components/schemas/ProductAvailabilityType" }, "default_currency": { "$ref": "#/components/schemas/NullableCurrency" }, "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" }, "default_locale": { "description": "The locale used within a feed for product descriptions.", "example": "en_US", "type": "string" }, "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" } }, "required": [ "credentials", "default_availability", "default_country", "default_currency", "default_locale", "format", "location", "name", "preferred_processing_schedule", "status" ] } ] }, "CatalogsFeedCredentials": { "type": "object", "nullable": true, "description": "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" } }, "required": [ "errors", "info" ] }, "CatalogsFeedIngestionErrors": { "type": "object", "properties": { "IMAGE_DOWNLOAD_ERROR": { "type": "integer", "description": "Some items include images that can't be found." }, "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." } } }, "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." } } }, "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" ] } ] }, "CatalogsFeedProcessingStatus": { "type": "string", "enum": [ "COMPLETED", "COMPLETED_EARLY", "DISAPPROVED", "FAILED", "PROCESSING", "QUEUED_FOR_PROCESSING", "UNDER_APPEAL", "UNDER_REVIEW" ] }, "CatalogsFeedProcessingSchedule": { "type": "object", "title": "catalogs_processing_schedule", "description": "Optional daily processing schedule. 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" ] }, "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" } } }, "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." }, "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." } } }, "CatalogsFeedValidationWarnings": { "type": "object", "properties": { "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." }, "LINK_FORMAT_WARNING": { "type": "integer", "description": "Some items have an invalid product link which contains invalid UTM tracking paramaters." }, "DUPLICATE_PRODUCTS": { "type": "integer", "description": "Some products are duplicated." }, "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_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 ] }, "ADWORDS_FORMAT_WARNING": { "type": "integer", "description": "Some items have adwords_redirect links that are formatted incorrectly." }, "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." }, "AVAILABILITY_NORMALIZED": { "type": "integer", "description": "Some items include availability values that are formatted incorrectly and have been automatically corrected." }, "CONDITION_NORMALIZED": { "type": "integer", "description": "Some items include condition values that are formatted incorrectly and have been automatically corrected." }, "GENDER_NORMALIZED": { "type": "integer", "description": "Some items include gender values that are formatted incorrectly and have been automatically corrected." }, "SIZE_TYPE_NORMALIZED": { "type": "integer", "description": "Some items include size_type values that are formatted incorrectly and have been automatically corrected." }, "AGE_GROUP_NORMALIZED": { "type": "integer", "description": "Some items include age_group values that are formatted incorrectly and have been automatically corrected." }, "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." } } }, "CatalogsFeedsCreateRequest": { "type": "object", "title": "feeds_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.", "properties": { "default_country": { "$ref": "#/components/schemas/Country" }, "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" }, "default_locale": { "description": "The locale used within a feed for product descriptions.", "example": "en_US", "type": "string" }, "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" } }, "required": [ "format", "location", "name" ] }, "CatalogsFeedsUpdateRequest": { "type": "object", "title": "catalogs_feeds_update_request", "description": "Request object for updating a feed.", "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" ] }, "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": { "items": { "description": "Array with the catalogs items processing records part of the catalogs items batch", "items": { "$ref": "#/components/schemas/ItemProcessingRecord" }, "type": "array" }, "batch_id": { "description": "Id of the catalogs items batch", "example": "595953100599279259-66753b9bb65c46c49bd8503b27fecf9e", "type": "string" }, "created_time": { "description": "Time of the batch creation: YYYY-MM-DD'T'hh:mm:ssTZD", "example": "2020-01-01T20:10:40-00:00", "type": "string", "format": "date-time", "readOnly": true }, "completed_time": { "description": "Time of the batch completion: YYYY-MM-DD'T'hh:mm:ssTZD", "example": "2022-03-10T15:37:10-00:00", "type": "string", "format": "date-time", "readOnly": true, "nullable": true }, "status": { "$ref": "#/components/schemas/BatchOperationStatus" } } }, "CatalogsItemsBatchRequest": { "type": "object", "description": "Request object of catalogs items batch", "oneOf": [ { "$ref": "#/components/schemas/CatalogsItemsUpdateBatchRequest" }, { "$ref": "#/components/schemas/CatalogsItemsCreateBatchRequest" }, { "$ref": "#/components/schemas/CatalogsItemsDeleteDiscontinuedBatchRequest" } ], "discriminator": { "propertyName": "operation", "mapping": { "UPDATE": "#/components/schemas/CatalogsItemsUpdateBatchRequest", "CREATE": "#/components/schemas/CatalogsItemsCreateBatchRequest", "DELETE_DISCONTINUED": "#/components/schemas/CatalogsItemsDeleteDiscontinuedBatchRequest" } } }, "CatalogsItemsCreateBatchRequest": { "description": "Request object to create catalogs items", "type": "object", "properties": { "country": { "$ref": "#/components/schemas/Country" }, "language": { "$ref": "#/components/schemas/Language" }, "operation": { "$ref": "#/components/schemas/BatchOperation" }, "items": { "type": "array", "description": "Array with catalogs items", "items": { "$ref": "#/components/schemas/ItemCreateBatchRecord" }, "minItems": 1, "maxItems": 50 } }, "required": [ "country", "language", "operation", "items" ] }, "CatalogsItemsUpdateBatchRequest": { "description": "Request object to update catalogs items", "type": "object", "properties": { "country": { "$ref": "#/components/schemas/Country" }, "language": { "$ref": "#/components/schemas/Language" }, "operation": { "$ref": "#/components/schemas/BatchOperation" }, "items": { "type": "array", "description": "Array with catalogs items", "items": { "$ref": "#/components/schemas/ItemUpdateBatchRecord" }, "minItems": 1, "maxItems": 1000 } }, "required": [ "country", "language", "operation", "items" ] }, "CatalogsItemsDeleteDiscontinuedBatchRequest": { "description": "Request object to discontinue catalogs items", "type": "object", "properties": { "country": { "$ref": "#/components/schemas/Country" }, "language": { "$ref": "#/components/schemas/Language" }, "operation": { "$ref": "#/components/schemas/BatchOperation" }, "items": { "type": "array", "description": "Array with catalogs items", "items": { "$ref": "#/components/schemas/ItemDeleteDiscontinuedBatchRecord" } } }, "required": [ "country", "language", "operation", "items" ] }, "CatalogsListProductsByFilterRequest": { "description": "Request object to list products for a given product group filter.", "type": "object", "oneOf": [ { "description": "Request object to list products for a given feed_id and product group filter.", "type": "object", "additionalProperties": false, "properties": { "feed_id": { "description": "Catalog Feed id pertaining to the catalog product group filter.", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" }, "filters": { "$ref": "#/components/schemas/CatalogsProductGroupFilters" } }, "required": [ "feed_id", "filters" ] } ] }, "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" ] }, "CatalogsItemValidationIssue": { "type": "string", "enum": [ "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", "AGE_GROUP_NORMALIZED", "ANDROID_DEEP_LINK_INVALID", "AVAILABILITY_DATE_INVALID", "AVAILABILITY_INVALID", "AVAILABILITY_NORMALIZED", "BLOCKLISTED_IMAGE_SIGNATURE", "CONDITION_NORMALIZED", "COUNTRY_DOES_NOT_MAP_TO_CURRENCY", "CUSTOM_LABEL_LENGTH_TOO_LONG", "DESCRIPTION_LENGTH_TOO_LONG", "DESCRIPTION_MISSING", "DUPLICATE_PRODUCTS", "EXPIRATION_DATE_INVALID", "GENDER_INVALID", "GENDER_NORMALIZED", "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", "MAX_ITEMS_PER_ITEM_GROUP_EXCEEDED", "MIN_AD_PRICE_INVALID", "MULTIPACK_INVALID", "OPTIONAL_CONDITION_INVALID", "OPTIONAL_CONDITION_MISSING", "OPTIONAL_PRODUCT_CATEGORY_INVALID", "OPTIONAL_PRODUCT_CATEGORY_MISSING", "PARSE_LINE_ERROR", "PINJOIN_CONTENT_UNSAFE", "PRICE_MISSING", "PRODUCT_CATEGORY_DEPTH_WARNING", "PRODUCT_LINK_MISSING", "PRODUCT_PRICE_INVALID", "PRODUCT_TYPE_LENGTH_TOO_LONG", "SALE_DATE_INVALID", "SALES_PRICE_INVALID", "SHIPPING_INVALID", "SHIPPING_WEIGHT_INVALID", "SIZE_TYPE_INVALID", "SIZE_TYPE_NORMALIZED", "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" ] }, "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." }, "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." }, "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_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." } } }, "CatalogsItemValidationWarnings": { "type": "object", "properties": { "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." }, "AGE_GROUP_NORMALIZED": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item includes an age_group value that is formatted incorrectly and has been automatically corrected." }, "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." }, "AVAILABILITY_NORMALIZED": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item includes an availability value that is formatted incorrectly and has been automatically corrected." }, "CONDITION_NORMALIZED": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item includes a condition value that is formatted incorrectly and has been automatically corrected." }, "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." }, "DUPLICATE_PRODUCTS": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "This product is duplicated. The duplicate entry will not be published." }, "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." }, "GENDER_NORMALIZED": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item includes a gender value that is formatted incorrectly and has been automatically corrected." }, "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." }, "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 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_WEIGHT_INVALID": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item has an invalid shipping_weight value." }, "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." }, "SIZE_TYPE_NORMALIZED": { "$ref": "#/components/schemas/CatalogsItemValidationDetails", "description": "Item includes a size_type value that is formatted incorrectly and has been automatically corrected." }, "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." } } }, "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" }, "CatalogsProductGroupStatus": { "type": "string", "enum": [ "ACTIVE", "INACTIVE" ] }, "CatalogsProductGroup": { "type": "object", "title": "catalogs_product_group", "description": "catalog product group entity", "oneOf": [ { "type": "object", "title": "catalogs_product_group_feed_based_case", "properties": { "id": { "description": "ID of the catalog product group.", "example": "443727193917", "type": "string", "pattern": "^\\d+$" }, "name": { "description": "Name of catalog product group", "example": "Most Popular", "type": "string" }, "description": { "type": "string", "nullable": true }, "filters": { "$ref": "#/components/schemas/CatalogsProductGroupFilters" }, "is_featured": { "description": "boolean indicator of whether the product group is being featured or not", "type": "boolean" }, "type": { "$ref": "#/components/schemas/CatalogsProductGroupType" }, "status": { "$ref": "#/components/schemas/CatalogsProductGroupStatus" }, "created_at": { "description": "Unix timestamp in seconds of when catalog product group was created.", "example": 1621350033000, "type": "integer" }, "updated_at": { "description": "Unix timestamp in seconds of last time catalog product group was updated.", "example": 1622742155000, "type": "integer" }, "feed_id": { "description": "id of the catalogs feed belonging to this catalog product group", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" } }, "required": [ "filters", "id", "feed_id" ] }, { "type": "object", "title": "catalogs_product_group_merchant_based_case", "properties": { "id": { "description": "ID of the catalog product group.", "example": "443727193917", "type": "string", "pattern": "^\\d+$" }, "name": { "description": "Name of catalog product group", "example": "Most Popular", "type": "string" }, "description": { "type": "string", "nullable": true }, "filters": { "$ref": "#/components/schemas/CatalogsProductGroupFilters" }, "is_featured": { "description": "boolean indicator of whether the product group is being featured or not", "type": "boolean" }, "type": { "$ref": "#/components/schemas/CatalogsProductGroupType" }, "status": { "$ref": "#/components/schemas/CatalogsProductGroupStatus" }, "created_at": { "description": "Unix timestamp in seconds of when catalog product group was created.", "example": 1621350033000, "type": "integer" }, "updated_at": { "description": "Unix timestamp in seconds of last time catalog product group was updated.", "example": 1622742155000, "type": "integer" }, "feed_id": { "example": null, "type": "string", "nullable": true, "enum": [ null ] } }, "required": [ "filters", "id", "feed_id" ] } ] }, "CatalogsProductGroupUpdateRequest": { "type": "object", "title": "product_groups_update_request", "description": "Request object for updating a product group.", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_featured": { "description": "boolean indicator of whether the product group is being featured or not", "type": "boolean" }, "filters": { "$ref": "#/components/schemas/CatalogsProductGroupFiltersAllOfRequest" } } }, "CatalogsProductGroupCreateRequest": { "type": "object", "title": "product_groups_create_request", "description": "Request object for creating a product group.", "oneOf": [ { "type": "object", "title": "product_groups_create_request_feed_base_case", "properties": { "name": { "type": "string" }, "description": { "type": "string", "nullable": true }, "is_featured": { "description": "boolean indicator of whether the product group is being featured or not", "type": "boolean", "default": false }, "filters": { "$ref": "#/components/schemas/CatalogsProductGroupFiltersAllOfRequest" }, "feed_id": { "description": "Catalog Feed id pertaining to the catalog product group.", "example": "2680059592705", "type": "string", "pattern": "^\\d+$" } }, "required": [ "name", "filters", "feed_id" ] } ] }, "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" } ] }, "CatalogsProductGroupFiltersAllOfRequest": { "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" ] }, "CatalogsProductGroupFiltersAllOf": { "type": "object", "additionalProperties": false, "properties": { "all_of": { "type": "array", "items": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupFilterKeys" } } }, "required": [ "all_of" ] }, "CatalogsProductGroupFilterKeys": { "title": "catalogs_product_group_keys", "anyOf": [ { "$ref": "#/components/schemas/MinPriceFilter" }, { "$ref": "#/components/schemas/MaxPriceFilter" }, { "$ref": "#/components/schemas/CurrencyFilter" }, { "$ref": "#/components/schemas/ItemIdFilter" }, { "$ref": "#/components/schemas/AvailabilityFilter" }, { "$ref": "#/components/schemas/BrandFilter" }, { "$ref": "#/components/schemas/ConditionFilter" }, { "$ref": "#/components/schemas/CustomLabel0Filter" }, { "$ref": "#/components/schemas/CustomLabel1Filter" }, { "$ref": "#/components/schemas/CustomLabel2Filter" }, { "$ref": "#/components/schemas/CustomLabel3Filter" }, { "$ref": "#/components/schemas/CustomLabel4Filter" }, { "$ref": "#/components/schemas/ItemGroupIdFilter" }, { "$ref": "#/components/schemas/GenderFilter" }, { "$ref": "#/components/schemas/ProductType4Filter" }, { "$ref": "#/components/schemas/ProductType3Filter" }, { "$ref": "#/components/schemas/ProductType2Filter" }, { "$ref": "#/components/schemas/ProductType1Filter" }, { "$ref": "#/components/schemas/ProductType0Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory6Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory5Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory4Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory3Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory2Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory1Filter" }, { "$ref": "#/components/schemas/GoogleProductCategory0Filter" } ] }, "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" ] }, "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" ] }, "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" ] }, "CatalogsProductGroupPricingCriteria": { "title": "catalogs_product_group_pricing_criteria", "type": "object", "additionalProperties": false, "properties": { "inclusion": { "type": "boolean", "default": true }, "values": { "type": "number", "minimum": 0 }, "negated": { "type": "boolean", "default": false } }, "required": [ "values" ] }, "CatalogsProductGroupProductCounts": { "title": "catalogs_product_group_product_counts", "description": "Product counts for a CatalogsProductGroup", "type": "object", "properties": { "in_stock": { "type": "number", "minimum": 0 }, "out_of_stock": { "type": "number", "minimum": 0 }, "preorder": { "type": "number", "minimum": 0 }, "total": { "type": "number", "minimum": 0 } }, "required": [ "in_stock", "out_of_stock", "preorder", "total" ] }, "CatalogsProductMetadata": { "type": "object", "description": "Product metadata entity", "properties": { "item_id": { "description": "The user-created unique ID that represents the product.", "example": "DS0294-L", "type": "string" }, "item_group_id": { "description": "The parent ID of the product.", "example": "DS0294", "type": "string", "nullable": true }, "availability": { "$ref": "#/components/schemas/NonNullableProductAvailabilityType" }, "price": { "description": "The price of the product.", "example": 24.99, "type": "number" }, "sale_price": { "description": "The discounted price of the product.", "example": 14.99, "type": "number", "nullable": true }, "currency": { "$ref": "#/components/schemas/NonNullableCatalogsCurrency" } }, "required": [ "item_id", "item_group_id", "availability", "price", "sale_price", "currency" ] }, "CatalogsProduct": { "type": "object", "properties": { "metadata": { "$ref": "#/components/schemas/CatalogsProductMetadata" }, "pin": { "$ref": "#/components/schemas/Pin" } }, "required": [ "metadata", "pin" ] }, "CustomerList": { "properties": { "ad_account_id": { "description": "Associated ad account ID.", "example": "549756359984", "title": "ad_account_id", "type": "string" }, "created_time": { "description": "Creation time. Unix timestamp in seconds.", "example": 1452208622, "title": "created_time", "type": "number" }, "id": { "description": "Customer list ID.", "example": "643", "title": "id", "type": "string" }, "name": { "description": "Customer list name.", "example": "The Glengarry Glen Ross leads", "title": "name", "type": "string" }, "num_batches": { "description": "Total number of list updates. List creation counts as one batch. Each Append or Remove API call counts as another. List creation via the Ads Manager UI could result in more than one batch since the UI breaks up large lists.", "example": 2, "title": "num_batches", "type": "number" }, "num_removed_user_records": { "description": "Number of removed user records. In a Remove API call, this counter increases even if the user is not found in the list.", "example": 0, "title": "num_removed_user_records", "type": "number" }, "num_uploaded_user_records": { "description": "Number of uploaded user records. In an Append API call, this counter increases even if the uploaded user is already in the list.", "example": 11, "title": "num_uploaded_user_records", "type": "number" }, "status": { "description": "Customer list status. TOO_SMALL - the list has less than 100 Pinterest users.", "enum": [ "PROCESSING", "READY", "TOO_SMALL", "UPLOADING" ], "example": "PROCESSING", "title": "status", "type": "string" }, "type": { "description": "Always \"customerlist\".", "example": "customerlist", "title": "type", "type": "string" }, "updated_time": { "description": "Last update time. Unix timestamp in seconds.", "example": 1461269616, "title": "updated_time", "type": "number" }, "exceptions": { "description": "Customer list errors", "title": "exceptions", "type": "object" } }, "title": "CustomerList", "type": "object" }, "CustomerListRequest": { "properties": { "name": { "description": "Customer list name.", "example": "The Glengarry Glen Ross leads", "title": "name", "type": "string" }, "records": { "description": "Records list. Can be any combination of emails, MAIDs, or IDFAs. Emails must be lowercase and can be plain text or hashed using SHA1, SHA256, or MD5. MAIDs and IDFAs must be hashed with SHA1, SHA256, or MD5.", "example": "email1@pinterest.com,email2@pinterest.com,..", "title": "records", "type": "string" }, "list_type": { "allOf": [ { "$ref": "#/components/schemas/UserListType" } ], "default": "EMAIL", "title": "list_type", "type": "string" }, "exceptions": { "description": "Customer list errors.", "title": "exceptions", "type": "object" } }, "required": [ "name", "records" ], "title": "CustomerListCreate", "type": "object" }, "CustomerListUpdateRequest": { "properties": { "records": { "description": "Records list. Can be any combination of emails, MAIDs, or IDFAs. Emails must be lowercase and can be plain text or hashed using SHA1, SHA256, or MD5. MAIDs and IDFAs must be hashed with SHA1, SHA256, or MD5.", "example": "email2@pinterest.com,email6@pinterest.com,", "title": "records", "type": "string" }, "operation_type": { "allOf": [ { "$ref": "#/components/schemas/UserListOperationType" } ], "title": "operation_type", "type": "string" }, "exceptions": { "$ref": "#/components/schemas/Exception", "title": "exceptions", "type": "object" } }, "required": [ "operation_type", "records" ], "title": "CustomerListUpdate", "type": "object" }, "MinPriceFilter": { "type": "object", "additionalProperties": false, "properties": { "MIN_PRICE": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupPricingCriteria" } }, "required": [ "MIN_PRICE" ] }, "MaxPriceFilter": { "type": "object", "additionalProperties": false, "properties": { "MAX_PRICE": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupPricingCriteria" } }, "required": [ "MAX_PRICE" ] }, "CurrencyFilter": { "type": "object", "additionalProperties": false, "properties": { "CURRENCY": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupCurrencyCriteria" } }, "required": [ "CURRENCY" ] }, "ItemIdFilter": { "type": "object", "additionalProperties": false, "properties": { "ITEM_ID": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringCriteria" } }, "required": [ "ITEM_ID" ] }, "AvailabilityFilter": { "type": "object", "additionalProperties": false, "properties": { "AVAILABILITY": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringCriteria" } }, "required": [ "AVAILABILITY" ] }, "BrandFilter": { "type": "object", "additionalProperties": false, "properties": { "BRAND": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringCriteria" } }, "required": [ "BRAND" ] }, "ConditionFilter": { "type": "object", "additionalProperties": false, "properties": { "CONDITION": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringCriteria" } }, "required": [ "CONDITION" ] }, "CustomLabel0Filter": { "type": "object", "additionalProperties": false, "properties": { "CUSTOM_LABEL_0": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringCriteria" } }, "required": [ "CUSTOM_LABEL_0" ] }, "CustomLabel1Filter": { "type": "object", "additionalProperties": false, "properties": { "CUSTOM_LABEL_1": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringCriteria" } }, "required": [ "CUSTOM_LABEL_1" ] }, "CustomLabel2Filter": { "type": "object", "additionalProperties": false, "properties": { "CUSTOM_LABEL_2": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringCriteria" } }, "required": [ "CUSTOM_LABEL_2" ] }, "CustomLabel3Filter": { "type": "object", "additionalProperties": false, "properties": { "CUSTOM_LABEL_3": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringCriteria" } }, "required": [ "CUSTOM_LABEL_3" ] }, "CustomLabel4Filter": { "type": "object", "additionalProperties": false, "properties": { "CUSTOM_LABEL_4": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringCriteria" } }, "required": [ "CUSTOM_LABEL_4" ] }, "Exception": { "title": "Generic exception class to be used within schemas", "type": "object", "properties": { "code": { "type": "integer", "example": 2, "description": "Exception error code." }, "message": { "type": "string", "example": "Advertiser not found.", "description": "Exception message." } } }, "ItemGroupIdFilter": { "type": "object", "additionalProperties": false, "properties": { "ITEM_GROUP_ID": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringCriteria" } }, "required": [ "ITEM_GROUP_ID" ] }, "GenderFilter": { "type": "object", "additionalProperties": false, "properties": { "GENDER": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringCriteria" } }, "required": [ "GENDER" ] }, "GetAudiencesOrderBy": { "type": "string", "enum": [ "NONE", "ID", "SIZE", "CREATION_DATE", "UPDATED_TIME", "NAME", "STATUS", "TYPE" ], "example": "NAME" }, "ProductType4Filter": { "type": "object", "additionalProperties": false, "properties": { "PRODUCT_TYPE_4": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringListCriteria" } }, "required": [ "PRODUCT_TYPE_4" ] }, "ProductType3Filter": { "type": "object", "additionalProperties": false, "properties": { "PRODUCT_TYPE_3": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringListCriteria" } }, "required": [ "PRODUCT_TYPE_3" ] }, "ProductType2Filter": { "type": "object", "additionalProperties": false, "properties": { "PRODUCT_TYPE_2": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringListCriteria" } }, "required": [ "PRODUCT_TYPE_2" ] }, "ProductType1Filter": { "type": "object", "additionalProperties": false, "properties": { "PRODUCT_TYPE_1": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringListCriteria" } }, "required": [ "PRODUCT_TYPE_1" ] }, "ProductType0Filter": { "type": "object", "additionalProperties": false, "properties": { "PRODUCT_TYPE_0": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringListCriteria" } }, "required": [ "PRODUCT_TYPE_0" ] }, "GoogleProductCategory6Filter": { "type": "object", "additionalProperties": false, "properties": { "GOOGLE_PRODUCT_CATEGORY_6": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringListCriteria" } }, "required": [ "GOOGLE_PRODUCT_CATEGORY_6" ] }, "GoogleProductCategory5Filter": { "type": "object", "additionalProperties": false, "properties": { "GOOGLE_PRODUCT_CATEGORY_5": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringListCriteria" } }, "required": [ "GOOGLE_PRODUCT_CATEGORY_5" ] }, "GoogleProductCategory4Filter": { "type": "object", "additionalProperties": false, "properties": { "GOOGLE_PRODUCT_CATEGORY_4": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringListCriteria" } }, "required": [ "GOOGLE_PRODUCT_CATEGORY_4" ] }, "GoogleProductCategory3Filter": { "type": "object", "additionalProperties": false, "properties": { "GOOGLE_PRODUCT_CATEGORY_3": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringListCriteria" } }, "required": [ "GOOGLE_PRODUCT_CATEGORY_3" ] }, "GoogleProductCategory2Filter": { "type": "object", "additionalProperties": false, "properties": { "GOOGLE_PRODUCT_CATEGORY_2": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringListCriteria" } }, "required": [ "GOOGLE_PRODUCT_CATEGORY_2" ] }, "GoogleProductCategory1Filter": { "type": "object", "additionalProperties": false, "properties": { "GOOGLE_PRODUCT_CATEGORY_1": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringListCriteria" } }, "required": [ "GOOGLE_PRODUCT_CATEGORY_1" ] }, "GoogleProductCategory0Filter": { "type": "object", "additionalProperties": false, "properties": { "GOOGLE_PRODUCT_CATEGORY_0": { "type": "object", "$ref": "#/components/schemas/CatalogsProductGroupMultipleStringListCriteria" } }, "required": [ "GOOGLE_PRODUCT_CATEGORY_0" ] }, "ConversionAttributionWindowDays": { "type": "integer", "enum": [ 1, 7, 30, 60 ] }, "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" ] }, "Country": { "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", "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" ] }, "Currency": { "type": "string", "description": "Currency Codes from ISO 4217", "example": "USD", "enum": [ "UNK", "USD", "GBP", "CAD", "EUR", "AUD", "NZD", "SEK", "ILS", "CHF", "HKD", "JPY", "SGD", "KRW", "NOK", "DKK", "PLN", "RON", "HUF", "CZK", "BRL", "MXN", "ARS", "CLP", "COP" ] }, "DataOutputFormat": { "type": "string", "description": "Format of generated report", "example": "JSON", "enum": [ "JSON", "CSV" ] }, "DataStatus": { "description": "Metrics availablity, e.g., \"READY\".", "example": "READY", "type": "string", "enum": [ "PROCESSING", "READY", "ESTIMATE", "BEFORE_BUSINESS_CREATED", "BEFORE_DATA_RETENTION_PERIOD", "BEFORE_PIN_DATA_RETENTION_PERIOD", "BEFORE_METRIC_START_DATE", "BEFORE_CORE_METRIC_START_DATE", "BEFORE_PIN_FORMAT_METRIC_START_DATE", "BEFORE_AUDIENCE_METRIC_START_DATE", "BEFORE_AUDIENCE_MONTHLY_METRIC_START_DATE", "BEFORE_VIDEO_METRIC_START_DATE", "BEFORE_CONVERSION_METRIC_START_DATE", "PURCHASERS_METRIC_SMALLER_THAN_THRESHOLD", "IN_BAD_TAG_DATE", "BEFORE_PUBLISHED_METRIC_START_DATE", "BEFORE_ASSIST_METRIC_START_DATE", "BEFORE_PIN_CREATED", "BEFORE_ACCOUNT_CLAIMED", "BEFORE_DEMOGRAPHIC_FILTERS_START_DATE", "AUDIENCE_SEGMENT_SMALLER_THAN_THRESHOLD", "AUDIENCE_TOTAL_SMALLER_THAN_THRESHOLD", "BEFORE_PRODUCT_GROUP_FILTER_START_DATE" ] }, "EntityStatus": { "type": "string", "description": "Entity status", "example": "ACTIVE", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] }, "Granularity": { "type": "string", "enum": [ "TOTAL", "DAY", "HOUR", "WEEK", "MONTH" ] }, "ItemAttributes": { "type": "object", "allOf": [ { "properties": { "additional_image_link": { "description": "

<= 2000 characters

\n

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

", "example": [ "https://scene.example.com/image/image_v2.jpg", "https://scene.example.com/image/image_v3.jpg" ], "type": "array", "nullable": true, "items": { "type": "string" } }, "image_link": { "description": "

<= 2000 characters

\n

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

", "example": [ "https://scene.example.com/image/image.jpg" ], "type": "array", "minItems": 1, "items": { "type": "string" } } } }, { "$ref": "#/components/schemas/UpdatableItemAttributes" } ] }, "UpdatableItemAttributes": { "type": "object", "properties": { "ad_link": { "description": "Allows advertisers to specify a separate URL that can be used to track traffic coming from Pinterest shopping ads. Must send full URL including tracking—do not send tracking parameters only. At this time we do not support impression tracking. Must begin with http:// or https://.", "example": "https://www.example.com/cat/denim-shirt/item012?utm_source=Pinterest", "type": "string", "nullable": true }, "adult": { "description": "Set this attribute to TRUE if you're submitting items that are considered “adult”. These will not be shown on Pinterest.", "example": true, "type": "boolean", "nullable": true }, "age_group": { "description": "The age group to apply a demographic range to the product. Must be one of the following values (upper or lowercased): ‘newborn’, ‘infant’, ‘toddler’, ‘kids’, or ‘adult’.", "example": "newborn", "type": "string", "nullable": true }, "availability": { "description": "The availability of the product. Must be one of the following values (upper or lowercased): ‘in stock’, ‘out of stock’, ‘preorder’.", "example": "in stock", "type": "string" }, "average_review_rating": { "description": "Average reviews for the item. Can be a number from 1-5.", "example": 5, "type": "number", "nullable": true }, "brand": { "description": "The brand of the product.", "example": "Josie’s Denim", "type": "string", "nullable": true }, "checkout_enabled": { "description": "Set this attribute to FALSE to indicate items that should be excluded from the Pinterest Checkout program. Note, this product is currently being tested and your account must be enrolled. Please contact your Account Manager or contact us for more information.", "example": false, "type": "boolean", "nullable": true }, "color": { "description": "The primary color of the product.", "example": "blue", "type": "string", "nullable": true }, "condition": { "description": "The condition of the product. Must be one of the following values (upper or lowercased): ‘new’, ‘used’, or ‘refurbished’.", "example": "new", "type": "string", "nullable": true }, "custom_label_0": { "description": "

<= 1000 characters

\n

Custom grouping of products.

", "example": "Best sellers", "type": "string", "nullable": true }, "custom_label_1": { "description": "

<= 1000 characters

\n

Custom grouping of products.

", "example": "Summer promotion", "type": "string", "nullable": true }, "custom_label_2": { "description": "

<= 1000 characters

\n

Custom grouping of products.

", "example": "Winter sales", "type": "string", "nullable": true }, "custom_label_3": { "description": "

<= 1000 characters

\n

Custom grouping of products.

", "example": "Woman dress", "type": "string", "nullable": true }, "custom_label_4": { "description": "

<= 1000 characters

\n

Custom grouping of products.

", "example": "Man hat", "type": "string", "nullable": true }, "description": { "description": "

<= 10000 characters

\n

The description of the product.

", "example": "Casual fit denim shirt made with the finest quality Japanese denim.", "type": "string" }, "free_shipping_label": { "description": "The item is free to ship.", "example": true, "type": "boolean", "nullable": true }, "free_shipping_limit": { "description": "The minimum order purchase necessary for the customer to get free shipping. Only relevant if free shipping is offered.", "example": "35 USD", "type": "string", "nullable": true }, "gender": { "description": "The gender associated with the product. Must be one of the following values (upper or lowercased): ‘male’, ‘female’, or ‘unisex’.", "example": "unisex", "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.", "example": "Apparel & Accessories > Clothing > Shirts & Tops", "type": "string", "nullable": true }, "gtin": { "description": "The unique universal product identifier.", "example": 3234567890126, "type": "integer", "nullable": true }, "id": { "description": "

<= 127 characters

\n

The user-created unique ID that represents the product. Only\nUnicode characters are accepted.

", "example": "DS0294-L", "type": "string", "deprecated": true }, "item_group_id": { "description": "

<= 127 characters

\n

The parent ID of the product.

", "example": "DS0294", "type": "string", "nullable": true }, "last_updated_time": { "description": "The millisecond timestamp when the item was lastly modified by the merchant.", "example": 1641483432072, "type": "integer", "format": "int64", "nullable": true }, "link": { "description": "

<= 511 characters

\n

The landing page for the product.

", "example": "https://www.example.com/cat/womens-clothing/denim-shirt-0294", "type": "string" }, "material": { "description": "The material used to make the product.", "example": "cotton", "type": "string", "nullable": true }, "min_ad_price": { "description": "The minimum advertised price of the product. It supports the following formats, \"19.99 USD\", \"19.99USD\" and \"19.99\". If the currency is not included, we default to US dollars.", "example": "19.99 USD", "type": "string", "nullable": true }, "mobile_link": { "description": "The mobile-optimized version of your landing page. Must begin with http:// or https://.", "example": "https://m.example.com/cat/womens-clothing/denim-shirt-0294", "type": "string", "nullable": true }, "mpn": { "description": "Manufacturer Part Number are alpha-numeric codes created by the manufacturer of a product to uniquely identify it among all products from the same manufacturer.", "example": "PI12345NTEREST", "type": "string", "nullable": true }, "number_of_ratings": { "description": "The number of ratings for the item.", "example": 10, "type": "integer", "nullable": true }, "number_of_reviews": { "description": "The number of reviews available for the item.", "example": 10, "type": "integer", "nullable": true }, "pattern": { "description": "The description of the pattern used for the product.", "example": "plaid", "type": "string", "nullable": true }, "price": { "description": "The price of the product. It supports the following formats, \"24.99 USD\", \"24.99USD\" and \"24.99\". If the currency is not included, we default to US dollars.", "example": "24.99 USD", "type": "string" }, "product_type": { "description": "

<= 1000 characters

\n

The categorization of your product based on your custom product\ntaxonomy. Subcategories must be sent separated by “ > “. The > must be\nwrapped by spaces. We do not recognize any other delimiters such as comma\nor pipe.

", "example": "Clothing > Women’s > Shirts > Denim", "type": "string", "nullable": true }, "sale_price": { "description": "The discounted price of the product. The sale_price must be lower than the price. It supports the following formats, \"14.99 USD\", \"14.99USD\" and \"14.99\". If the currency is not included, we default to US dollars.", "example": "14.99 USD", "type": "string", "nullable": true }, "shipping": { "description": "Shipping consists of one group of up to four elements, country, region, service (all optional) and price (required). All colons, even for blank values, are required.", "example": "US:CA:Ground:0 USD", "type": "string", "nullable": true }, "shipping_height": { "description": "The height of the package needed to ship the product. Ensure there is a space between the numeric string and the metric.", "example": "12 in", "type": "string", "nullable": true }, "shipping_weight": { "description": "The weight of the product. Ensure there is a space between the numeric string and the metric.", "example": "3 kg", "type": "string", "nullable": true }, "shipping_width": { "description": "The width of the package needed to ship the product. Ensure there is a space between the numeric string and the metric.", "example": "16 in", "type": "string", "nullable": true }, "size": { "description": "The size of the product.", "example": "M", "type": "string", "nullable": true }, "size_system": { "description": "Indicates the country’s sizing system in which you are submitting your product. Must be one of the following values (upper or lowercased): ‘US’, ‘UK’, ‘EU’, ‘DE’, ‘FR’, ‘JP’, ‘CN’, ‘IT’, ‘BR’, ‘MEX’, or ‘AU’.", "example": "US", "type": "string", "nullable": true }, "size_type": { "description": "Additional description for the size. Must be one of the following values (upper or lowercased): ‘regular’, ‘petite’, ‘plus’, ‘big_and_tall’, or ‘maternity’.", "example": "regular", "type": "string", "nullable": true }, "tax": { "description": "Tax consists of one group of up to four elements, country, region, rate (all required) and tax_ship (optional). All colons, even for blank values, are required.", "example": "US:1025433:6.00:y", "type": "string", "nullable": true }, "title": { "description": "

<= 500 characters

\n

The name of the product.

", "example": "Women’s denim shirt, large", "type": "string" }, "variant_names": { "description": "Options for this variant. People will see these options next to your Pin and can select the one they want. List them in the order you want them displayed.", "example": [ "Color", "Size" ], "type": "array", "nullable": true, "items": { "type": "string" } }, "variant_values": { "description": "Option values for this variant. People will see these options next to your Pin and can select the one they want. List them in the order you want them displayed. The order of the variant values must be consistent with the order of the variant names.", "example": [ "Red", "Small" ], "type": "array", "nullable": true, "items": { "type": "string" } } } }, "ItemBatchRecord": { "type": "object", "description": "Object describing an item batch record", "oneOf": [ { "$ref": "#/components/schemas/ItemCreateBatchRecord" }, { "$ref": "#/components/schemas/ItemDeleteDiscontinuedBatchRecord" }, { "$ref": "#/components/schemas/ItemUpdateBatchRecord" } ] }, "ItemCreateBatchRecord": { "type": "object", "description": "Object describing an item batch record to create items", "properties": { "item_id": { "description": "The catalog item id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "attributes": { "$ref": "#/components/schemas/ItemAttributes" } } }, "ItemDeleteDiscontinuedBatchRecord": { "type": "object", "description": "Object describing an item batch record to discontinue items", "properties": { "item_id": { "description": "The catalog item id in the merchant namespace", "example": "DS0294-M", "type": "string" } } }, "ItemUpdateBatchRecord": { "type": "object", "description": "Object describing an item batch record to update items", "properties": { "item_id": { "description": "The catalog item id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "attributes": { "$ref": "#/components/schemas/UpdatableItemAttributes" } } }, "ItemProcessingRecord": { "type": "object", "description": "Object describing an item processing record", "properties": { "item_id": { "description": "The catalog item 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" } } }, "ItemProcessingStatus": { "description": "The status of the item processing record", "example": "SUCCESS", "type": "string", "enum": [ "SUCCESS", "FAILURE", "PROCESSING" ] }, "ItemResponse": { "type": "object", "description": "Object describing an item record", "anyOf": [ { "type": "object", "properties": { "item_id": { "description": "The catalog item id in the merchant namespace", "example": "DS0294-M", "type": "string" }, "attributes": { "$ref": "#/components/schemas/ItemAttributes" } } }, { "type": "object", "properties": { "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" } } } ] }, "ItemValidationEvent": { "type": "object", "description": "Object describing an item validation event", "properties": { "attribute": { "description": "The attribute that the item validation event references", "example": "title", "type": "string" }, "code": { "description": "The event code that the item validation event references", "example": 106, "type": "integer" }, "message": { "description": "Title message describing the item validation event", "example": "Title is missing from product metadata.", "type": "string" } } }, "Keyword": { "type": "object", "allOf": [ { "$ref": "#/components/schemas/KeywordsCommon" }, { "type": "object" } ], "properties": { "archived": { "type": "boolean", "example": false }, "id": { "description": "Keyword ID .", "example": "383791336903426391", "pattern": "^\\d+$", "title": "id", "type": "string" }, "parent_id": { "description": "Keyword parent entity ID (advertiser, campaign, ad group, ad).", "example": "383791336903426391", "pattern": "^\\d+$", "title": "parent_id", "type": "string" }, "parent_type": { "type": "string", "description": "Parent entity type", "example": "campaign" }, "type": { "type": "string", "description": "Always keyword", "example": "keyword" } } }, "KeywordsCommon": { "type": "object", "properties": { "bid": { "type": "number", "description": "Keyword custom bid", "example": 200000 }, "match_type": { "$ref": "#/components/schemas/MatchTypeResponse" }, "value": { "type": "string", "description": "Keyword value (120 chars max)." } }, "required": [ "match_type", "value" ] }, "KeywordError": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Keyword" }, "error_messages": { "type": "array", "items": { "type": "string" } } } }, "KeywordsRequest": { "type": "object", "properties": { "keywords": { "type": "array", "description": "Keyword JSON array. Each array element has 3 fields", "items": { "$ref": "#/components/schemas/KeywordsCommon" } }, "parent_id": { "description": "Keyword parent entity ID (advertiser, campaign, ad group, ad).", "example": "383791336903426391", "pattern": "^((AG)|C)?\\d+$", "title": "parent_id", "type": "string" } }, "required": [ "keywords", "parent_id" ] }, "KeywordUpdate": { "title": "KeywordUpdate", "type": "object", "properties": { "id": { "type": "string", "description": "Keyword ID.", "example": "2886364308355", "pattern": "^\\d+$", "title": "id" }, "archived": { "type": "boolean", "description": "Is keyword archived?", "example": false, "title": "archived" }, "bid": { "type": "integer", "minimum": 1, "description": "Keyword custom bid in microcurrency - null if inherited from parent ad group.", "example": 200000, "nullable": true, "title": "bid" } }, "required": [ "id" ] }, "KeywordUpdateBody": { "type": "object", "properties": { "keywords": { "description": "Keywords to update. Object array. Each object has 3 possible fields:
1. \"id\": (required) keyword ID
2. \"archived\": boolean. Should keyword be archived?
3. \"bid\": number
For example: [{\"id\":\"2886610576653\", \"archived\": false, \"bid\": 20000}, {\"id\":\"2886610576654\", \"archived\": true, \"bid\": 20000}, ...]", "type": "array", "items": { "$ref": "#/components/schemas/KeywordUpdate" }, "title": "keywords" } }, "required": [ "keywords" ] }, "KeywordsResponse": { "properties": { "errors": { "type": "array", "items": { "$ref": "#/components/schemas/KeywordError" } }, "keywords": { "type": "array", "items": { "$ref": "#/components/schemas/Keyword" } } } }, "Language": { "type": "string", "description": "Language code, which is among the offical ISO 639-1 language list.", "example": "EN", "enum": [ "AM", "AR", "AZ", "BG", "BN", "BS", "CA", "CS", "DA", "DV", "DZ", "DE", "EL", "EN", "ES", "ET", "FA", "FI", "FR", "HE", "HI", "HR", "HU", "HY", "ID", "IN", "IS", "IT", "IW", "JA", "KA", "KM", "KO", "LO", "LT", "LV", "MK", "MN", "MS", "MY", "NB", "NE", "NL", "NO", "PL", "PT", "RO", "RU", "SK", "SL", "SQ", "SR", "SV", "TL", "UK", "VI", "TE", "TH", "TR", "XX", "ZH" ] }, "MatchType": { "type": "string", "description": "Keyword match type", "example": "BROAD", "enum": [ "BROAD", "PHRASE", "EXACT", "EXACT_NEGATIVE", "PHRASE_NEGATIVE" ] }, "MatchTypeResponse": { "type": "string", "description": "Keyword match type", "nullable": true, "example": "BROAD", "enum": [ "BROAD", "PHRASE", "EXACT", "EXACT_NEGATIVE", "PHRASE_NEGATIVE", null ] }, "MediaUpload": { "title": "Media upload", "description": "Media upload that has been registered but not uploaded/processed yet.", "allOf": [ { "type": "object", "readOnly": true, "properties": { "media_id": { "type": "string", "description": "Unique identifier for this media upload. Used to track status and for attaching during Pin creation." }, "media_type": { "allOf": [ { "$ref": "#/components/schemas/MediaUploadType" } ], "type": "string", "example": "video" }, "upload_url": { "type": "string", "description": "The URL where you will POST your media file.", "example": "https://pinterest-media-upload.s3-accelerate.amazonaws.com/" }, "upload_parameters": { "type": "object", "description": "The list of parameter key/value pairs you will need to send with your POST request to upload your media file.", "properties": { "x-amz-date": { "type": "string" }, "x-amz-signature": { "type": "string" }, "x-amz-security-token": { "type": "string" }, "x-amz-algorithm": { "type": "string" }, "key": { "type": "string" }, "policy": { "type": "string" }, "x-amz-credential": { "type": "string" }, "Content-Type": { "type": "string", "example": "multipart/form-data" } } } } } ], "example": { "media_id": "12345", "media_type": "video", "upload_url": "https://pinterest-media-upload.s3-accelerate.amazonaws.com/", "upload_parameters": { "x-amz-data": "20220127T185143Z", "x-amz-signature": "fcd6309a6aaee213348666a72abed8b44552a43acb6b340e8e1b288d21a5fe92", "key": "uploads/11/aa/22/3:video:203014033110991560:5212123920968240771", "policy": "eyJleHBpcmF0aW9uIjoiMj..==", "x-amz-credential": "ASIA6QZJ64OPIKV7FRVX/20220127/us-east-1/s3/aws4_request", "x-amz-security-token": "IQoJb3JpZ2luX2VjEJr...==", "x-amz-algorithm": "AWS4-HMAC-SHA256", "Content-Type": "multipart/form-data" } } }, "MediaUploadDetails": { "title": "Media upload details", "description": "Media upload details", "type": "object", "properties": { "media_id": { "type": "string", "pattern": "^\\d+$", "readOnly": true }, "media_type": { "allOf": [ { "$ref": "#/components/schemas/MediaUploadType" } ], "type": "string", "readOnly": true }, "status": { "allOf": [ { "$ref": "#/components/schemas/MediaUploadStatus" } ], "type": "string", "readOnly": true } }, "example": { "media_id": "12345", "media_type": "video", "status": "succeeded" } }, "MediaUploadRequest": { "title": "Media upload request", "description": "Media upload request", "type": "object", "properties": { "media_type": { "allOf": [ { "$ref": "#/components/schemas/MediaUploadType" } ], "type": "string", "writeOnly": true } }, "required": [ "media_type" ], "example": { "media_type": "video" } }, "MediaUploadStatus": { "description": "Media upload status", "type": "string", "enum": [ "registered", "processing", "succeeded", "failed" ] }, "MediaUploadType": { "type": "string", "enum": [ "video" ] }, "Metrics": { "description": "The metric name and daily value for each requested metric", "type": "object", "additionalProperties": { "type": "number" }, "example": { "ENGAGEMENT": 100, "CLICKTHROUGH_RATE": 0.2, "CLICKTHROUGH": 200, "CLOSEUP": 37, "CLOSEUP_RATE": 0.5, "ENGAGEMENT_RATE": 0.2, "SAVE": 20, "SAVE_RATE": 0.18, "IMPRESSION": 240 } }, "MetricsReportingLevel": { "type": "string", "description": "Level of the reporting request", "example": "CAMPAIGN", "enum": [ "ADVERTISER", "ADVERTISER_TARGETING", "CAMPAIGN", "CAMPAIGN_TARGETING", "AD_GROUP", "AD_GROUP_TARGETING", "PIN_PROMOTION", "PIN_PROMOTION_TARGETING", "KEYWORD", "PRODUCT_GROUP", "PRODUCT_GROUP_TARGETING", "PRODUCT_ITEM" ] }, "NonNullableCatalogsCurrency": { "type": "string", "description": "Currency Codes from ISO 4217.", "nullable": false, "example": "USD", "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BYR", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GGP", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "IMP", "INR", "IQD", "IRR", "ISK", "JEP", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SPL", "SRD", "STD", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TVD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VEF", "VND", "VUV", "WST", "XAF", "XCD", "XDR", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWD" ] }, "NonNullableProductAvailabilityType": { "description": "Product availability.", "nullable": false, "type": "string", "enum": [ "IN_STOCK", "OUT_OF_STOCK", "PREORDER" ] }, "NullableCatalogsItemFieldType": { "description": "Product item fields", "example": "TITLE", "type": "string", "nullable": true, "enum": [ "ITEM_ID", "ITEM_GROUP_ID", "TITLE", "DESCRIPTION", "ITEM_LINK", "ORGANIC_LINK", "IMAGE_LINK", "ADWORDS_REDIRECT_LINK", "AD_LINK", "SIZE", "GOOGLE_PRODUCT_CATEGORY", "PRODUCT_CATEGORY", "CONDITION", "AVAILABILITY", "GENDER", "AGE_GROUP", "SIZE_TYPE", "SIZE_SYSTEM", "ADULT", "SHIPPING", "SHIPPING_WEIGHT", "TAX", "MULTIPACK", "ADDITIONAL_IMAGE_LINK", "PRICE", "SALE_PRICE", "IS_BUNDLE", "EXPIRATION_DATE", "SALE_PRICE_EFFECTIVE_DATE", "AVAILABILITY_DATE", "WEIGHT_UNIT", "PRODUCT_TYPE", "CUSTOM_LABEL_0", "CUSTOM_LABEL_1", "CUSTOM_LABEL_2", "CUSTOM_LABEL_3", "CUSTOM_LABEL_4", "MATERIAL", "PATTERN", "COLOR", "BRAND", "GTIN", "MPN", "IOS_DEEP_LINK", "ANDROID_DEEP_LINK", "FREE_SHIPPING_LABEL", "FREE_SHIPPING_LIMIT", "AVG_REVIEW_RATING", "NUM_RATINGS", "NUM_REVIEWS", "ALT_TEXT", "VARIANT_NAMES", "VARIANT_VALUES", "MIN_AD_PRICE", "SHIPPING_WIDTH", "SHIPPING_HEIGHT", null ] }, "NullableCurrency": { "type": "string", "description": "Currency Codes from ISO 4217.", "example": "USD", "nullable": true, "enum": [ "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AUD", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BYR", "BZD", "CAD", "CDF", "CHF", "CLP", "CNY", "COP", "CRC", "CUC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ERN", "ETB", "EUR", "FJD", "FKP", "GBP", "GEL", "GGP", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "IMP", "INR", "IQD", "IRR", "ISK", "JEP", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRO", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SPL", "SRD", "STD", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TVD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VEF", "VND", "VUV", "WST", "XAF", "XCD", "XDR", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWD", null ] }, "OauthAccessTokenRequest": { "title": "OAuth access token request", "description": "Describes the valid schema for possible OAuth access token requests.", "type": "object", "discriminator": { "propertyName": "grant_type", "mapping": { "authorization_code": "#/components/schemas/OauthAccessTokenRequestCode", "refresh_token": "#/components/schemas/OauthAccessTokenRequestRefresh" } }, "properties": { "grant_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ] } }, "required": [ "grant_type" ] }, "OauthAccessTokenRequestRefresh": { "title": "refresh_token", "description": "A request to exchange a refresh token for a new access token.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OauthAccessTokenRequest" }, { "type": "object", "properties": { "refresh_token": { "type": "string" }, "scope": { "type": "string" } }, "required": [ "refresh_token" ] } ] }, "OauthAccessTokenRequestCode": { "title": "authorization_code", "description": "A request to exchange an authorization code for an access token.", "allOf": [ { "$ref": "#/components/schemas/OauthAccessTokenRequest" }, { "type": "object", "properties": { "code": { "type": "string" }, "redirect_uri": { "type": "string" } }, "required": [ "code", "redirect_uri" ] } ] }, "OauthAccessTokenResponse": { "title": "OAuth access token response", "description": "A successful OAuth access token response.", "type": "object", "properties": { "response_type": { "type": "string", "enum": [ "authorization_code", "refresh_token" ] }, "access_token": { "type": "string" }, "token_type": { "type": "string", "default": "bearer" }, "expires_in": { "type": "integer" }, "scope": { "type": "string" } }, "discriminator": { "propertyName": "response_type", "mapping": { "authorization_code": "#/components/schemas/OauthAccessTokenResponseCode", "refresh_token": "#/components/schemas/OauthAccessTokenResponseRefresh" } }, "required": [ "access_token", "token_type", "expires_in", "scope" ] }, "OauthAccessTokenResponseCode": { "title": "OAuth access token response", "description": "A successful OAuth access token response for the authorization code flow.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OauthAccessTokenResponse" }, { "type": "object", "properties": { "refresh_token": { "type": "string" }, "refresh_token_expires_in": { "type": "integer" } }, "required": [ "refresh_token", "refresh_token_expires_in" ] } ] }, "OauthAccessTokenResponseRefresh": { "title": "OAuth access token response", "description": "A successful OAuth access token response for the refresh token flow.", "type": "object", "allOf": [ { "$ref": "#/components/schemas/OauthAccessTokenResponse" } ] }, "OptimizationGoalMetadata": { "type": "object" }, "PacingDeliveryType": { "type": "string", "description": "Ad group pacing delivery type", "example": "STANDARD", "enum": [ "STANDARD", "ACCELERATED" ] }, "PlacementGroupType": { "type": "string", "description": "Campaign placement group type", "example": "ALL", "enum": [ "ALL", "SEARCH", "BROWSE", "OTHER" ] }, "Pin": { "title": "Pin", "description": "Pin", "type": "object", "properties": { "id": { "type": "string", "readOnly": true, "example": "813744226420795884" }, "created_at": { "type": "string", "format": "date-time", "readOnly": true, "example": "2020-01-01T20:10:40-00:00" }, "link": { "type": "string", "nullable": true, "example": "https://www.pinterest.com/" }, "title": { "type": "string", "nullable": true }, "description": { "type": "string", "nullable": true }, "dominant_color": { "type": "string", "nullable": true, "description": "Dominant pin color. Hex number, e.g. \\\"#6E7874\\\".", "example": "#6E7874" }, "alt_text": { "type": "string", "nullable": true }, "board_id": { "description": "The board to which this Pin belongs.", "type": "string", "pattern": "^\\d+$" }, "board_section_id": { "description": "The board section to which this Pin belongs.", "type": "string", "pattern": "^\\d+$", "nullable": true }, "board_owner": { "allOf": [ { "$ref": "#/components/schemas/BoardOwner" } ], "type": "object", "readOnly": true }, "media": { "allOf": [ { "$ref": "#/components/schemas/PinMedia" } ], "type": "object", "readOnly": true }, "media_source": { "allOf": [ { "$ref": "#/components/schemas/PinMediaSource" } ], "type": "object", "writeOnly": true }, "parent_pin_id": { "description": "The source pin id if this pin was saved from another pin. Learn more.", "type": "string", "pattern": "^\\d+$", "nullable": true } } }, "PinMedia": { "title": "Pin media", "description": "Pin media objects.", "discriminator": { "propertyName": "media_type", "mapping": { "image": "#/components/schemas/PinMediaWithImage", "video": "#/components/schemas/PinMediaWithVideo" } }, "properties": { "media_type": { "type": "string" } } }, "PinMediaWithImage": { "title": "image", "description": "Pin with image.", "allOf": [ { "type": "object", "properties": { "images": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ImageDetails" } } } }, { "$ref": "#/components/schemas/PinMedia" } ], "example": { "media_type": "image", "images": { "400x300": { "width": 400, "height": 300, "url": "https://i.pinimg.com/400x300/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg" }, "600x": { "width": 600, "height": 600, "url": "https://i.pinimg.com/600x/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg" }, "orig": { "width": 560, "height": 560, "url": "https://i.pinimg.com/originals/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg" } } } }, "PinMediaWithVideo": { "title": "video", "description": "Pin with video.", "allOf": [ { "type": "object", "properties": { "images": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/ImageDetails" } }, "cover_image_url": { "type": "string" }, "duration": { "type": "number", "description": "Duration (in milliseconds)" }, "height": { "type": "integer", "description": "Height (in pixels)" }, "width": { "type": "integer", "description": "Width (in pixels)" } } }, { "$ref": "#/components/schemas/PinMedia" } ], "example": { "media_type": "video", "images": { "400x300": { "width": 400, "height": 300, "url": "https://i.pinimg.com/400x300/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg" }, "600x": { "width": 600, "height": 600, "url": "https://i.pinimg.com/600x/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg" }, "orig": { "width": 560, "height": 560, "url": "https://i.pinimg.com/originals/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg" } }, "cover_image_url": "https://i.pinimg.com/videos/thumbnails/originals/a8/b9/38/a8b938b1dacc523054a6bac201e9f1d2.0000001.jpg", "duration": 14000, "height": 1064, "width": 1280 } }, "PinMediaSource": { "title": "Pin media source", "description": "Pin media source.", "oneOf": [ { "$ref": "#/components/schemas/PinMediaSourceImageBase64" }, { "$ref": "#/components/schemas/PinMediaSourceImageURL" }, { "$ref": "#/components/schemas/PinMediaSourceVideoID" } ], "discriminator": { "propertyName": "source_type", "mapping": { "image_base64": "#/components/schemas/PinMediaSourceImageBase64", "image_url": "#/components/schemas/PinMediaSourceImageURL", "video_id": "#/components/schemas/PinMediaSourceVideoID" } } }, "PinMediaSourceImageBase64": { "title": "Image Base64", "description": "Base64-encoded image media source", "type": "object", "properties": { "source_type": { "type": "string", "enum": [ "image_base64" ] }, "content_type": { "type": "string", "enum": [ "image/jpeg", "image/png" ] }, "data": { "type": "string", "pattern": "[a-zA-Z0-9+\\/=]+" } }, "required": [ "source_type", "content_type", "data" ] }, "PinMediaSourceImageURL": { "title": "Image URL", "description": "Image URL-based media source", "type": "object", "properties": { "source_type": { "type": "string", "enum": [ "image_url" ] }, "url": { "type": "string" } }, "required": [ "source_type", "url" ] }, "PinMediaSourceVideoID": { "title": "Video ID", "description": "Video ID-based media source", "type": "object", "properties": { "source_type": { "type": "string", "enum": [ "video_id" ] }, "cover_image_url": { "type": "string" }, "media_id": { "type": "string", "pattern": "^\\d+$" } }, "required": [ "source_type", "cover_image_url", "media_id" ] }, "ImageDetails": { "title": "ImageDetails", "type": "object", "properties": { "width": { "type": "integer", "minimum": 100 }, "height": { "type": "integer", "minimum": 100, "nullable": true }, "url": { "type": "string" } }, "required": [ "height", "width", "url" ], "example": { "width": 400, "height": 300, "url": "https://i.pinimg.com/400x300/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg" } }, "PinPromotionSummaryStatus": { "type": "string", "description": "Summary status for pin promotions", "example": "APPROVED", "enum": [ "APPROVED", "PAUSED", "PENDING", "REJECTED", "ADVERTISER_DISABLED", "ARCHIVED" ] }, "CreativeType": { "type": "string", "description": "Ad creative type enum", "enum": [ "REGULAR", "VIDEO", "SHOPPING", "CAROUSEL", "MAX_VIDEO", "SHOP_THE_PIN", "IDEA" ], "example": "REGULAR", "title": "CreativeType" }, "ProductAvailabilityType": { "nullable": true, "description": "Default availability for products in a feed.", "type": "string", "enum": [ "IN_STOCK", "OUT_OF_STOCK", "PREORDER", null ] }, "ProductGroupAnalyticsResponse": { "type": "array", "items": { "type": "object", "properties": { "PRODUCT_GROUP_ID": { "description": "The ID of the product 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": [ "PRODUCT_GROUP_ID" ], "additionalProperties": true, "example": { "DATE": "2021-04-01", "PRODUCT_GROUP_ID": "74629351736530", "SPEND_IN_DOLLAR": 30, "TOTAL_CLICKTHROUGH": 216 } } }, "ProductGroupSummaryStatus": { "type": "string", "description": "Summary status for product group", "example": "RUNNING", "enum": [ "RUNNING", "PAUSED", "EXCLUDED", "ARCHIVED" ] }, "ProductGroupPromotion": { "allOf": [ { "$ref": "#/components/schemas/ProductGroupPromotionCommon" } ], "properties": { "id": { "description": "ID of the product group promotion.", "example": "2680059592705", "title": "id", "type": "string", "pattern": "^\\d+$" }, "ad_group_id": { "description": "ID of the ad group the product group belongs to.", "example": "2680059592705", "pattern": "^(AG)?\\d+$", "title": "ad_group_id", "type": "string" }, "type": { "description": "Product group promotion", "example": "productgroup", "title": "type", "type": "string", "nullable": true }, "bid_in_micro_currency": { "description": "The bid in micro currency.", "example": 14000000, "title": "bid_in_micro_currency", "type": "integer" }, "included": { "description": "True if the group is BIDDABLE, false if it should be EXCLUDED from serving ads.", "example": true, "nullable": true, "title": "included", "type": "boolean" }, "definition": { "description": "The full product group definition path", "example": "*/product_type_0='kitchen'/product_type_1='beverage appliances'", "nullable": true, "title": "definition", "type": "string" }, "relative_definition": { "description": "The definition of the product group, relative to its parent - an attribute name/value pair", "example": "product_type_1='beverage appliances'", "nullable": true, "title": "relative_definition", "type": "string" }, "parent_id": { "description": "The parent Product Group ID of this Product Group", "example": "1231234", "nullable": true, "title": "parent_id", "type": "string", "pattern": "^\\d+$" }, "slideshow_collections_title": { "description": "Slideshow Collections Title", "example": "slideshow title", "nullable": true, "title": "slideshow_collections_title", "type": "string" }, "slideshow_collections_description": { "description": "Slideshow Collections Description", "example": "slideshow description", "nullable": true, "title": "slideshow_collections_description", "type": "string" } }, "type": "object", "title": "ProductGroupPromotion" }, "ProductGroupPromotionCommon": { "properties": { "status": { "$ref": "#/components/schemas/EntityStatus" }, "tracking_url": { "description": "Tracking template for proudct group promotions. 4000 limit", "example": "https://www.pinterest.com", "nullable": true, "title": "tracking_url", "type": "string" }, "catalogs_product_group_id": { "description": "ID of the catalogs product group that this product group promotion references", "example": "1231235", "title": "catalogs_product_group_id", "type": "string", "pattern": "^\\d+$" }, "catalogs_product_group_name": { "description": "Catalogs product group", "example": "catalogProductGroupName", "title": "product_group_promotion_name", "type": "string" }, "creative_type": { "$ref": "#/components/schemas/CreativeType" }, "collections_hero_pin_id": { "description": "Hero Pin ID if this PG is promoted as a Collection", "example": "123123", "nullable": true, "title": "collections_hero_pin_id", "type": "string", "pattern": "^\\d+$" }, "collections_hero_destination_url": { "description": "Collections Hero Destination Url", "example": "http://www.pinterest.com", "nullable": true, "title": "collections_hero_destination_url", "type": "string" }, "slideshow_collections_title": { "description": "Slideshow Collections Title", "example": "Title", "nullable": true, "title": "slideshow_collections_title", "type": "string" }, "slideshow_collections_description": { "description": "Slideshow Collections Description", "example": "Description", "nullable": true, "title": "slideshow_collections_description", "type": "string" } }, "title": "ProductGroupPromotionCommon", "type": "object" }, "ProductGroupPromotionCreateRequest": { "example": { "product_group_promotion": [ { "slideshow_collections_description": "Description", "creative_type": "REGULAR", "collections_hero_pin_id": "123123", "product_group_promotion_name": "catalogProductGroupName", "collections_hero_destination_url": "http://www.pinterest.com", "tracking_url": "https://www.pinterest.com", "slideshow_collections_title": "Title", "status": "ACTIVE" }, { "slideshow_collections_description": "Description", "creative_type": "REGULAR", "collections_hero_pin_id": "123123", "product_group_promotion_name": "catalogProductGroupName", "collections_hero_destination_url": "http://www.pinterest.com", "tracking_url": "https://www.pinterest.com", "slideshow_collections_title": "Title", "status": "ACTIVE" } ], "ad_group_id": "2680059592705" }, "properties": { "ad_group_id": { "description": "ID of the Ad Group the Product Group Promotion belongs to.", "example": "2680059592705", "pattern": "^(AG)?\\d+$", "title": "ad_group_id", "type": "string" }, "product_group_promotion": { "items": { "$ref": "#/components/schemas/ProductGroupPromotionCommon" }, "title": "product_group_promotion", "type": "array" } }, "required": [ "ad_group_id", "product_group_promotion" ], "title": "ProductGroupPromotionCreateRequest", "type": "object" }, "ProductGroupPromotionArrayResponse": { "description": "Product group promotions array.", "items": { "$ref": "#/components/schemas/ProductGroupPromotionArrayElement" }, "title": "ProductGroupPromotionArrayResponse", "type": "array" }, "ProductGroupPromotionArrayElement": { "properties": { "data": { "$ref": "#/components/schemas/ProductGroupPromotion" }, "exceptions": { "$ref": "#/components/schemas/Exception" } }, "title": "ProductGroupPromotionArrayElement", "type": "object" }, "ProductGroupPromotionUpdateItem": { "properties": { "id": { "description": "ID of the product group.", "example": "2680059592705", "title": "id", "type": "string" } }, "title": "ProductGroupPromotionUpdateItem" }, "ProductGroupPromotionUpdateResponseItem": { "properties": { "data": { "$ref": "#/components/schemas/ProductGroupPromotion" }, "exceptions": { "$ref": "#/components/schemas/Exception" } }, "title": "ProductGroupPromotionUpdateResponseItem", "type": "object" }, "ProductGroupPromotionUpdateRequest": { "example": { "product_group_promotion": [ { "catalogs_product_group_id": "1234123", "slideshow_collections_description": "Description", "creative_type": "REGULAR", "collections_hero_pin_id": "123123", "product_group_promotion_name": "ProductGroupName", "collections_hero_destination_url": "http://www.pinterest.com", "tracking_url": "https://www.pinterest.com", "slideshow_collections_title": "Title", "status": "ACTIVE", "id": "2680059592705" }, { "catalogs_product_group_id": "1231231", "slideshow_collections_description": "Other description", "creative_type": "REGULAR", "collections_hero_pin_id": "123124", "product_group_promotion_name": "ProductGroupName", "collections_hero_destination_url": "http://www.pinterest.com", "tracking_url": "https://www.pinterest.com", "slideshow_collections_title": "Title", "status": "ACTIVE", "id": "2680059592706" } ], "ad_group_id": "26823439592705" }, "properties": { "ad_group_id": { "description": "ID of the ad group the product group belongs to.", "example": "2680059592705", "pattern": "^(AG)?\\d+$", "title": "ad_group_id", "type": "string" }, "product_group_promotion": { "items": { "$ref": "#/components/schemas/ProductGroupPromotionUpdateItem" }, "title": "product_group_promotion", "type": "array" } }, "required": [ "ad_group_id", "product_group_promotion" ], "title": "ProductGroupPromotionUpdateRequest", "type": "object" }, "ReportingColumnAsync": { "type": "string", "description": "Reporting columns", "example": "SPEND_IN_MICRO_DOLLAR", "enum": [ "SPEND_IN_MICRO_DOLLAR", "PAID_IMPRESSION", "CPC_IN_MICRO_DOLLAR", "ECPC_IN_MICRO_DOLLAR", "CTR", "ECTR", "CAMPAIGN_NAME", "CAMPAIGN_STATUS", "AD_STATUS", "PIN_PROMOTION_STATUS", "PIN_ID", "TOTAL_ENGAGEMENT", "ENGAGEMENT_1", "ENGAGEMENT_2", "ECPM_IN_MICRO_DOLLAR", "CTR_2", "CAMPAIGN_ID", "ADVERTISER_ID", "AD_ACCOUNT_ID", "PIN_PROMOTION_ID", "AD_ID", "AD_GROUP_ID", "CAMPAIGN_MANAGED_STATUS", "CPM_IN_MICRO_DOLLAR", "AD_GROUP_NAME", "AD_GROUP_STATUS", "PRODUCT_GROUP_ID", "CLICKTHROUGH_1", "REPIN_1", "IMPRESSION_1", "IMPRESSION_1_GROSS", "CLICKTHROUGH_1_GROSS", "OUTBOUND_CLICK_1", "CLICKTHROUGH_2", "REPIN_2", "IMPRESSION_2", "OUTBOUND_CLICK_2", "TOTAL_IMPRESSION_USER", "TOTAL_IMPRESSION_FREQUENCY", "TOTAL_ENGAGEMENT_PAGE_VISIT", "TOTAL_ENGAGEMENT_SIGNUP", "TOTAL_ENGAGEMENT_CHECKOUT", "TOTAL_ENGAGEMENT_CUSTOM", "TOTAL_ENGAGEMENT_ADD_TO_CART", "TOTAL_ENGAGEMENT_LEAD", "TOTAL_ENGAGEMENT_SEARCH", "TOTAL_ENGAGEMENT_WATCH_VIDEO", "TOTAL_ENGAGEMENT_VIEW_CATEGORY", "TOTAL_ENGAGEMENT_APP_INSTALL", "TOTAL_ENGAGEMENT_UNKNOWN", "TOTAL_CLICK_PAGE_VISIT", "TOTAL_CLICK_SIGNUP", "TOTAL_CLICK_CHECKOUT", "TOTAL_CLICK_CUSTOM", "TOTAL_CLICK_ADD_TO_CART", "TOTAL_CLICK_LEAD", "TOTAL_CLICK_SEARCH", "TOTAL_CLICK_WATCH_VIDEO", "TOTAL_CLICK_VIEW_CATEGORY", "TOTAL_CLICK_APP_INSTALL", "TOTAL_CLICK_UNKNOWN", "TOTAL_VIEW_PAGE_VISIT", "TOTAL_VIEW_SIGNUP", "TOTAL_VIEW_CHECKOUT", "TOTAL_VIEW_CUSTOM", "TOTAL_VIEW_ADD_TO_CART", "TOTAL_VIEW_LEAD", "TOTAL_VIEW_SEARCH", "TOTAL_VIEW_WATCH_VIDEO", "TOTAL_VIEW_VIEW_CATEGORY", "TOTAL_VIEW_APP_INSTALL", "TOTAL_VIEW_UNKNOWN", "TOTAL_CONVERSIONS", "TOTAL_ENGAGEMENT_PAGE_VISIT_VALUE_IN_MICRO_DOLLAR", "TOTAL_ENGAGEMENT_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_ENGAGEMENT_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_ENGAGEMENT_CUSTOM_VALUE_IN_MICRO_DOLLAR", "TOTAL_ENGAGEMENT_ADD_TO_CART_VALUE_IN_MICRO_DOLLAR", "TOTAL_ENGAGEMENT_LEAD_VALUE_IN_MICRO_DOLLAR", "TOTAL_ENGAGEMENT_SEARCH_VALUE_IN_MICRO_DOLLAR", "TOTAL_ENGAGEMENT_WATCH_VIDEO_VALUE_IN_MICRO_DOLLAR", "TOTAL_ENGAGEMENT_VIEW_CATEGORY_VALUE_IN_MICRO_DOLLAR", "TOTAL_ENGAGEMENT_APP_INSTALL_VALUE_IN_MICRO_DOLLAR", "TOTAL_ENGAGEMENT_UNKNOWN_VALUE_IN_MICRO_DOLLAR", "TOTAL_CLICK_PAGE_VISIT_VALUE_IN_MICRO_DOLLAR", "TOTAL_CLICK_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_CLICK_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_CLICK_CUSTOM_VALUE_IN_MICRO_DOLLAR", "TOTAL_CLICK_ADD_TO_CART_VALUE_IN_MICRO_DOLLAR", "TOTAL_CLICK_LEAD_VALUE_IN_MICRO_DOLLAR", "TOTAL_CLICK_SEARCH_VALUE_IN_MICRO_DOLLAR", "TOTAL_CLICK_WATCH_VIDEO_VALUE_IN_MICRO_DOLLAR", "TOTAL_CLICK_VIEW_CATEGORY_VALUE_IN_MICRO_DOLLAR", "TOTAL_CLICK_APP_INSTALL_VALUE_IN_MICRO_DOLLAR", "TOTAL_CLICK_UNKNOWN_VALUE_IN_MICRO_DOLLAR", "TOTAL_VIEW_PAGE_VISIT_VALUE_IN_MICRO_DOLLAR", "TOTAL_VIEW_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_VIEW_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_VIEW_CUSTOM_VALUE_IN_MICRO_DOLLAR", "TOTAL_VIEW_ADD_TO_CART_VALUE_IN_MICRO_DOLLAR", "TOTAL_VIEW_LEAD_VALUE_IN_MICRO_DOLLAR", "TOTAL_VIEW_SEARCH_VALUE_IN_MICRO_DOLLAR", "TOTAL_VIEW_WATCH_VIDEO_VALUE_IN_MICRO_DOLLAR", "TOTAL_VIEW_VIEW_CATEGORY_VALUE_IN_MICRO_DOLLAR", "TOTAL_VIEW_APP_INSTALL_VALUE_IN_MICRO_DOLLAR", "TOTAL_VIEW_UNKNOWN_VALUE_IN_MICRO_DOLLAR", "TOTAL_CONVERSIONS_VALUE_IN_MICRO_DOLLAR", "TOTAL_ENGAGEMENT_PAGE_VISIT_QUANTITY", "TOTAL_ENGAGEMENT_SIGNUP_QUANTITY", "TOTAL_ENGAGEMENT_CHECKOUT_QUANTITY", "TOTAL_ENGAGEMENT_CUSTOM_QUANTITY", "TOTAL_ENGAGEMENT_ADD_TO_CART_QUANTITY", "TOTAL_ENGAGEMENT_LEAD_QUANTITY", "TOTAL_ENGAGEMENT_SEARCH_QUANTITY", "TOTAL_ENGAGEMENT_WATCH_VIDEO_QUANTITY", "TOTAL_ENGAGEMENT_VIEW_CATEGORY_QUANTITY", "TOTAL_ENGAGEMENT_UNKNOWN_QUANTITY", "TOTAL_CLICK_PAGE_VISIT_QUANTITY", "TOTAL_CLICK_SIGNUP_QUANTITY", "TOTAL_CLICK_CHECKOUT_QUANTITY", "TOTAL_CLICK_CUSTOM_QUANTITY", "TOTAL_CLICK_ADD_TO_CART_QUANTITY", "TOTAL_CLICK_LEAD_QUANTITY", "TOTAL_CLICK_SEARCH_QUANTITY", "TOTAL_CLICK_WATCH_VIDEO_QUANTITY", "TOTAL_CLICK_VIEW_CATEGORY_QUANTITY", "TOTAL_CLICK_UNKNOWN_QUANTITY", "TOTAL_VIEW_PAGE_VISIT_QUANTITY", "TOTAL_VIEW_SIGNUP_QUANTITY", "TOTAL_VIEW_CHECKOUT_QUANTITY", "TOTAL_VIEW_CUSTOM_QUANTITY", "TOTAL_VIEW_ADD_TO_CART_QUANTITY", "TOTAL_VIEW_LEAD_QUANTITY", "TOTAL_VIEW_SEARCH_QUANTITY", "TOTAL_VIEW_WATCH_VIDEO_QUANTITY", "TOTAL_VIEW_VIEW_CATEGORY_QUANTITY", "TOTAL_VIEW_UNKNOWN_QUANTITY", "TOTAL_CONVERSIONS_QUANTITY", "ONSITE_CHECKOUTS_1", "PIN_PROMOTION_NAME", "AD_NAME", "CAMPAIGN_LIFETIME_SPEND_CAP", "CAMPAIGN_DAILY_SPEND_CAP", "TOTAL_PAGE_VISIT_DESKTOP_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_PAGE_VISIT_DESKTOP_ACTION_TO_MOBILE_CONVERSION", "TOTAL_PAGE_VISIT_DESKTOP_ACTION_TO_TABLET_CONVERSION", "TOTAL_PAGE_VISIT_MOBILE_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_PAGE_VISIT_MOBILE_ACTION_TO_MOBILE_CONVERSION", "TOTAL_PAGE_VISIT_MOBILE_ACTION_TO_TABLET_CONVERSION", "TOTAL_PAGE_VISIT_TABLET_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_PAGE_VISIT_TABLET_ACTION_TO_MOBILE_CONVERSION", "TOTAL_PAGE_VISIT_TABLET_ACTION_TO_TABLET_CONVERSION", "TOTAL_SIGNUP_DESKTOP_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_SIGNUP_DESKTOP_ACTION_TO_MOBILE_CONVERSION", "TOTAL_SIGNUP_DESKTOP_ACTION_TO_TABLET_CONVERSION", "TOTAL_SIGNUP_MOBILE_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_SIGNUP_MOBILE_ACTION_TO_MOBILE_CONVERSION", "TOTAL_SIGNUP_MOBILE_ACTION_TO_TABLET_CONVERSION", "TOTAL_SIGNUP_TABLET_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_SIGNUP_TABLET_ACTION_TO_MOBILE_CONVERSION", "TOTAL_SIGNUP_TABLET_ACTION_TO_TABLET_CONVERSION", "TOTAL_CHECKOUT_DESKTOP_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_CHECKOUT_DESKTOP_ACTION_TO_MOBILE_CONVERSION", "TOTAL_CHECKOUT_DESKTOP_ACTION_TO_TABLET_CONVERSION", "TOTAL_CHECKOUT_MOBILE_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_CHECKOUT_MOBILE_ACTION_TO_MOBILE_CONVERSION", "TOTAL_CHECKOUT_MOBILE_ACTION_TO_TABLET_CONVERSION", "TOTAL_CHECKOUT_TABLET_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_CHECKOUT_TABLET_ACTION_TO_MOBILE_CONVERSION", "TOTAL_CHECKOUT_TABLET_ACTION_TO_TABLET_CONVERSION", "TOTAL_CUSTOM_DESKTOP_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_CUSTOM_DESKTOP_ACTION_TO_MOBILE_CONVERSION", "TOTAL_CUSTOM_DESKTOP_ACTION_TO_TABLET_CONVERSION", "TOTAL_CUSTOM_MOBILE_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_CUSTOM_MOBILE_ACTION_TO_MOBILE_CONVERSION", "TOTAL_CUSTOM_MOBILE_ACTION_TO_TABLET_CONVERSION", "TOTAL_CUSTOM_TABLET_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_CUSTOM_TABLET_ACTION_TO_MOBILE_CONVERSION", "TOTAL_CUSTOM_TABLET_ACTION_TO_TABLET_CONVERSION", "TOTAL_ADD_TO_CART_DESKTOP_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_ADD_TO_CART_DESKTOP_ACTION_TO_MOBILE_CONVERSION", "TOTAL_ADD_TO_CART_DESKTOP_ACTION_TO_TABLET_CONVERSION", "TOTAL_ADD_TO_CART_MOBILE_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_ADD_TO_CART_MOBILE_ACTION_TO_MOBILE_CONVERSION", "TOTAL_ADD_TO_CART_MOBILE_ACTION_TO_TABLET_CONVERSION", "TOTAL_ADD_TO_CART_TABLET_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_ADD_TO_CART_TABLET_ACTION_TO_MOBILE_CONVERSION", "TOTAL_ADD_TO_CART_TABLET_ACTION_TO_TABLET_CONVERSION", "TOTAL_LEAD_DESKTOP_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_LEAD_DESKTOP_ACTION_TO_MOBILE_CONVERSION", "TOTAL_LEAD_DESKTOP_ACTION_TO_TABLET_CONVERSION", "TOTAL_LEAD_MOBILE_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_LEAD_MOBILE_ACTION_TO_MOBILE_CONVERSION", "TOTAL_LEAD_MOBILE_ACTION_TO_TABLET_CONVERSION", "TOTAL_LEAD_TABLET_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_LEAD_TABLET_ACTION_TO_MOBILE_CONVERSION", "TOTAL_LEAD_TABLET_ACTION_TO_TABLET_CONVERSION", "TOTAL_SEARCH_DESKTOP_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_SEARCH_DESKTOP_ACTION_TO_MOBILE_CONVERSION", "TOTAL_SEARCH_DESKTOP_ACTION_TO_TABLET_CONVERSION", "TOTAL_SEARCH_MOBILE_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_SEARCH_MOBILE_ACTION_TO_MOBILE_CONVERSION", "TOTAL_SEARCH_MOBILE_ACTION_TO_TABLET_CONVERSION", "TOTAL_SEARCH_TABLET_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_SEARCH_TABLET_ACTION_TO_MOBILE_CONVERSION", "TOTAL_SEARCH_TABLET_ACTION_TO_TABLET_CONVERSION", "TOTAL_WATCH_VIDEO_DESKTOP_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_WATCH_VIDEO_DESKTOP_ACTION_TO_MOBILE_CONVERSION", "TOTAL_WATCH_VIDEO_DESKTOP_ACTION_TO_TABLET_CONVERSION", "TOTAL_WATCH_VIDEO_MOBILE_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_WATCH_VIDEO_MOBILE_ACTION_TO_MOBILE_CONVERSION", "TOTAL_WATCH_VIDEO_MOBILE_ACTION_TO_TABLET_CONVERSION", "TOTAL_WATCH_VIDEO_TABLET_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_WATCH_VIDEO_TABLET_ACTION_TO_MOBILE_CONVERSION", "TOTAL_WATCH_VIDEO_TABLET_ACTION_TO_TABLET_CONVERSION", "TOTAL_VIEW_CATEGORY_DESKTOP_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_VIEW_CATEGORY_DESKTOP_ACTION_TO_MOBILE_CONVERSION", "TOTAL_VIEW_CATEGORY_DESKTOP_ACTION_TO_TABLET_CONVERSION", "TOTAL_VIEW_CATEGORY_MOBILE_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_VIEW_CATEGORY_MOBILE_ACTION_TO_MOBILE_CONVERSION", "TOTAL_VIEW_CATEGORY_MOBILE_ACTION_TO_TABLET_CONVERSION", "TOTAL_VIEW_CATEGORY_TABLET_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_VIEW_CATEGORY_TABLET_ACTION_TO_MOBILE_CONVERSION", "TOTAL_VIEW_CATEGORY_TABLET_ACTION_TO_TABLET_CONVERSION", "TOTAL_APP_INSTALL_DESKTOP_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_APP_INSTALL_DESKTOP_ACTION_TO_MOBILE_CONVERSION", "TOTAL_APP_INSTALL_DESKTOP_ACTION_TO_TABLET_CONVERSION", "TOTAL_APP_INSTALL_MOBILE_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_APP_INSTALL_MOBILE_ACTION_TO_MOBILE_CONVERSION", "TOTAL_APP_INSTALL_MOBILE_ACTION_TO_TABLET_CONVERSION", "TOTAL_APP_INSTALL_TABLET_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_APP_INSTALL_TABLET_ACTION_TO_MOBILE_CONVERSION", "TOTAL_APP_INSTALL_TABLET_ACTION_TO_TABLET_CONVERSION", "TOTAL_UNKNOWN_DESKTOP_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_UNKNOWN_DESKTOP_ACTION_TO_MOBILE_CONVERSION", "TOTAL_UNKNOWN_DESKTOP_ACTION_TO_TABLET_CONVERSION", "TOTAL_UNKNOWN_MOBILE_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_UNKNOWN_MOBILE_ACTION_TO_MOBILE_CONVERSION", "TOTAL_UNKNOWN_MOBILE_ACTION_TO_TABLET_CONVERSION", "TOTAL_UNKNOWN_TABLET_ACTION_TO_DESKTOP_CONVERSION", "TOTAL_UNKNOWN_TABLET_ACTION_TO_MOBILE_CONVERSION", "TOTAL_UNKNOWN_TABLET_ACTION_TO_TABLET_CONVERSION", "TOTAL_CHECKOUT", "TOTAL_CUSTOM", "TOTAL_LEAD", "TOTAL_APP_INSTALL", "TOTAL_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_APP_INSTALL_VALUE_IN_MICRO_DOLLAR", "TOTAL_CHECKOUT_QUANTITY", "APP_INSTALL_COST_PER_ACTION", "VIDEO_3SEC_VIEWS_1", "VIDEO_P100_COMPLETE_1", "VIDEO_P0_COMBINED_1", "VIDEO_P25_COMBINED_1", "VIDEO_P50_COMBINED_1", "VIDEO_P75_COMBINED_1", "VIDEO_P95_COMBINED_1", "VIDEO_MRC_VIEWS_1", "VIDEO_3SEC_VIEWS_2", "VIDEO_P100_COMPLETE_2", "VIDEO_P0_COMBINED_2", "VIDEO_P25_COMBINED_2", "VIDEO_P50_COMBINED_2", "VIDEO_P75_COMBINED_2", "VIDEO_P95_COMBINED_2", "VIDEO_MRC_VIEWS_2", "VIDEO_LENGTH", "CPV_IN_MICRO_DOLLAR", "CPCV_IN_MICRO_DOLLAR", "CPCV_P95_IN_MICRO_DOLLAR", "TOTAL_VIDEO_3SEC_VIEWS", "VIDEO_AVG_WATCHTIME_IN_SECOND_1", "VIDEO_AVG_WATCHTIME_IN_SECOND_2", "TOTAL_VIDEO_AVG_WATCHTIME_IN_SECOND", "WEB_CHECKOUT_COST_PER_ACTION", "WEB_CHECKOUT_ROAS", "TOTAL_WEB_CHECKOUT", "TOTAL_WEB_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_CLICK_CHECKOUT", "TOTAL_WEB_CLICK_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_ENGAGEMENT_CHECKOUT", "TOTAL_WEB_ENGAGEMENT_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_VIEW_CHECKOUT", "TOTAL_WEB_VIEW_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "INAPP_CHECKOUT_COST_PER_ACTION", "INAPP_CHECKOUT_ROAS", "TOTAL_INAPP_CHECKOUT", "TOTAL_INAPP_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_CLICK_CHECKOUT", "TOTAL_INAPP_CLICK_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_ENGAGEMENT_CHECKOUT", "TOTAL_INAPP_ENGAGEMENT_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_VIEW_CHECKOUT", "TOTAL_INAPP_VIEW_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "OFFLINE_CHECKOUT_COST_PER_ACTION", "OFFLINE_CHECKOUT_ROAS", "TOTAL_OFFLINE_CHECKOUT", "TOTAL_OFFLINE_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_OFFLINE_CLICK_CHECKOUT", "TOTAL_OFFLINE_CLICK_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_OFFLINE_ENGAGEMENT_CHECKOUT", "TOTAL_OFFLINE_ENGAGEMENT_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_OFFLINE_VIEW_CHECKOUT", "TOTAL_OFFLINE_VIEW_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "WEB_ADD_TO_CART_COST_PER_ACTION", "WEB_ADD_TO_CART_ROAS", "TOTAL_WEB_ADD_TO_CART", "TOTAL_WEB_ADD_TO_CART_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_CLICK_ADD_TO_CART", "TOTAL_WEB_CLICK_ADD_TO_CART_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_ENGAGEMENT_ADD_TO_CART", "TOTAL_WEB_ENGAGEMENT_ADD_TO_CART_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_VIEW_ADD_TO_CART", "TOTAL_WEB_VIEW_ADD_TO_CART_VALUE_IN_MICRO_DOLLAR", "INAPP_ADD_TO_CART_COST_PER_ACTION", "INAPP_ADD_TO_CART_ROAS", "TOTAL_INAPP_ADD_TO_CART", "TOTAL_INAPP_ADD_TO_CART_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_CLICK_ADD_TO_CART", "TOTAL_INAPP_CLICK_ADD_TO_CART_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_ENGAGEMENT_ADD_TO_CART", "TOTAL_INAPP_ENGAGEMENT_ADD_TO_CART_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_VIEW_ADD_TO_CART", "TOTAL_INAPP_VIEW_ADD_TO_CART_VALUE_IN_MICRO_DOLLAR", "WEB_PAGE_VISIT_COST_PER_ACTION", "WEB_PAGE_VISIT_ROAS", "TOTAL_WEB_PAGE_VISIT", "TOTAL_WEB_PAGE_VISIT_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_CLICK_PAGE_VISIT", "TOTAL_WEB_CLICK_PAGE_VISIT_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_ENGAGEMENT_PAGE_VISIT", "TOTAL_WEB_ENGAGEMENT_PAGE_VISIT_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_VIEW_PAGE_VISIT", "TOTAL_WEB_VIEW_PAGE_VISIT_VALUE_IN_MICRO_DOLLAR", "WEB_SIGNUP_COST_PER_ACTION", "WEB_SIGNUP_ROAS", "TOTAL_WEB_SIGNUP", "TOTAL_WEB_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_CLICK_SIGNUP", "TOTAL_WEB_CLICK_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_ENGAGEMENT_SIGNUP", "TOTAL_WEB_ENGAGEMENT_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_VIEW_SIGNUP", "TOTAL_WEB_VIEW_SIGNUP_VALUE_IN_MICRO_DOLLAR", "INAPP_SIGNUP_COST_PER_ACTION", "INAPP_SIGNUP_ROAS", "TOTAL_INAPP_SIGNUP", "TOTAL_INAPP_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_CLICK_SIGNUP", "TOTAL_INAPP_CLICK_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_ENGAGEMENT_SIGNUP", "TOTAL_INAPP_ENGAGEMENT_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_VIEW_SIGNUP", "TOTAL_INAPP_VIEW_SIGNUP_VALUE_IN_MICRO_DOLLAR", "OFFLINE_SIGNUP_COST_PER_ACTION", "OFFLINE_SIGNUP_ROAS", "TOTAL_OFFLINE_SIGNUP", "TOTAL_OFFLINE_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_OFFLINE_CLICK_SIGNUP", "TOTAL_OFFLINE_CLICK_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_OFFLINE_ENGAGEMENT_SIGNUP", "TOTAL_OFFLINE_ENGAGEMENT_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_OFFLINE_VIEW_SIGNUP", "TOTAL_OFFLINE_VIEW_SIGNUP_VALUE_IN_MICRO_DOLLAR", "WEB_WATCH_VIDEO_COST_PER_ACTION", "WEB_WATCH_VIDEO_ROAS", "TOTAL_WEB_WATCH_VIDEO", "TOTAL_WEB_WATCH_VIDEO_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_CLICK_WATCH_VIDEO", "TOTAL_WEB_CLICK_WATCH_VIDEO_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_ENGAGEMENT_WATCH_VIDEO", "TOTAL_WEB_ENGAGEMENT_WATCH_VIDEO_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_VIEW_WATCH_VIDEO", "TOTAL_WEB_VIEW_WATCH_VIDEO_VALUE_IN_MICRO_DOLLAR", "WEB_LEAD_COST_PER_ACTION", "WEB_LEAD_ROAS", "TOTAL_WEB_LEAD", "TOTAL_WEB_LEAD_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_CLICK_LEAD", "TOTAL_WEB_CLICK_LEAD_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_ENGAGEMENT_LEAD", "TOTAL_WEB_ENGAGEMENT_LEAD_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_VIEW_LEAD", "TOTAL_WEB_VIEW_LEAD_VALUE_IN_MICRO_DOLLAR", "OFFLINE_LEAD_COST_PER_ACTION", "OFFLINE_LEAD_ROAS", "TOTAL_OFFLINE_LEAD", "TOTAL_OFFLINE_LEAD_VALUE_IN_MICRO_DOLLAR", "TOTAL_OFFLINE_CLICK_LEAD", "TOTAL_OFFLINE_CLICK_LEAD_VALUE_IN_MICRO_DOLLAR", "TOTAL_OFFLINE_ENGAGEMENT_LEAD", "TOTAL_OFFLINE_ENGAGEMENT_LEAD_VALUE_IN_MICRO_DOLLAR", "TOTAL_OFFLINE_VIEW_LEAD", "TOTAL_OFFLINE_VIEW_LEAD_VALUE_IN_MICRO_DOLLAR", "WEB_SEARCH_COST_PER_ACTION", "WEB_SEARCH_ROAS", "TOTAL_WEB_SEARCH", "TOTAL_WEB_SEARCH_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_CLICK_SEARCH", "TOTAL_WEB_CLICK_SEARCH_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_ENGAGEMENT_SEARCH", "TOTAL_WEB_ENGAGEMENT_SEARCH_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_VIEW_SEARCH", "TOTAL_WEB_VIEW_SEARCH_VALUE_IN_MICRO_DOLLAR", "INAPP_SEARCH_COST_PER_ACTION", "INAPP_SEARCH_ROAS", "TOTAL_INAPP_SEARCH", "TOTAL_INAPP_SEARCH_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_CLICK_SEARCH", "TOTAL_INAPP_CLICK_SEARCH_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_ENGAGEMENT_SEARCH", "TOTAL_INAPP_ENGAGEMENT_SEARCH_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_VIEW_SEARCH", "TOTAL_INAPP_VIEW_SEARCH_VALUE_IN_MICRO_DOLLAR", "WEB_VIEW_CATEGORY_COST_PER_ACTION", "WEB_VIEW_CATEGORY_ROAS", "TOTAL_WEB_VIEW_CATEGORY", "TOTAL_WEB_VIEW_CATEGORY_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_CLICK_VIEW_CATEGORY", "TOTAL_WEB_CLICK_VIEW_CATEGORY_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_ENGAGEMENT_VIEW_CATEGORY", "TOTAL_WEB_ENGAGEMENT_VIEW_CATEGORY_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_VIEW_VIEW_CATEGORY", "TOTAL_WEB_VIEW_VIEW_CATEGORY_VALUE_IN_MICRO_DOLLAR", "WEB_CUSTOM_COST_PER_ACTION", "WEB_CUSTOM_ROAS", "TOTAL_WEB_CUSTOM", "TOTAL_WEB_CUSTOM_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_CLICK_CUSTOM", "TOTAL_WEB_CLICK_CUSTOM_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_ENGAGEMENT_CUSTOM", "TOTAL_WEB_ENGAGEMENT_CUSTOM_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_VIEW_CUSTOM", "TOTAL_WEB_VIEW_CUSTOM_VALUE_IN_MICRO_DOLLAR", "OFFLINE_CUSTOM_COST_PER_ACTION", "OFFLINE_CUSTOM_ROAS", "TOTAL_OFFLINE_CUSTOM", "TOTAL_OFFLINE_CUSTOM_VALUE_IN_MICRO_DOLLAR", "TOTAL_OFFLINE_CLICK_CUSTOM", "TOTAL_OFFLINE_CLICK_CUSTOM_VALUE_IN_MICRO_DOLLAR", "TOTAL_OFFLINE_ENGAGEMENT_CUSTOM", "TOTAL_OFFLINE_ENGAGEMENT_CUSTOM_VALUE_IN_MICRO_DOLLAR", "TOTAL_OFFLINE_VIEW_CUSTOM", "TOTAL_OFFLINE_VIEW_CUSTOM_VALUE_IN_MICRO_DOLLAR", "WEB_UNKNOWN_COST_PER_ACTION", "WEB_UNKNOWN_ROAS", "TOTAL_WEB_UNKNOWN", "TOTAL_WEB_UNKNOWN_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_CLICK_UNKNOWN", "TOTAL_WEB_CLICK_UNKNOWN_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_ENGAGEMENT_UNKNOWN", "TOTAL_WEB_ENGAGEMENT_UNKNOWN_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_VIEW_UNKNOWN", "TOTAL_WEB_VIEW_UNKNOWN_VALUE_IN_MICRO_DOLLAR", "INAPP_UNKNOWN_COST_PER_ACTION", "INAPP_UNKNOWN_ROAS", "TOTAL_INAPP_UNKNOWN", "TOTAL_INAPP_UNKNOWN_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_CLICK_UNKNOWN", "TOTAL_INAPP_CLICK_UNKNOWN_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_ENGAGEMENT_UNKNOWN", "TOTAL_INAPP_ENGAGEMENT_UNKNOWN_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_VIEW_UNKNOWN", "TOTAL_INAPP_VIEW_UNKNOWN_VALUE_IN_MICRO_DOLLAR", "OFFLINE_UNKNOWN_COST_PER_ACTION", "OFFLINE_UNKNOWN_ROAS", "TOTAL_OFFLINE_UNKNOWN", "TOTAL_OFFLINE_UNKNOWN_VALUE_IN_MICRO_DOLLAR", "TOTAL_OFFLINE_CLICK_UNKNOWN", "TOTAL_OFFLINE_CLICK_UNKNOWN_VALUE_IN_MICRO_DOLLAR", "TOTAL_OFFLINE_ENGAGEMENT_UNKNOWN", "TOTAL_OFFLINE_ENGAGEMENT_UNKNOWN_VALUE_IN_MICRO_DOLLAR", "TOTAL_OFFLINE_VIEW_UNKNOWN", "TOTAL_OFFLINE_VIEW_UNKNOWN_VALUE_IN_MICRO_DOLLAR", "INAPP_APP_INSTALL_COST_PER_ACTION", "INAPP_APP_INSTALL_ROAS", "TOTAL_INAPP_APP_INSTALL", "TOTAL_INAPP_APP_INSTALL_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_CLICK_APP_INSTALL", "TOTAL_INAPP_CLICK_APP_INSTALL_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_ENGAGEMENT_APP_INSTALL", "TOTAL_INAPP_ENGAGEMENT_APP_INSTALL_VALUE_IN_MICRO_DOLLAR", "TOTAL_INAPP_VIEW_APP_INSTALL", "TOTAL_INAPP_VIEW_APP_INSTALL_VALUE_IN_MICRO_DOLLAR", "IDEA_PIN_PRODUCT_TAG_VISIT_1", "IDEA_PIN_PRODUCT_TAG_VISIT_2", "REPIN_RATE", "TOTAL_VIDEO_P95_COMBINED", "AD_GROUP_ENTITY_STATUS", "ECPCV_P95_IN_DOLLAR", "ENGAGEMENT_RATE", "PAGE_VISIT_COST_PER_ACTION", "TOTAL_PAGE_VISIT", "CHECKOUT_ROAS", "TOTAL_SIGNUP_VALUE_IN_MICRO_DOLLAR", "ECPCV_IN_DOLLAR", "TOTAL_VIDEO_P75_COMBINED", "TOTAL_VIDEO_P50_COMBINED", "TOTAL_SIGNUP", "TOTAL_VIDEO_P0_COMBINED", "SPEND_IN_DOLLAR", "EENGAGEMENT_RATE", "TOTAL_VIDEO_P25_COMBINED", "CPM_IN_DOLLAR", "ECPV_IN_DOLLAR", "TOTAL_CLICKTHROUGH", "ECPE_IN_DOLLAR", "TOTAL_VIDEO_P100_COMPLETE", "CAMPAIGN_ENTITY_STATUS", "PAGE_VISIT_ROAS", "TOTAL_REPIN_RATE", "TOTAL_VIDEO_MRC_VIEWS", "TOTAL_IDEA_PIN_PRODUCT_TAG_VISIT", "ECPC_IN_DOLLAR", "WEB_SESSIONS_1", "WEB_SESSIONS_2", "TOTAL_WEB_SESSIONS" ] }, "ObjectiveType": { "type": "string", "description": "Campaign objective type. [\"WEB_SESSIONS\"] in BETA.", "enum": [ "AWARENESS", "CONSIDERATION", "VIDEO_VIEW", "WEB_CONVERSION", "CATALOG_SALES", "WEB_SESSIONS" ] }, "SingleInterestTargetingOptionResponse": { "title": "SingleInterestTargetingOptionData", "type": "object", "properties": { "id": { "type": "string", "title": "id", "pattern": "\\d+", "example": "945391946569" }, "name": { "type": "string", "title": "name", "example": "Dress" }, "child_interests": { "type": "array", "title": "child_interests", "items": { "type": "string" } }, "level": { "type": "integer", "title": "level", "example": 2 } } }, "TargetingOptionResponse": { "title": "TargetingOptionResponse", "type": "array", "nullable": true, "items": { "type": "object", "example": { "36313": "Australia: Moreton Bay - North", "124735": "Canada: North Battleford" } } }, "TargetingTypeFilter": { "type": "object", "properties": { "targeting_types": { "type": "array", "description": "List of targeting types", "items": { "$ref": "#/components/schemas/AdsAnalyticsTargetingType" }, "maxItems": 5, "minItems": 1 } } }, "TermsOfService": { "example": { "has_accepted": true, "html": "example test", "id": "2650449554526", "ad_account_id": "549755885175" }, "properties": { "id": { "description": "The ID of the terms of service", "example": "2650449554526", "title": "id", "type": "string" }, "html": { "description": "The terms of service content", "example": "example test", "nullable": true, "title": "html", "type": "string" }, "has_accepted": { "description": "Whether the ad account has accepted terms of service.", "example": true, "title": "hasAccepted", "type": "boolean" }, "ad_account_id": { "description": "The ID of the ad account.", "example": "549755885175", "title": "adAccountId", "type": "string" } }, "title": "TermsOfService", "type": "object" }, "RelatedTerms": { "type": "object", "properties": { "id": { "description": "First input term. For example, if you pass \"?terms=clothes,workout\", then id will be \"clothes\"", "type": "string", "example": "clothes" }, "related_term_count": { "description": "Total number of related terms returned", "type": "integer", "example": 2 }, "related_terms_list": { "description": "The id of the advertiser.", "type": "array", "items": { "type": "object", "properties": { "term": { "type": "string", "example": "clothes" }, "related_terms": { "type": "array", "items": { "type": "string" }, "example": [ "shoes", "cute clothes" ] } } } } } }, "TopPinsAnalyticsResponse": { "type": "object", "properties": { "date_availability": { "type": "object", "properties": { "latest_available_timestamp": { "type": "number", "example": 1649116799000 }, "is_realtime": { "type": "boolean", "example": false } } }, "pins": { "type": "array", "items": { "description": "Array with metrics, status, and pin id for the requested metric", "type": "object", "properties": { "metrics": { "$ref": "#/components/schemas/Metrics" }, "data_status": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DataStatus" } }, "pin_id": { "description": "The pin id", "type": "string", "example": "642396334344813594" } } } }, "sort_by": { "type": "string", "enum": [ "ENGAGEMENT", "SAVE", "IMPRESSION", "OUTBOUND_CLICK", "PIN_CLICK" ], "example": "IMPRESSION" } } }, "TopVideoPinsAnalyticsResponse": { "type": "object", "properties": { "date_availability": { "type": "object", "properties": { "latest_available_timestamp": { "type": "number", "example": 1649116799000 }, "is_realtime": { "type": "boolean", "example": false } } }, "pins": { "type": "array", "items": { "description": "Array with metrics, status, and pin id for the requested metric", "type": "object", "properties": { "metrics": { "description": "The metric name and daily value for each requested metric", "type": "object", "additionalProperties": { "type": "number" }, "example": { "IMPRESSION": 7, "QUARTILE_95_PERCENT_VIEW": 2, "SAVE": 1, "VIDEO_10S_VIEW": 5, "VIDEO_AVG_WATCH_TIME": 86989, "VIDEO_MRC_VIEW": 2, "VIDEO_START": 2, "VIDEO_V50_WATCH_TIME": 173979, "OUTBOUND_CLICK": 2 } }, "data_status": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/DataStatus" } }, "pin_id": { "description": "The pin id", "type": "string", "example": "642396334344813594" } } } }, "sort_by": { "type": "string", "enum": [ "SAVE", "IMPRESSION", "OUTBOUND_CLICK", "VIDEO_MRC_VIEW", "VIDEO_AVG_WATCH_TIME", "VIDEO_V50_WATCH_TIME", "QUARTILE_95_PERCENT_VIEW", "VIDEO_10S_VIEW", "VIDEO_START" ], "example": "IMPRESSION" } } }, "TrackingUrls": { "description": "Third-party tracking URLs. 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. For more information, see Third-party and dynamic tracking.", "example": { "impression": [ "URL1", "URL2" ], "click": [ "URL1", "URL2" ], "engagement": [ "URL1", "URL2" ], "buyable_button": [ "URL1", "URL2" ], "audience_verification": [ "URL1", "URL2" ] }, "type": "object", "nullable": true, "properties": { "impression": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 3 }, "click": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 3 }, "engagement": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 3 }, "buyable_button": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 3 }, "audience_verification": { "type": "array", "items": { "type": "string", "maxLength": 2000 }, "maxItems": 3 } } }, "TargetingSpec": { "description": "Ad group targeting specification defining the ad group target audience. For example, {\"APPTYPE\":[\"iphone\"], \"GENDER\":[\"male\"], \"LOCALE\":[\"en-US\"], \"LOCATION\":[\"501\"], \"AGE_BUCKET\":[\"25-34\"]}", "type": "object", "properties": { "AGE_BUCKET": { "type": "array", "nullable": true, "description": "Age ranges", "example": [ "35-44", "50-54" ], "items": { "type": "string", "enum": [ "18-24", "21+", "25-34", "35-44", "45-49", "50-54", "55-64", "65+" ] } }, "APPTYPE": { "type": "array", "nullable": true, "description": "Allowed devices", "example": [ "ipad", "iphone" ], "items": { "type": "string", "enum": [ "android_mobile", "android_tablet", "ipad", "iphone", "web", "web_mobile" ] } }, "AUDIENCE_EXCLUDE": { "type": "array", "nullable": true, "description": "Excluded customer list IDs. Used to drive new customer acquisition goals. For example: [\"2542620905475\"]. Audience lists need to have at least 100 people with Pinterest accounts in them.", "items": { "type": "string", "pattern": "^\\d+$", "minItems": 100 } }, "AUDIENCE_INCLUDE'": { "type": "array", "nullable": true, "description": "Targeted customer list IDs. For example: [\"2542620905473\"]. Audience lists need to have at least 100 people with Pinterest accounts in them", "items": { "type": "string", "pattern": "^\\d+$", "minItems": 100 } }, "GENDER": { "type": "array", "nullable": true, "description": "Targeted genders. Values: [\"unknown\",\"male\",\"female\"]", "items": { "type": "string", "enum": [ "unknown", "male", "female" ] } }, "GEO": { "type": "array", "nullable": true, "description": "Location region codes, e.g., \"BE-VOV\" (East Flanders, Belgium) For complete list, click here or postal codes, e.g., \"US-94107\". Use either region codes or postal codes but not both.", "items": { "type": "string" } }, "INTEREST": { "type": "array", "description": "Array of interest object IDs.", "items": { "type": "string" } }, "LOCALE": { "type": "array", "nullable": true, "description": "24 ISO 639-1 two letter language codes.", "items": { "type": "string" } }, "LOCATION": { "type": "array", "nullable": true, "description": "22 ISO Alpha 2 two letter country codes or US Nielsen DMA (Designated Market Area) codes (location region codes) (e.g., [\"US\", \"807\"]). For complete list, click here. Location-Country and Location-Metro codes apply.", "items": { "type": "string" } }, "SHOPPING_RETARGETING": { "type": "array", "nullable": true, "description": "Array of object: lookback_window\t[Integer]: Number of days ago to start lookback timeframe for dynamic retargeting tag_types [Array of integer]: Event types to target for dynamic retargeting exclusion_window [Integer]: Number of days ago to stop lookback timeframe for dynamic retargeting", "items": { "type": "object", "properties": { "lookback_window": { "type": "integer" }, "tag_types": { "type": "array", "items": { "type": "integer" } }, "exclusion_window": { "type": "integer" } } } }, "TARGETING_STRATEGY": { "type": "array", "nullable": true, "description": "", "items": { "enum": [ "CHOOSE_YOUR_OWN", "FIND_NEW_CUSTOMERS", "RECONNECT_WITH_USERS" ] } } } }, "TermsSuggestedResponse": { "items": { "type": "string" }, "type": "array" }, "UserListType": { "description": "User list type", "enum": [ "EMAIL", "IDFA", "MAID", "LR_ID", "DLX_ID", "HASHED_PINNER_ID" ], "example": "EMAIL", "title": "UserListType", "type": "string" }, "UserListOperationType": { "description": "User list operation type (add or remove)", "enum": [ "ADD", "REMOVE" ], "example": "REMOVE", "title": "UserListOperationType", "type": "string" } }, "parameters": { "path_ad_id": { "name": "ad_id", "description": "Unique identifier of an ad.", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, "path_ad_account_id": { "name": "ad_account_id", "description": "Unique identifier of an ad account.", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+$", "maxLength": 19 } }, "path_ad_group_id": { "name": "ad_group_id", "description": "Unique identifier of an ad group.", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, "path_audience_id": { "name": "audience_id", "description": "Unique identifier of an audience", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, "path_customer_list_id": { "name": "customer_list_id", "description": "Unique identifier of a customer list", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, "path_interest_id": { "name": "interest_id", "description": "Unique identifier of an interest.", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, "path_targeting_type": { "name": "targeting_type", "description": "Public targeting type.", "in": "path", "required": true, "style": "simple", "schema": { "title": "PublicTargetingType", "description": "Public ad targeting type with external names", "type": "string", "example": "APPTYPE", "enum": [ "APPTYPE", "GENDER", "LOCALE", "AGE_BUCKET", "LOCATION", "GEO", "INTEREST", "KEYWORD", "AUDIENCE_INCLUDE", "AUDIENCE_EXCLUDE" ] } }, "path_board_id": { "name": "board_id", "description": "Unique identifier of a board.", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, "path_board_section_id": { "name": "section_id", "description": "Unique identifier of a board section.", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, "path_campaign_id": { "name": "campaign_id", "description": "Campaign ID, must be associated with the ad account ID provided in the path.", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, "path_catalogs_feed_id": { "description": "Unique identifier of a feed", "in": "path", "required": true, "name": "feed_id", "schema": { "type": "string", "pattern": "^\\d+$" } }, "path_catalogs_items_batch_id": { "name": "batch_id", "in": "path", "description": "Id of a catalogs items batch to fetch", "example": "595953100599279259-66753b9bb65c46c49bd8503b27fecf9e", "required": true, "schema": { "type": "string" } }, "path_catalogs_processing_result_id": { "description": "Unique identifier of a feed processing result", "name": "processing_result_id", "in": "path", "example": "5224831246441439241", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, "path_catalogs_product_group_id": { "description": "Unique identifier of a product group", "in": "path", "required": true, "name": "product_group_id", "schema": { "type": "string", "pattern": "^\\d+$" } }, "path_media_id": { "name": "media_id", "description": "Media identifier", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, "path_pin_id": { "name": "pin_id", "description": "Unique identifier of a Pin.", "in": "path", "required": true, "schema": { "type": "string" } }, "path_product_group_promotion_id": { "name": "product_group_promotion_id", "description": "Unique identifier of a product group promotion", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^\\d+$" } }, "query_ad_account_id": { "name": "ad_account_id", "description": "Unique identifier of an ad account.", "in": "query", "schema": { "type": "string", "pattern": "^\\d+$" } }, "query_ad_group_id": { "description": "Ad group Id.", "in": "query", "name": "ad_group_id", "example": "123123123", "required": false, "schema": { "type": "string" } }, "query_ad_group_ids": { "description": "List of Ad group Ids to use to filter the results.", "in": "query", "name": "ad_group_ids", "required": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, "query_ad_group_ids_required": { "description": "List of Ad group Ids to use to filter the results.", "in": "query", "name": "ad_group_ids", "required": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, "query_ad_ids": { "description": "List of Ad Ids to use to filter the results.", "in": "query", "name": "ad_ids", "required": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, "query_ad_ids_required": { "description": "List of Ad Ids to use to filter the results.", "in": "query", "name": "ad_ids", "required": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, "query_app_types": { "description": "Apps or devices to get data for, default is all.", "in": "query", "name": "app_types", "required": false, "schema": { "default": "ALL", "enum": [ "ALL", "MOBILE", "TABLET", "WEB" ], "type": "string" } }, "query_audience_ids": { "description": "List of audience ids to use to filter the results.", "in": "query", "name": "audience_ids", "required": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, "query_audience_type": { "description": "The type of audience to filter for.", "in": "query", "name": "audience_type", "required": false, "schema": { "type": "string", "pattern": "^\\d+$" } }, "query_audience_types": { "description": "The types of audience to filter for.", "in": "query", "name": "audience_types", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/AudienceType" }, "minItems": 1, "maxItems": 100 } }, "query_bookmark": { "name": "bookmark", "description": "Cursor used to fetch the next page of items", "in": "query", "required": false, "schema": { "type": "string" } }, "query_campaign_id": { "description": "Campaign Id to use to filter the results.", "in": "query", "name": "campaign_id", "required": false, "schema": { "type": "string", "pattern": "^\\d+$" } }, "query_campaign_ids": { "description": "List of Campaign Ids to use to filter the results.", "in": "query", "name": "campaign_ids", "required": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, "query_campaign_ids_required": { "description": "List of Campaign Ids to use to filter the results.", "in": "query", "name": "campaign_ids", "required": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, "query_client_id": { "name": "client_id", "description": "Client ID.", "in": "query", "required": false, "schema": { "type": "string", "pattern": "^\\d+$", "example": "1094834" }, "style": "form" }, "query_catalogs_feed_id": { "description": "Unique identifier of a feed", "in": "query", "required": true, "name": "feed_id", "schema": { "type": "string", "pattern": "^\\d+$" } }, "query_catalogs_item_numbers": { "name": "item_numbers", "in": "query", "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": [ 1, 5 ], "required": false, "schema": { "type": "array", "items": { "type": "integer" } } }, "query_catalogs_item_validation_issue": { "name": "item_validation_issue", "in": "query", "description": "Filter item validation issues that have a given type of item validation issue.", "example": "TITLE_MISSING", "required": false, "schema": { "$ref": "#/components/schemas/CatalogsItemValidationIssue" } }, "query_catalogs_items_country": { "name": "country", "in": "query", "description": "Country for the Catalogs Items", "example": "US", "required": true, "schema": { "type": "string" } }, "query_catalogs_items": { "name": "item_ids", "in": "query", "description": "Catalogs Item ids", "example": [ "CR123" ], "required": true, "schema": { "type": "array", "items": { "type": "string" } } }, "query_catalogs_items_language": { "name": "language", "in": "query", "description": "Language for the Catalogs Items", "example": "EN", "required": true, "schema": { "type": "string" } }, "query_columns": { "description": "Columns to retrieve, encoded as a comma-separated string. **NOTE**: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile's currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it's microdollars. Otherwise, it's in microunits of the advertiser's currency.
For example, if the advertiser's currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound).
If a column has no value, it may not be returned", "explode": false, "in": "query", "name": "columns", "required": true, "schema": { "items": { "type": "string", "description": "Name of the reporting column", "example": "SPEND_IN_DOLLAR", "enum": [ "ADVERTISER_ID", "PIN_PROMOTION_ID", "AD_ACCOUNT_ID", "AD_GROUP_ENTITY_STATUS", "AD_GROUP_ID", "AD_ID", "CAMPAIGN_DAILY_SPEND_CAP", "CAMPAIGN_ENTITY_STATUS", "CAMPAIGN_ID", "CAMPAIGN_LIFETIME_SPEND_CAP", "CAMPAIGN_NAME", "CHECKOUT_ROAS", "CLICKTHROUGH_1", "CLICKTHROUGH_1_GROSS", "CLICKTHROUGH_2", "CPC_IN_MICRO_DOLLAR", "CPM_IN_DOLLAR", "CPM_IN_MICRO_DOLLAR", "CTR", "CTR_2", "ECPCV_IN_DOLLAR", "ECPCV_P95_IN_DOLLAR", "ECPC_IN_DOLLAR", "ECPC_IN_MICRO_DOLLAR", "ECPE_IN_DOLLAR", "ECPM_IN_MICRO_DOLLAR", "ECPV_IN_DOLLAR", "ECTR", "EENGAGEMENT_RATE", "ENGAGEMENT_1", "ENGAGEMENT_2", "ENGAGEMENT_RATE", "IDEA_PIN_PRODUCT_TAG_VISIT_1", "IDEA_PIN_PRODUCT_TAG_VISIT_2", "IMPRESSION_1", "IMPRESSION_1_GROSS", "IMPRESSION_2", "INAPP_CHECKOUT_COST_PER_ACTION", "OUTBOUND_CLICK_1", "OUTBOUND_CLICK_2", "PAGE_VISIT_COST_PER_ACTION", "PAGE_VISIT_ROAS", "PAID_IMPRESSION", "PIN_ID", "REPIN_1", "REPIN_2", "REPIN_RATE", "SPEND_IN_DOLLAR", "SPEND_IN_MICRO_DOLLAR", "TOTAL_CHECKOUT", "TOTAL_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_CLICKTHROUGH", "TOTAL_CLICK_ADD_TO_CART", "TOTAL_CLICK_CHECKOUT", "TOTAL_CLICK_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_CLICK_LEAD", "TOTAL_CLICK_SIGNUP", "TOTAL_CLICK_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_CONVERSIONS", "TOTAL_CUSTOM", "TOTAL_ENGAGEMENT", "TOTAL_ENGAGEMENT_CHECKOUT", "TOTAL_ENGAGEMENT_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_ENGAGEMENT_LEAD", "TOTAL_ENGAGEMENT_SIGNUP", "TOTAL_ENGAGEMENT_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_IDEA_PIN_PRODUCT_TAG_VISIT", "TOTAL_IMPRESSION_FREQUENCY", "TOTAL_IMPRESSION_USER", "TOTAL_LEAD", "TOTAL_OFFLINE_CHECKOUT", "TOTAL_PAGE_VISIT", "TOTAL_REPIN_RATE", "TOTAL_SIGNUP", "TOTAL_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_VIDEO_3SEC_VIEWS", "TOTAL_VIDEO_AVG_WATCHTIME_IN_SECOND", "TOTAL_VIDEO_MRC_VIEWS", "TOTAL_VIDEO_P0_COMBINED", "TOTAL_VIDEO_P100_COMPLETE", "TOTAL_VIDEO_P25_COMBINED", "TOTAL_VIDEO_P50_COMBINED", "TOTAL_VIDEO_P75_COMBINED", "TOTAL_VIDEO_P95_COMBINED", "TOTAL_VIEW_ADD_TO_CART", "TOTAL_VIEW_CHECKOUT", "TOTAL_VIEW_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_VIEW_LEAD", "TOTAL_VIEW_SIGNUP", "TOTAL_VIEW_SIGNUP_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_CHECKOUT", "TOTAL_WEB_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_CLICK_CHECKOUT", "TOTAL_WEB_CLICK_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_ENGAGEMENT_CHECKOUT", "TOTAL_WEB_ENGAGEMENT_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "TOTAL_WEB_SESSIONS", "TOTAL_WEB_VIEW_CHECKOUT", "TOTAL_WEB_VIEW_CHECKOUT_VALUE_IN_MICRO_DOLLAR", "VIDEO_3SEC_VIEWS_2", "VIDEO_LENGTH", "VIDEO_MRC_VIEWS_2", "VIDEO_P0_COMBINED_2", "VIDEO_P100_COMPLETE_2", "VIDEO_P25_COMBINED_2", "VIDEO_P50_COMBINED_2", "VIDEO_P75_COMBINED_2", "VIDEO_P95_COMBINED_2", "WEB_CHECKOUT_COST_PER_ACTION", "WEB_CHECKOUT_ROAS", "WEB_SESSIONS_1", "WEB_SESSIONS_2" ] }, "type": "array" } }, "query_conversion_attribution_click_window_days": { "name": "click_window_days", "in": "query", "schema": { "type": "integer", "enum": [ 1, 7, 30, 60 ], "default": 30 }, "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.", "example": 1 }, "query_conversion_attribution_engagement_window_days": { "name": "engagement_window_days", "in": "query", "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.", "schema": { "type": "integer", "enum": [ 1, 7, 30, 60 ], "default": 30 } }, "query_conversion_attribution_view_window_days": { "name": "view_window_days", "in": "query", "description": "Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `1` day.", "schema": { "type": "integer", "enum": [ 1, 7, 30, 60 ], "default": 1 } }, "query_country_code": { "name": "country_code", "description": "Two letter country code (ISO 3166-1 alpha-2)", "in": "query", "example": "US", "required": true, "explode": true, "schema": { "type": "string" }, "style": "form" }, "query_conversion_attribution_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.", "example": "TIME_OF_AD_ACTION", "in": "query", "name": "conversion_report_time", "schema": { "type": "string", "enum": [ "TIME_OF_AD_ACTION", "TIME_OF_CONVERSION" ], "default": "TIME_OF_AD_ACTION" } }, "query_end_date": { "description": "Metric report end date (UTC). Format: YYYY-MM-DD", "in": "query", "name": "end_date", "required": true, "schema": { "type": "string", "format": "date" } }, "query_entity_statuses": { "in": "query", "name": "entity_statuses", "required": false, "description": "Entity status", "schema": { "type": "array", "items": { "type": "string", "example": "ACTIVE", "enum": [ "ACTIVE", "PAUSED", "ARCHIVED" ] } } }, "query_flatten_rule": { "description": "Uniform the format of Audiences rules for presentation on Web UI.", "in": "query", "name": "flatten_rule", "required": false, "schema": { "type": "boolean" } }, "query_from_claimed_content": { "description": "Filter on Pins that match your claimed domain.", "in": "query", "name": "from_claimed_content", "required": false, "schema": { "default": "BOTH", "enum": [ "OTHER", "CLAIMED", "BOTH" ], "type": "string" } }, "query_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", "example": "DAY", "in": "query", "name": "granularity", "required": true, "schema": { "$ref": "#/components/schemas/Granularity" } }, "query_oauth_signature": { "name": "oauth_signature", "description": "Oauth signature", "in": "query", "required": false, "schema": { "type": "string", "example": "8209f" }, "style": "form" }, "query_list_input_terms": { "description": "List of input terms.", "in": "query", "name": "terms", "required": true, "schema": { "type": "array", "items": { "type": "string", "example": "workout" } } }, "query_match_types": { "explode": true, "description": "Keyword match type", "in": "query", "name": "match_types", "required": false, "schema": { "type": "array", "items": { "$ref": "#/components/schemas/MatchType" }, "minItems": 1, "maxItems": 5 } }, "query_metric_types": { "description": "Metric types to get data for, default is all. ", "explode": false, "in": "query", "name": "metric_types", "required": false, "schema": { "items": { "enum": [ "ENGAGEMENT", "ENGAGEMENT_RATE", "IMPRESSION", "OUTBOUND_CLICK", "OUTBOUND_CLICK_RATE", "PIN_CLICK", "PIN_CLICK_RATE", "SAVE", "SAVE_RATE" ], "type": "string" }, "type": "array" }, "style": "form" }, "query_search_query": { "description": "String keywords to search for audiences by.", "in": "query", "name": "search_query", "required": false, "schema": { "type": "string" } }, "query_start_index": { "description": "he starting index for returned list.", "in": "query", "name": "start_index", "required": false, "schema": { "type": "string", "pattern": "^\\d+$" } }, "query_video_pin_metric_types": { "description": "Metric types to get video data for, default is all. ", "explode": false, "in": "query", "name": "metric_types", "required": false, "schema": { "items": { "enum": [ "IMPRESSION", "SAVE", "VIDEO_MRC_VIEW", "VIDEO_AVG_WATCH_TIME", "VIDEO_V50_WATCH_TIME", "QUARTILE_95_PERCENT_VIEW", "VIDEO_10S_VIEW", "VIDEO_START", "OUTBOUND_CLICK" ], "type": "string" }, "type": "array" }, "style": "form" }, "query_pin_analytics_metric_types": { "description": "Pin metric types to get data for, default is all.", "explode": false, "in": "query", "name": "metric_types", "required": true, "schema": { "items": { "enum": [ "IMPRESSION", "SAVE", "PIN_CLICK", "OUTBOUND_CLICK", "VIDEO_MRC_VIEW", "VIDEO_AVG_WATCH_TIME", "VIDEO_V50_WATCH_TIME", "QUARTILE_95_PERCENT_VIEW" ], "type": "string" }, "type": "array" }, "style": "form" }, "query_order_by": { "description": "The audience field to order results by.", "in": "query", "name": "order_by", "required": false, "schema": { "$ref": "#/components/schemas/GetAudiencesOrderBy" } }, "query_split_field_user_account": { "description": "How to split the data into groups. Not including this param means data won't be split.", "required": false, "in": "query", "explode": false, "name": "split_field", "schema": { "default": "NO_SPLIT", "enum": [ "NO_SPLIT", "APP_TYPE", "OWNED_CONTENT", "PIN_FORMAT" ], "type": "string" } }, "query_split_field_pins": { "description": "How to split the data into groups. Not including this param means data won't be split.", "required": false, "in": "query", "explode": false, "name": "split_field", "schema": { "default": "NO_SPLIT", "enum": [ "NO_SPLIT", "APP_TYPE" ], "type": "string" } }, "query_num_of_pins": { "name": "num_of_pins", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }, "description": "Number of pins to include, default is 10. Max is 50.", "example": 25 }, "query_created_in_last_n_days": { "name": "created_in_last_n_days", "in": "query", "schema": { "type": "integer", "enum": [ 30 ] }, "description": "Get metrics for pins created in the last \"n\" days.", "example": 30 }, "query_sort_by": { "description": "Specify sorting order for metrics", "explode": false, "in": "query", "name": "sort_by", "required": true, "schema": { "enum": [ "ENGAGEMENT", "IMPRESSION", "OUTBOUND_CLICK", "PIN_CLICK", "SAVE" ], "type": "string" } }, "query_video_pin_sort_by": { "description": "Specify sorting order for video metrics", "explode": false, "in": "query", "name": "sort_by", "required": true, "schema": { "enum": [ "IMPRESSION", "SAVE", "OUTBOUND_CLICK", "VIDEO_MRC_VIEW", "VIDEO_AVG_WATCH_TIME", "VIDEO_V50_WATCH_TIME", "QUARTILE_95_PERCENT_VIEW", "VIDEO_10S_VIEW", "VIDEO_START" ], "type": "string" } }, "query_order": { "description": "The order in which to sort the items returned: “ASCENDING” or “DESCENDING”\nby ID. Note that higher-value IDs are associated with more-recently added\nitems.", "in": "query", "name": "order", "required": false, "schema": { "type": "string", "example": "ASCENDING", "enum": [ "ASCENDING", "DESCENDING" ] } }, "query_include_html": { "description": "Return HTML in TOS text.", "explode": true, "in": "query", "name": "include_html", "required": false, "schema": { "default": false, "type": "boolean" }, "style": "form" }, "query_tos_type": { "description": "Request type.", "explode": true, "in": "query", "name": "tos_type", "required": false, "schema": { "type": "string" }, "style": "form" }, "query_page_size": { "name": "page_size", "description": "Maximum number of items to include in a single page of the response. See documentation on Pagination for more information.", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, "query_pin_format": { "description": "Pin formats to get data for, default is all.", "in": "query", "name": "pin_format", "required": false, "schema": { "default": "ALL", "enum": [ "ALL", "PRODUCT", "REGULAR", "VIDEO" ], "type": "string" } }, "query_product_group_ids_required": { "description": "List of Product group Ids to use to filter the results.", "in": "query", "name": "product_group_ids", "required": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, "query_start_date": { "description": "Metric report start date (UTC). Format: YYYY-MM-DD", "in": "query", "name": "start_date", "required": true, "schema": { "type": "string", "format": "date" } }, "query_token_required": { "name": "token", "description": "Token returned from the post request creation call", "in": "query", "required": true, "schema": { "type": "string" } }, "query_include_shared_accounts": { "in": "query", "description": "Include shared ad accounts", "name": "include_shared_accounts", "required": false, "schema": { "type": "boolean", "default": true } }, "query_timestamp": { "name": "timestamp", "description": "Timestamp", "in": "query", "required": false, "schema": { "type": "string", "example": "1618338184277", "pattern": "\\d+" }, "style": "form" }, "query_translate_interests_to_names": { "description": "Return interests as text names (if value is true) rather than topic IDs.", "in": "query", "name": "translate_interests_to_names", "required": false, "schema": { "type": "boolean", "default": false } }, "query_input_term": { "description": "Input term.", "in": "query", "name": "term", "example": "sports", "required": true, "schema": { "type": "string" } }, "query_product_group_promotion_ids": { "description": "List of Product group promotion Ids.", "in": "query", "name": "product_group_promotion_ids", "required": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^\\d+$" }, "minItems": 1, "maxItems": 100 } }, "query_term_limit": { "description": "Max suggested terms to return.", "in": "query", "name": "limit", "example": 4, "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 10, "default": 4 } } } } }