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",
"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",
"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"
}
}
}
}
}
},
"patch": {
"summary": "Update Pin",
"description": "Update a pin owned by the \"operating user_account\".\n\nThis endpoint is currently in beta and not available to all apps. Learn more.",
"tags": [
"pins"
],
"operationId": "pins/update",
"security": [
{
"pinterest_oauth2": [
"boards:read",
"boards:write",
"pins:read",
"pins:write"
]
}
],
"x-ratelimit-category": "org_write",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_pin_id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PinUpdate"
}
}
}
},
"responses": {
"200": {
"description": "response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Pin"
}
}
}
},
"403": {
"description": "Not authorized to update Pin.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 29,
"message": "Not authorized to update Pin."
}
}
}
},
"404": {
"description": "Pin not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 50,
"message": "Pin not found."
}
}
}
},
"429": {
"description": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits or if multiple write operations are applied to\nan object within a short time window.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 8,
"message": "This request exceeded a rate limit. This can happen if the client exceeds one\nof the published rate limits or if multiple write operations are applied to\nan object within a short time window."
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/pins/{pin_id}/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.\n- Any Pin type can be saved: image Pin, video Pin, Idea Pin, product Pin, etc.\n- Any public Pin can be saved given a pin ID.",
"tags": [
"pins"
],
"operationId": "pins/save",
"security": [
{
"pinterest_oauth2": [
"boards:read",
"boards:write",
"pins:read",
"pins:write"
]
}
],
"x-ratelimit-category": "org_write",
"x-sandbox": "enabled",
"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": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_pin_id"
},
{
"$ref": "#/components/parameters/query_start_date"
},
{
"$ref": "#/components/parameters/query_end_date"
},
{
"$ref": "#/components/parameters/query_app_types"
},
{
"$ref": "#/components/parameters/query_pin_analytics_metric_types"
},
{
"$ref": "#/components/parameters/query_split_field_pins"
},
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"responses": {
"200": {
"description": "response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/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",
"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",
"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",
"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",
"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",
"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",
"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",
"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",
"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",
"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",
"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",
"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",
"parameters": [
{
"$ref": "#/components/parameters/query_bookmark"
},
{
"$ref": "#/components/parameters/query_page_size"
}
],
"responses": {
"200": {
"description": "response",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Paginated"
},
{
"properties": {
"items": {
"description": "Media",
"items": {
"$ref": "#/components/schemas/MediaUploadDetails"
}
}
}
}
]
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"summary": "Register media upload",
"description": "Register your intent to upload media\n\nThe response includes all of the information needed to upload the media\nto Pinterest.\n\nTo upload the media, make an HTTP POST request (using curl, for\nexample) to upload_url using the Content-Type header\nvalue. Send the media file's contents as the request's file\nparameter and also include all of the parameters from\nupload_parameters.\n\nLearn more about video Pin creation.",
"tags": [
"media"
],
"operationId": "media/create",
"security": [
{
"pinterest_oauth2": [
"pins:read",
"pins:write"
]
}
],
"x-ratelimit-category": "org_write",
"x-sandbox": "enabled",
"requestBody": {
"description": "Create a media upload request",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MediaUploadRequest"
}
}
}
},
"responses": {
"201": {
"description": "response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MediaUpload"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/media/{media_id}": {
"get": {
"summary": "Get media upload details",
"description": "Get details for a registered media upload, including its current status.\n\nLearn more about video Pin creation.",
"tags": [
"media"
],
"operationId": "media/get",
"security": [
{
"pinterest_oauth2": [
"pins:read"
]
}
],
"x-ratelimit-category": "org_read",
"x-sandbox": "enabled",
"parameters": [
{
"$ref": "#/components/parameters/path_media_id"
}
],
"responses": {
"200": {
"description": "response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MediaUploadDetails"
}
}
}
},
"404": {
"description": "Media upload not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 404,
"message": "Media upload not found"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/ad_accounts": {
"get": {
"summary": "List ad accounts",
"description": "Get a list of the ad_accounts that the \"operation user_account\" has access to.\n- This includes ad_accounts they own and ad_accounts that are owned by others who have granted them Business Access.",
"tags": [
"ad_accounts"
],
"operationId": "ad_accounts/list",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "enabled",
"parameters": [
{
"$ref": "#/components/parameters/query_bookmark"
},
{
"$ref": "#/components/parameters/query_page_size"
},
{
"$ref": "#/components/parameters/query_include_shared_accounts"
}
],
"responses": {
"200": {
"description": "response",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Paginated"
},
{
"properties": {
"items": {
"description": "Ad accounts",
"items": {
"$ref": "#/components/schemas/AdAccount"
}
}
}
}
]
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
},
"post": {
"summary": "Create ad account",
"description": "Create a new ad account. Different ad accounts can support different currencies, payment methods, etc.\nAn ad account is needed to create campaigns, ad groups, and ads; other accounts (your employees or partners) can be assigned business access and appropriate roles to access an ad account. \nYou can set up up to 50 ad accounts per user. (The user must have a business account to create an ad account.) \nFor more, see Create an advertiser account.",
"tags": [
"ad_accounts"
],
"operationId": "ad_accounts/create",
"security": [
{
"pinterest_oauth2": [
"ads:write"
]
}
],
"x-ratelimit-category": "ads_write",
"x-sandbox": "enabled",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdAccountCreateRequest"
}
}
},
"description": "Ad account to create.",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdAccount"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
}
}
},
"/ad_accounts/{ad_account_id}": {
"get": {
"summary": "Get ad account",
"description": "Get an ad account",
"operationId": "ad_accounts/get",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "enabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdAccount"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"tags": [
"ad_accounts"
]
}
},
"/ad_accounts/{ad_account_id}/analytics": {
"get": {
"summary": "Get ad account analytics",
"description": "Get analytics for the specified ad_account_id, filtered by the specified options.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.\n- If granularity is not HOUR, the furthest back you can are allowed to pull data is 914 days before the current date in UTC time.\n- If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time.",
"operationId": "ad_account/analytics",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_analytics",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_start_date"
},
{
"$ref": "#/components/parameters/query_end_date"
},
{
"$ref": "#/components/parameters/query_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}/ads/targeting_analytics": {
"get": {
"summary": "Get targeting analytics for ads",
"description": "Get targeting analytics for one or more ads. For the requested ad(s) and metrics,\nthe response will include the requested metric information (e.g. SPEND_IN_DOLLAR) for the requested target type\n(e.g. \"age_bucket\") for applicable values (e.g. \"45-49\"). \n- The token's user_account must either be the Owner of the specified ad account, or have one\nof the necessary roles granted to them via\nBusiness Access: Admin, Analyst, Campaign Manager.\n- If granularity is not HOUR, the furthest back you can are allowed to pull data is 914 days before the current date in UTC time and the max time range supported is 186 days.\n- If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.",
"operationId": "ad_targeting_analytics/get",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_analytics",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_ad_ids_required"
},
{
"$ref": "#/components/parameters/query_start_date"
},
{
"$ref": "#/components/parameters/query_end_date"
},
{
"$ref": "#/components/parameters/query_targeting_types"
},
{
"$ref": "#/components/parameters/query_columns"
},
{
"$ref": "#/components/parameters/query_granularity"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_click_window_days"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_engagement_window_days"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_view_window_days"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_conversion_report_time"
},
{
"$ref": "#/components/parameters/query_attribution_types"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetricsResponse"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"tags": [
"ads"
]
}
},
"/ad_accounts/{ad_account_id}/campaigns": {
"get": {
"summary": "List campaigns",
"description": "Get a list of the campaigns in the specified ad_account_id, filtered by the specified options.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.",
"operationId": "campaigns/list",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "enabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_campaign_ids"
},
{
"$ref": "#/components/parameters/query_entity_statuses"
},
{
"$ref": "#/components/parameters/query_page_size"
},
{
"$ref": "#/components/parameters/query_order"
},
{
"$ref": "#/components/parameters/query_bookmark"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Paginated"
},
{
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CampaignResponse"
}
}
}
}
]
}
}
},
"description": "Success"
},
"400": {
"description": "Invalid ad account campaign parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 400,
"message": "Invalid ad account campaign parameters."
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"campaigns"
]
},
"post": {
"summary": "Create campaigns",
"description": "Create multiple new campaigns. Every campaign has its own campaign_id and houses one or more ad groups, which contain one or more ads.\nFor more, see Set up your campaign. \nNote:\n- The values for 'lifetime_spend_cap' and 'daily_spend_cap' are microcurrency amounts based on the currency field set in the advertiser's profile. (e.g. USD) \nMicrocurrency is used to track very small transactions, based on the currency set in the advertiser’s profile.
\nA microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser’s profile.
\nEquivalency equations, using dollars as an example currency:
\nTo convert between currency and microcurrency, using dollars as an example currency:
\nThe 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)
\nMicrocurrency is used to track very small transactions, based on the currency set in the advertiser’s profile.
\nA microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser’s profile.
\nEquivalency equations, using dollars as an example currency:
\nTo convert between currency and microcurrency, using dollars as an example currency:
\nad_account_id, filtered by the specified options.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.\n- If granularity is not HOUR, the furthest back you can are allowed to pull data is 914 days before the current date in UTC time and the max time range supported is 186 days.\n- If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.",
"operationId": "campaigns/analytics",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_analytics",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_start_date"
},
{
"$ref": "#/components/parameters/query_end_date"
},
{
"$ref": "#/components/parameters/query_campaign_ids_required"
},
{
"$ref": "#/components/parameters/query_columns"
},
{
"$ref": "#/components/parameters/query_granularity"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_click_window_days"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_engagement_window_days"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_view_window_days"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_conversion_report_time"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CampaignsAnalyticsResponse"
}
}
},
"description": "Success"
},
"400": {
"description": "Invalid ad account campaign analytics parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 400,
"message": "Invalid ad account campaign analytics parameters."
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"campaigns"
]
}
},
"/ad_accounts/{ad_account_id}/campaigns/targeting_analytics": {
"get": {
"summary": "Get targeting analytics for campaigns",
"description": "Get targeting analytics for one or more campaigns.\nFor the requested account and metrics, the response will include the requested metric information\n(e.g. SPEND_IN_DOLLAR) for the requested target type (e.g. \"age_bucket\") for applicable values (e.g. \"45-49\"). \n- The token's user_account must either be the Owner of the specified ad account, or have one\nof the necessary roles granted to them via\nBusiness Access: Admin, Analyst, Campaign Manager.\n- If granularity is not HOUR, the furthest back you can are allowed to pull data is 914 days before the current date in UTC time and the max time range supported is 186 days.\n- If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.",
"operationId": "campaign_targeting_analytics/get",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_analytics",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_campaign_ids_required"
},
{
"$ref": "#/components/parameters/query_start_date"
},
{
"$ref": "#/components/parameters/query_end_date"
},
{
"$ref": "#/components/parameters/query_targeting_types"
},
{
"$ref": "#/components/parameters/query_columns"
},
{
"$ref": "#/components/parameters/query_granularity"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_click_window_days"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_engagement_window_days"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_view_window_days"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_conversion_report_time"
},
{
"$ref": "#/components/parameters/query_attribution_types"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetricsResponse"
}
}
},
"description": "Success"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"campaigns"
]
}
},
"/ad_accounts/{ad_account_id}/ad_groups/targeting_analytics": {
"get": {
"summary": "Get targeting analytics for ad groups",
"description": "Get targeting analytics for one or more ad groups.\nFor the requested ad group(s) and metrics, the response will include the requested metric information\n(e.g. SPEND_IN_DOLLAR) for the requested target type (e.g. \"age_bucket\") for applicable values (e.g. \"45-49\"). \n- The token's user_account must either be the Owner of the specified ad account, or have one\nof the necessary roles granted to them via\nBusiness Access: Admin, Analyst, Campaign Manager.\n- If granularity is not HOUR, the furthest back you can are allowed to pull data is 914 days before the current date in UTC time and the max time range supported is 186 days.\n- If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.",
"operationId": "ad_groups_targeting_analytics/get",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_analytics",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_ad_group_ids_required"
},
{
"$ref": "#/components/parameters/query_start_date"
},
{
"$ref": "#/components/parameters/query_end_date"
},
{
"$ref": "#/components/parameters/query_targeting_types"
},
{
"$ref": "#/components/parameters/query_columns"
},
{
"$ref": "#/components/parameters/query_granularity"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_click_window_days"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_engagement_window_days"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_view_window_days"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_conversion_report_time"
},
{
"$ref": "#/components/parameters/query_attribution_types"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MetricsResponse"
}
}
},
"description": "Success"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"ad_groups"
]
}
},
"/ad_accounts/{ad_account_id}/ad_groups": {
"get": {
"summary": "List ad groups",
"description": "List ad groups based on provided campaign IDs or ad group IDs.(campaign_ids or ad_group_ids). \nNote:\nProvide only campaign_id or ad_group_id. Do not provide both.",
"operationId": "ad_groups/list",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "enabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_campaign_ids"
},
{
"$ref": "#/components/parameters/query_ad_group_ids"
},
{
"$ref": "#/components/parameters/query_entity_statuses"
},
{
"$ref": "#/components/parameters/query_page_size"
},
{
"$ref": "#/components/parameters/query_order"
},
{
"$ref": "#/components/parameters/query_bookmark"
},
{
"$ref": "#/components/parameters/query_translate_interests_to_names"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Paginated"
},
{
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AdGroupResponse"
}
}
}
}
]
}
}
},
"description": "Success"
},
"400": {
"description": "Invalid ad account group parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 400,
"message": "Invalid ad account group parameters."
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"ad_groups"
]
},
"post": {
"summary": "Create ad groups",
"description": "Create multiple new ad groups. All ads in a given ad group will have the same budget, bid, run dates, targeting, and placement (search, browse, other). For more information, click here.\nNote:\n- 'bid_in_micro_currency' and 'budget_in_micro_currency' should be expressed in microcurrency amounts based on the currency field set in the advertiser's profile.\nMicrocurrency is used to track very small transactions, based on the currency set in the advertiser’s profile.
\nA microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser’s profile.
\nEquivalency equations, using dollars as an example currency:
\nTo convert between currency and microcurrency, using dollars as an example currency:
\nad_account_id, filtered by the specified options.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.\n- If granularity is not HOUR, the furthest back you can are allowed to pull data is 914 days before the current date in UTC time and the max time range supported is 186 days.\n- If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.",
"operationId": "ad_groups/analytics",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_analytics",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_start_date"
},
{
"$ref": "#/components/parameters/query_end_date"
},
{
"$ref": "#/components/parameters/query_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",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_campaign_ids"
},
{
"$ref": "#/components/parameters/query_ad_group_ids"
},
{
"$ref": "#/components/parameters/query_ad_ids"
},
{
"$ref": "#/components/parameters/query_entity_statuses"
},
{
"$ref": "#/components/parameters/query_page_size"
},
{
"$ref": "#/components/parameters/query_order"
},
{
"$ref": "#/components/parameters/query_bookmark"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Paginated"
},
{
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/AdResponse"
}
}
}
}
]
}
}
},
"description": "Success"
},
"400": {
"description": "Invalid ad account ads parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 400,
"message": "Invalid ad account ads parameters."
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"ads"
]
},
"post": {
"description": "Create multiple new ads. Request must contain ad_group_id, creative_type, and the source Pin pin_id.",
"operationId": "ads/create",
"security": [
{
"pinterest_oauth2": [
"ads:write"
]
}
],
"x-ratelimit-category": "ads_write",
"x-sandbox": "enabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/AdCreateRequest"
},
"maxItems": 30,
"minItems": 1,
"type": "array"
}
}
},
"description": "List of ads to create, size limit [1, 30].",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdArrayResponse"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"summary": "Create ads",
"tags": [
"ads"
]
},
"patch": {
"description": "Update multiple existing ads",
"operationId": "ads/update",
"security": [
{
"pinterest_oauth2": [
"ads:write"
]
}
],
"x-ratelimit-category": "ads_write",
"x-sandbox": "enabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"items": {
"$ref": "#/components/schemas/AdUpdateRequest"
},
"maxItems": 30,
"minItems": 1,
"type": "array"
}
}
},
"description": "List of ads to update, size limit [1, 30]",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdArrayResponse"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"summary": "Update ads",
"tags": [
"ads"
]
}
},
"/ad_accounts/{ad_account_id}/ads/{ad_id}": {
"get": {
"summary": "Get ad",
"description": "Get a specific ad given the ad ID. If your pin is rejected, rejected_reasons will\ncontain additional information from the Ad Review process.\nFor more information about our policies and rejection reasons see the Pinterest advertising standards.",
"operationId": "ads/get",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "enabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/path_ad_id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdResponse"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"tags": [
"ads"
]
}
},
"/ad_accounts/{ad_account_id}/ads/analytics": {
"get": {
"summary": "Get ad analytics",
"description": "Get analytics for the specified ads in the specified ad_account_id, filtered by the specified options.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.\n- If granularity is not HOUR, the furthest back you can are allowed to pull data is 914 days before the current date in UTC time and the max time range supported is 186 days.\n- If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.",
"operationId": "ads/analytics",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_analytics",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_start_date"
},
{
"$ref": "#/components/parameters/query_end_date"
},
{
"$ref": "#/components/parameters/query_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",
"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. \nMicrocurrency is used to track very small transactions, based on the currency set in the advertiser’s profile.
\nA microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser’s profile.
\nEquivalency equations, using dollars as an example currency:
\nTo convert between currency and microcurrency, using dollars as an example currency:
\nad_account_id. The request body should be a JSON object.\n- This endpoint requires an access_token be generated through Ads Manager. Review the Conversions Guide for more details.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Audience, Campaign.\n- If the merchant is submitting this information using both Pinterest conversion tags and the Pinterest API, Pinterest will remove duplicate information before reporting. (Note that events that took place offline cannot be deduplicated.)",
"operationId": "events/create",
"tags": [
"conversion_events"
],
"security": [
{
"conversion_token": []
}
],
"x-ratelimit-category": "ads_conversions",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"name": "test",
"description": "Include query param ?test=true to mark the request as a test request. The events will not be recorded but the API will still return the same response messages. Use this mode to verify your requests are working and your events are constructed correctly.\nWarning: If you use this query parameter, be certain that it is off (set to false or deleted) before sending a legitimate (non-testing) request.",
"in": "query",
"required": false,
"schema": {
"type": "boolean"
}
}
],
"requestBody": {
"description": "Conversion events.",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversionEvents"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversionApiResponse"
}
}
},
"description": "Success"
},
"400": {
"description": "The request was invalid.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 4196,
"message": "The request was invalid."
}
}
}
},
"503": {
"description": "The endpoint has been ramped down and is currently not accepting any traffic.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 4197,
"message": "The endpoint has been ramped down and is currently not accepting any traffic."
}
}
}
},
"default": {
"description": "Unexpected errors",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/ad_accounts/{ad_account_id}/product_groups/analytics": {
"get": {
"summary": "Get product group analytics",
"description": "Get analytics for the specified product groups in the specified ad_account_id, filtered by the specified options.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.\n- If granularity is not HOUR, the furthest back you can are allowed to pull data is 914 days before the current date in UTC time and the max time range supported is 186 days.\n- If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.",
"operationId": "product_groups/analytics",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_analytics",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_start_date"
},
{
"$ref": "#/components/parameters/query_end_date"
},
{
"$ref": "#/components/parameters/query_product_group_ids_required"
},
{
"$ref": "#/components/parameters/query_columns"
},
{
"$ref": "#/components/parameters/query_granularity"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_click_window_days"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_engagement_window_days"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_view_window_days"
},
{
"$ref": "#/components/parameters/query_conversion_attribution_conversion_report_time"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProductGroupAnalyticsResponse"
}
}
},
"description": "Success"
},
"400": {
"description": "Invalid ad account ads analytics parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 400,
"message": "Invalid ad account ads analytics parameters."
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"product_group_promotions"
]
}
},
"/ad_accounts/{ad_account_id}/product_groups/catalogs": {
"get": {
"description": "Get a list of catalog product groups used by the feed profile ID.",
"operationId": "ad_accounts_catalogs_product_groups/list",
"security": [
{
"pinterest_oauth2": [
"ads:write"
]
}
],
"x-ratelimit-category": "ads_write",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_feed_profile_id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Paginated"
},
{
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CatalogProductGroup"
}
}
}
}
]
}
}
},
"description": "Success"
},
"400": {
"description": "Invalid ad account ads parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 400,
"message": "Invalid ad account ads parameters."
}
}
}
},
"401": {
"description": "Access Denied. This can happen if account is not yet approved to operate as Merchant on Pinterest.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Merchant data not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"summary": "Get catalog product groups",
"tags": [
"product_groups"
]
}
},
"/ad_accounts/{ad_account_id}/reports": {
"get": {
"summary": "Get the account analytics report created by the async call",
"description": "This returns a URL to an analytics report given a token returned from the post request report creation call. You can use the URL to download the report 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": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_token_required"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdsAnalyticsGetAsyncResponse"
}
}
},
"description": "Success"
},
"400": {
"description": "Invalid ad account ads analytics parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 400,
"message": "Invalid ad account ads analytics parameters."
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"ad_accounts"
]
},
"post": {
"summary": "Create async request for an account analytics report",
"description": "This returns a token that you can use to download the report when it is ready. Note that this endpoint requires the parameters to be passed as JSON-formatted in the request body. This endpoint does not support URL query parameters.\n- The token's user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager.\n- If granularity is not HOUR, the furthest back you can are allowed to pull data is 914 days before the current date in UTC time and the max time range supported is 186 days.\n- If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.\n- If level is PRODUCT_ITEM, the furthest back you can are allowed to pull data is 92 days before the current date in UTC time and the max time range supported is 31 days.",
"operationId": "analytics/create_report",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_analytics",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdsAnalyticsCreateAsyncRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdsAnalyticsCreateAsyncResponse"
}
}
},
"description": "Success"
},
"400": {
"description": "Invalid ad account ads analytics parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 400,
"message": "Invalid ad account ads analytics parameters."
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"ad_accounts"
]
}
},
"/ad_accounts/{ad_account_id}/audiences": {
"get": {
"summary": "List audiences",
"description": "Get list of audiences for the ad account.",
"operationId": "audiences/list",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_bookmark"
},
{
"$ref": "#/components/parameters/query_order"
},
{
"$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/Audience"
}
}
}
}
]
}
}
},
"description": "Success"
},
"400": {
"description": "Invalid ad account audience parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 400,
"message": "Invalid ad account audience parameters."
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"audiences"
]
},
"post": {
"description": "Create an audience you can use in targeting for specific ad groups. Targeting combines customer information with\nthe ways users interact with Pinterest to help you reach specific groups of users; you can include or exclude\nspecific audience_ids when you create an ad group. \nFor more, see Audience targeting.",
"operationId": "audiences/create",
"security": [
{
"pinterest_oauth2": [
"ads:write"
]
}
],
"x-ratelimit-category": "ads_write",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AudienceCreateRequest"
}
}
},
"description": "List of ads to create, size limit [1, 30]",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Audience"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"summary": "Create audience",
"tags": [
"audiences"
]
}
},
"/ad_accounts/{ad_account_id}/audiences/{audience_id}": {
"get": {
"summary": "Get audience",
"description": "Get a specific audience given the audience ID.",
"operationId": "audiences/get",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/path_audience_id"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Audience"
}
}
}
},
"404": {
"description": "Audience not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"default": {
"description": "Unexpected error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"audiences"
]
},
"patch": {
"summary": "Update audience",
"description": "Update (edit or remove) an existing targeting audience.",
"operationId": "audiences/update",
"security": [
{
"pinterest_oauth2": [
"ads:write"
]
}
],
"x-ratelimit-category": "ads_write",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/path_audience_id"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AudienceUpdateRequest"
}
}
},
"description": "The audience to be updated."
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Audience"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"tags": [
"audiences"
]
}
},
"/ad_accounts/{ad_account_id}/audiences/custom": {
"post": {
"summary": "Create custom audience",
"description": "Create a custom audience and find the audiences you want your ads to reach.",
"operationId": "audiences/create_custom",
"security": [
{
"pinterest_oauth2": [
"ads:write"
]
}
],
"x-ratelimit-category": "ads_write",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
}
],
"requestBody": {
"description": "Custom audience to create.",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AudienceCreateCustomRequest"
}
}
}
},
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Audience"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"audiences"
]
}
},
"/ad_accounts/{ad_account_id}/audience_insights": {
"get": {
"summary": "Get audience insights",
"description": "Get Audience Insights for an ad account. The response will return insights for 3 types of audiences: the\nad account's engaged audience on Pinterest, the ad account's total audience on Pinterest and Pinterest's\ntotal audience.\nLearn more about Audience Insights.",
"operationId": "audience_insights/get",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_audience_insight_type"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AudienceInsightsResponse"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"tags": [
"audience_insights"
]
}
},
"/ad_accounts/{ad_account_id}/insights/audiences": {
"get": {
"summary": "Get audience insights scope and type",
"description": "Get the scope and type of available audiences, which along with a date, is an audience that has recently had an interaction (referred to here as a type) on pins. Interacted pins can belong to at least the most common **partner** or **Pinterest** scopes. This means that user interactions made on advertiser or partner pins will have the **partner** scope. You can also have user interactions performed in general on Pinterest with the **Pinterest** scope. In that case, you can then use the returned type and scope values together on requests to other endpoints to retrieve insight metrics for a desired audience.",
"operationId": "audience_insights_scope_and_type/get",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AudienceDefinitionResponse"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"tags": [
"audience_insights"
]
}
},
"/ad_accounts/{ad_account_id}/insights/audiences/{scope}/{type}/{category_id}": {
"get": {
"description": "Get information about a category's sub-level interests. For a list of interests, their IDs, and hierarchy, \nsee the [list of interests](https://docs.google.com/spreadsheets/d/1HxL-0Z3p2fgxis9YBP2HWC3tvPrs1hAuHDRtH-NJTIM/edit#gid=118370875). \nAlso, a category is a level-one (L1) interest. For example, in the interest hierarchy see **Animals** > **Mammals** > **Dogs**, **Animals** \nis the category.",
"operationId": "audiences/insights_category/list",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/path_scope"
},
{
"$ref": "#/components/parameters/path_type"
},
{
"$ref": "#/components/parameters/path_category_id"
},
{
"$ref": "#/components/parameters/query_sort"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AudienceInsightCategoryArrayResponse"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"summary": "Get category sub-interest",
"tags": [
"audiences"
]
}
},
"/ad_accounts/{ad_account_id}/customer_lists": {
"post": {
"description": "Create a customer list from your records(hashed or plain-text email addresses, or hashed MAIDs or IDFAs).
\nA 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.
\nPlease review our requirements for what type of information is allowed when uploading a customer list.
\nWhen 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.
\nNote that once you have created your customer list, you must convert it into an audience (of the “CUSTOMER_LIST” type)\nusing the create audience endpoint before it can be used.
", "operationId": "customer_lists/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListRequest" } } }, "description": "Parameters to get Customer lists info", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Create customer lists", "tags": [ "customer_lists" ] }, "get": { "description": "Get a set of customer lists including id and name based on the filters provided.
\n(Customer lists are a type of audience.) For more information, see\nAudience targeting\n or the Audiences\nsection of the ads management guide.
", "operationId": "customer_lists/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerList" } } } } ] } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Get customer lists", "tags": [ "customer_lists" ] } }, "/ad_accounts/{ad_account_id}/customer_lists/{customer_list_id}": { "get": { "summary": "Get customer list", "description": "Gets a specific customer list given the customer list ID.", "operationId": "customer_lists/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_customer_list_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" } } }, "description": "Success" }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "customer_lists" ] }, "patch": { "description": "Append or remove records to/from an existing customer list. (A customer list is one of the four types of Pinterest audiences.)
\nWhen 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.
\nFor more information, see Audience targeting\nor the Audiences\nsection of the ads management guide.
", "operationId": "customer_lists/update", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_customer_list_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerListUpdateRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Update customer list", "tags": [ "customer_lists" ] } }, "/ad_accounts/{ad_account_id}/keywords": { "get": { "summary": "Get keywords", "description": "Get a list of keywords based on the filters provided.
For more information, see Keyword targeting.
\nNotes:
For more information on match types, see match type enums.
\nReturns:
A successful call returns an object containing an array of new keyword objects and an empty "errors" object array.
An unsuccessful call returns an empty keywords array, and, instead, inserts the entire object with nulled/negated properties into the "errors" object array:
{ \"keywords\": [], \"errors\": [ { \"data\": { \"archived\": null, \"match_type\": \"EXACT\", \"parent_type\": null, \"value\": \"foobar\", \"parent_id\": null, \"type\": \"keyword\", \"id\": null }, \"error_messages\": [ \"Advertisers and Campaigns only accept excluded targeting attributes.\" ] } } Create keywords for following entity types(advertiser, campaign, ad group or ad).
For more information, see Keyword targeting.
\nNotes:
For more information on match types, see match type enums.
\nReturns:
A successful call returns an object containing an array of new keyword objects and an empty "errors" object array.
An unsuccessful call returns an empty keywords array, and, instead, inserts the entire object with nulled/negated properties into the "errors" object array:
{ \"keywords\": [], \"errors\": [ { \"data\": { \"archived\": null, \"match_type\": \"EXACT\", \"parent_type\": null, \"value\": \"foobar\", \"parent_id\": null, \"type\": \"keyword\", \"id\": null }, \"error_messages\": [ \"Advertisers and Campaigns only accept excluded targeting attributes.\" ] } } Rate limit: WRITE.
", "operationId": "keywords/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordsRequest" } } } }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordsResponse" } } }, "description": "Success" }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "keywords" ] }, "patch": { "summary": "Update keywords", "description": "Update one or more keywords' bid and archived fields.
Archiving a keyword effectively deletes it - keywords no longer receive metrics and no longer visible within the parent entity's keywords list.
", "operationId": "keywords/update", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordUpdateBody" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordsResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "keywords" ] } }, "/ad_accounts/{ad_account_id}/keywords/metrics": { "get": { "summary": "Get country's keyword metrics", "description": "See keyword metrics for a specified country, aggregated across all of Pinterest.\n(Definitions are available from the \"Get delivery metrics definitions\"\nAPI endpoint).", "operationId": "country_keywords_metrics/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_country_code" }, { "$ref": "#/components/parameters/query_keywords" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/KeywordsMetricsArrayResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "keywords" ] } }, "/ad_accounts/{ad_account_id}/product_group_promotions": { "post": { "description": "Add one or more product groups from your catalog to an existing ad group. (Product groups added to an ad group are a 'product group promotion.')", "operationId": "product_group_promotions/create", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductGroupPromotionCreateRequest" } } }, "description": "List of Product Group Promotions to create, size limit [1, 30].", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductGroupPromotionResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Create product group promotions", "tags": [ "product_group_promotions" ] }, "patch": { "description": "Update multiple existing Product Group Promotions (by product_group_id)", "operationId": "product_group_promotions/update", "security": [ { "pinterest_oauth2": [ "ads:write" ] } ], "x-ratelimit-category": "ads_write", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductGroupPromotionUpdateRequest" } } }, "description": "Parameters to update Product group promotions", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductGroupPromotionResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Update product group promotions", "tags": [ "product_group_promotions" ] }, "get": { "description": "List existing product group promotions associated with an ad account.", "operationId": "product_group_promotions/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_product_group_promotion_ids" }, { "$ref": "#/components/parameters/query_entity_statuses" }, { "$ref": "#/components/parameters/query_ad_group_id" }, { "$ref": "#/components/parameters/query_page_size" }, { "$ref": "#/components/parameters/query_order" }, { "$ref": "#/components/parameters/query_bookmark" } ], "responses": { "200": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Paginated" }, { "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/ProductGroupPromotionResponseItem" } } } } ] } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Get product group promotions", "tags": [ "product_group_promotions" ] } }, "/ad_accounts/{ad_account_id}/product_group_promotions/{product_group_promotion_id}": { "get": { "description": "Get a product group promotion by id", "operationId": "product_group_promotions/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/path_product_group_promotion_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductGroupPromotionResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Get a product group promotion by id", "tags": [ "product_group_promotions" ] } }, "/ad_accounts/{ad_account_id}/targeting_analytics": { "get": { "summary": "Get targeting analytics for an ad account", "description": "Get targeting analytics for an ad account.\nFor the requested account and metrics, the response will include the requested metric information\n(e.g. SPEND_IN_DOLLAR) for the requested target type (e.g. \"age_bucket\") for applicable values (e.g. \"45-49\"). \n- The token's user_account must either be the Owner of the specified ad account, or have one\nof the necessary roles granted to them via\nBusiness Access: Admin, Analyst, Campaign Manager.\n- If granularity is not HOUR, the furthest back you can are allowed to pull data is 914 days before the current date in UTC time and the max time range supported is 186 days.\n- If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.", "operationId": "ad_account_targeting_analytics/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_analytics", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_start_date" }, { "$ref": "#/components/parameters/query_end_date" }, { "$ref": "#/components/parameters/query_targeting_types" }, { "$ref": "#/components/parameters/query_columns" }, { "$ref": "#/components/parameters/query_granularity" }, { "$ref": "#/components/parameters/query_conversion_attribution_click_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_engagement_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_view_window_days" }, { "$ref": "#/components/parameters/query_conversion_attribution_conversion_report_time" }, { "$ref": "#/components/parameters/query_attribution_types" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetricsResponse" } } }, "description": "Success" }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "tags": [ "ad_accounts" ] } }, "/terms/suggested": { "get": { "summary": "List suggested terms", "description": "Get popular search terms that begin with your input term. \nExample: 'sport' would return popular terms like 'sports bar' and 'sportswear', but not 'motor sports' since the phrase does not begin with the given term.", "tags": [ "terms" ], "operationId": "terms_suggested/list", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/query_input_term" }, { "$ref": "#/components/parameters/query_term_limit" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsSuggestedResponse" } } }, "description": "Success" }, "400": { "description": "Invalid terms suggested parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "code": 400, "message": "Invalid terms suggested parameters." } } } }, "default": { "description": "Unexpected error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/ad_accounts/{ad_account_id}/terms_of_service": { "get": { "description": "Get the text of the terms of service and see whether the advertiser has accepted the terms of service.", "operationId": "terms_of_service/get", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" }, { "$ref": "#/components/parameters/query_include_html" }, { "$ref": "#/components/parameters/query_tos_type" } ], "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TermsOfService" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "summary": "Get terms of service", "tags": [ "terms_of_service" ] } }, "/ad_accounts/{ad_account_id}/bulk/download": { "post": { "summary": "Get advertiser entities in bulk", "description": "Create an asynchronous report that may include information on campaigns, ad groups, product groups, ads,\nand/or keywords; can filter by campaigns. Though the entities may be active, archived, or paused,\nonly active entities will return data.", "operationId": "bulk_download/create", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "disabled", "parameters": [ { "$ref": "#/components/parameters/path_ad_account_id" } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDownloadRequest" } } }, "description": "Parameters to get ad entities in bulk", "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkDownloadResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "bulk" ] } }, "/ad_accounts/{ad_account_id}/bulk/upsert": { "post": { "description": "Either create or update any combination of campaigns, ad groups, product groups, ads, or keywords.\nNote that this request will be processed asynchronously; the response will include arequest_id\nthat can be used to obtain the status of the request.",
"operationId": "bulk_upsert/create",
"security": [
{
"pinterest_oauth2": [
"ads:write"
]
}
],
"x-ratelimit-category": "ads_write",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkUpsertRequest"
}
}
},
"description": "Parameters to get create/update ad entities in bulk",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkUpsertResponse"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"summary": "Create/update ad entities in bulk",
"tags": [
"bulk"
]
}
},
"/ad_accounts/{ad_account_id}/bulk/{bulk_request_id}": {
"get": {
"description": "Get the status of a bulk request by request_id, along with a download URL that will allow you to download the\nnew or updated entity data (campaigns, ad groups, product groups, ads, or keywords).",
"operationId": "bulk_request/get",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/path_bulk_request_id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BulkUpsertStatusResponse"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"summary": "Download advertiser entities in bulk",
"tags": [
"bulk"
]
}
},
"/catalogs/feeds": {
"get": {
"x-ratelimit-category": "catalogs_read",
"summary": "List feeds",
"description": "Fetch feeds owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more",
"operationId": "feeds/list",
"security": [
{
"pinterest_oauth2": [
"catalogs:read"
]
}
],
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/query_bookmark"
},
{
"$ref": "#/components/parameters/query_page_size"
},
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Paginated"
},
{
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CatalogsFeed"
}
}
}
}
]
}
}
},
"description": "Success"
},
"400": {
"description": "Invalid parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"InvalidRequest": {
"value": {
"code": 1,
"message": "Parameter 'page_size' was not numeric (was 3e)\""
}
}
}
}
}
},
"401": {
"description": "Unauthorized access.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"UnauthorizedAccess": {
"value": {
"code": 29,
"message": "You are not permitted to access that resource."
}
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"catalogs"
]
},
"post": {
"x-ratelimit-category": "catalogs_write",
"summary": "Create feed",
"description": "Create a new feed owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nPlease, be aware that \"default_country\"\nand \"default_locale\" are not required in the spec for forward compatibility\nbut for now the API will not accept requests without those fields.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more",
"operationId": "feeds/create",
"security": [
{
"pinterest_oauth2": [
"catalogs:read",
"catalogs:write"
]
}
],
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"requestBody": {
"description": "Request object used to created a feed.",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogsFeedsCreateRequest"
}
}
}
},
"responses": {
"201": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogsFeed"
}
}
},
"description": "Success"
},
"400": {
"description": "Invalid feed parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"InvalidRequest": {
"value": {
"code": 1,
"message": "Invalid request: ..."
}
}
}
}
}
},
"401": {
"description": "Unauthorized access.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"UnauthorizedAccess": {
"value": {
"code": 29,
"message": "You are not permitted to access that resource."
}
}
}
}
}
},
"403": {
"description": "Business account required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"BusinessAccountRequired": {
"value": {
"code": 654,
"message": "You must have a business account to operate as merchant."
}
},
"MerchantDisapproved": {
"value": {
"code": 2625,
"message": "Sorry, you cannot perform this action. Account is disapproved."
}
}
}
}
}
},
"409": {
"description": "User website required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"UserWebsiteRequired": {
"value": {
"code": 4168,
"message": "User does not have a website."
}
},
"UserWebsiteNotVerified": {
"value": {
"code": 4169,
"message": "User does not have a verified website."
}
}
}
}
}
},
"422": {
"description": "Unique feed name is required.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"FeedDuplicatedName": {
"value": {
"code": 4170,
"message": "The feed name already exists."
}
}
}
}
}
},
"501": {
"description": "Not implemented (absent \"default_country\" or \"default_locale\").",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"NotImplemented": {
"value": {
"code": 4181,
"message": "Not implemented at the moment. Please, see documentation"
}
}
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"catalogs"
]
}
},
"/catalogs/feeds/{feed_id}": {
"get": {
"x-ratelimit-category": "catalogs_read",
"summary": "Get feed",
"description": "Get a single feed owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more",
"operationId": "feeds/get",
"security": [
{
"pinterest_oauth2": [
"catalogs:read"
]
}
],
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_catalogs_feed_id"
},
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogsFeed"
}
}
},
"description": "Success"
},
"400": {
"description": "Invalid feed parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"InvalidRequest": {
"value": {
"code": 1,
"message": "'feed_id' value '1511851494501_' must match the pattern: ^\\d+$\"}"
}
}
}
}
}
},
"401": {
"description": "Unauthorized access.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"UnauthorizedAccess": {
"value": {
"code": 29,
"message": "You are not permitted to access that resource."
}
}
}
}
}
},
"404": {
"description": "Data feed not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"FeedNotFound": {
"value": {
"code": 4161,
"message": "Sorry! We could not find your catalogs feed."
}
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"catalogs"
]
},
"patch": {
"x-ratelimit-category": "catalogs_write",
"summary": "Update feed",
"description": "Update a feed owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more",
"operationId": "feeds/update",
"security": [
{
"pinterest_oauth2": [
"catalogs:read",
"catalogs:write"
]
}
],
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_catalogs_feed_id"
},
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"requestBody": {
"description": "Request object used to update a feed.",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogsFeedsUpdateRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogsFeed"
}
}
},
"description": "Success"
},
"400": {
"description": "Invalid feed parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"InvalidRequest": {
"value": {
"code": 1,
"message": "Invalid request: ..."
}
}
}
}
}
},
"403": {
"description": "Forbidden. Account not approved for feed mutations yet.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"MerchantDisapproved": {
"value": {
"code": 2625,
"message": "Sorry, you cannot perform this action. Account is disapproved."
}
},
"MerchantUnderReview": {
"value": {
"code": 2626,
"message": "Sorry, you cannot perform this action. Account is under review."
}
}
}
}
}
},
"404": {
"description": "Data feed not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"FeedNotFound": {
"value": {
"code": 4161,
"message": "Sorry! We could not find your catalogs feed."
}
}
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"catalogs"
]
},
"delete": {
"x-ratelimit-category": "catalogs_write",
"summary": "Delete feed",
"description": "Delete a feed owned by the \"operating user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more",
"operationId": "feeds/delete",
"security": [
{
"pinterest_oauth2": [
"catalogs:read",
"catalogs:write"
]
}
],
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_catalogs_feed_id"
},
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"responses": {
"204": {
"description": "Feed deleted successfully."
},
"400": {
"description": "Invalid feed parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"InvalidRequest": {
"value": {
"code": 1,
"message": "'feed_id' value '1511851494501_' must match the pattern: ^\\d+$\"}"
}
}
}
}
}
},
"403": {
"description": "Forbidden. Account not approved for feed mutations yet.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"MerchantDisapproved": {
"value": {
"code": 2625,
"message": "Sorry, you cannot perform this action. Account is disapproved."
}
},
"MerchantUnderReview": {
"value": {
"code": 2626,
"message": "Sorry, you cannot perform this action. Account is under review."
}
}
}
}
}
},
"404": {
"description": "Data feed not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"FeedNotFound": {
"value": {
"code": 4161,
"message": "Sorry! We could not find your catalogs feed."
}
}
}
}
}
},
"409": {
"description": "Conflict. Can't delete a feed with active promotions.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"FeedHasActivePromotions": {
"value": {
"code": 4162,
"message": "We can't disable a Product Group with active promotions."
}
}
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"catalogs"
]
}
},
"/catalogs/feeds/{feed_id}/processing_results": {
"get": {
"x-ratelimit-category": "catalogs_read",
"summary": "List processing results for a given feed",
"description": "Fetch a feed processing results owned by the \"operation user_account\". Please note that for now the bookmark parameter is not functional and only the first page will be available until it is implemented in some release in the near future.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more",
"operationId": "feed_processing_results/list",
"security": [
{
"pinterest_oauth2": [
"catalogs:read"
]
}
],
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_catalogs_feed_id"
},
{
"$ref": "#/components/parameters/query_bookmark"
},
{
"$ref": "#/components/parameters/query_page_size"
},
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Paginated"
},
{
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CatalogsFeedProcessingResult"
}
}
}
}
]
}
}
},
"description": "Success"
},
"400": {
"description": "Invalid parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"InvalidRequest": {
"value": {
"code": 1,
"message": "Parameter 'page_size' was not numeric (was 3e)\""
}
}
}
}
}
},
"401": {
"description": "Unauthorized access.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"UnauthorizedAccess": {
"value": {
"code": 29,
"message": "You are not permitted to access that resource."
}
}
}
}
}
},
"404": {
"description": "Feed not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"FeedNotFound": {
"value": {
"code": 4161,
"message": "Sorry! We could not find your catalogs feed."
}
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"catalogs"
]
}
},
"/catalogs/processing_results/{processing_result_id}/item_issues": {
"get": {
"x-ratelimit-category": "catalogs_read",
"summary": "List item issues for a given processing result",
"description": "List item validation issues for a given feed processing result owned by the \"operation user_account\". Please note that for now query parameters 'item_numbers' and 'item_validation_issue' cannot be used simultaneously until it is implemented in some release in the future.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more",
"operationId": "items_issues/list",
"security": [
{
"pinterest_oauth2": [
"catalogs:read"
]
}
],
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/query_bookmark"
},
{
"$ref": "#/components/parameters/query_page_size"
},
{
"$ref": "#/components/parameters/path_catalogs_processing_result_id"
},
{
"$ref": "#/components/parameters/query_catalogs_item_numbers"
},
{
"$ref": "#/components/parameters/query_catalogs_item_validation_issue"
},
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Paginated"
},
{
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/CatalogsItemValidationIssues"
}
}
}
}
]
}
}
},
"description": "Success"
},
"401": {
"description": "Unauthorized access.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"UnauthorizedAccess": {
"value": {
"code": 29,
"message": "You are not permitted to access that resource."
}
}
}
}
}
},
"404": {
"description": "Processing Result not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"ProcessingResultFound": {
"value": {
"code": 4184,
"message": "Sorry! We could not find your processing result."
}
}
}
}
}
},
"501": {
"description": "Not implemented.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"NotImplemented": {
"value": {
"code": 4181,
"message": "Not implemented at the moment. Please, see documentation."
}
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"catalogs"
]
}
},
"/catalogs/items": {
"get": {
"summary": "Get catalogs items",
"description": "Get the items of the catalog owned by the \"operation user_account\". See detailed documentation here.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.",
"operationId": "items/get",
"security": [
{
"pinterest_oauth2": [
"catalogs:read"
]
}
],
"x-ratelimit-category": "catalogs_read",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/query_catalogs_items_country"
},
{
"$ref": "#/components/parameters/query_catalogs_items"
},
{
"$ref": "#/components/parameters/query_catalogs_items_language"
},
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"responses": {
"200": {
"description": "Response containing the requested catalogs items",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogsItems"
}
}
}
},
"400": {
"description": "Invalid request parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"InvalidRequest": {
"value": {
"code": 1,
"message": "Parameter 'item_ids' is required."
}
}
}
}
}
},
"401": {
"description": "Not authorized to access catalogs items",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"UnauthorizedAccess": {
"value": {
"code": 2,
"message": "Authentication failed."
}
}
}
}
}
},
"403": {
"description": "Not authorized to access catalogs items",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"catalogs"
]
}
},
"/catalogs/items/batch/{batch_id}": {
"get": {
"summary": "Get catalogs items batch",
"description": "Get a single catalogs items batch owned by the \"operating user_account\". See detailed documentation here.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.",
"operationId": "items_batch/get",
"security": [
{
"pinterest_oauth2": [
"catalogs:read"
]
}
],
"x-ratelimit-category": "catalogs_read",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_catalogs_items_batch_id"
},
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"responses": {
"200": {
"description": "Response containing the requested catalogs items batch",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogsItemsBatch"
}
}
}
},
"401": {
"description": "Not authenticated to access catalogs items batch",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"UnauthenticatedAccess": {
"value": {
"code": 2,
"message": "Authentication failed."
}
}
}
}
}
},
"403": {
"description": "Not authorized to access catalogs items batch",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Catalogs items batch not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"CannotFindBatch": {
"value": {
"code": 4331,
"message": "Sorry! We could not find your batch ID."
}
}
}
}
}
},
"405": {
"description": "Method Not Allowed.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"MethodNotAllowed": {
"value": {
"status": "failure",
"code": 5,
"data": "405 Method Not Allowed: The method is not allowed for the requested URL.",
"message": "Method not allowed",
"endpoint_name": null
}
}
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"catalogs"
]
}
},
"/catalogs/items/batch": {
"post": {
"summary": "Operate on item batch",
"description": "This endpoint supports multiple operations on a set of one or more catalog items owned by the \"operation user_account\". See detailed documentation here.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.",
"operationId": "items_batch/post",
"x-ratelimit-category": "catalogs_write",
"x-sandbox": "disabled",
"security": [
{
"pinterest_oauth2": [
"catalogs:read",
"catalogs:write"
]
}
],
"parameters": [
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"requestBody": {
"description": "Request object used to create catalogs items in a batch",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogsItemsBatchRequest"
}
}
}
},
"responses": {
"200": {
"description": "Response containing the requested catalogs items batch",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogsItemsBatch"
}
}
}
},
"400": {
"description": "Invalid request parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"InvalidRequest": {
"value": {
"code": 1,
"message": "Invalid request: {'country': 'US', 'language': 'EN', 'operation': 'CREATE', 'items': [{'item_id': 'RAY_01_', 'attributes': {'image_link': 'https://www.example.com/', 'title': 'My Product'}}]} ('https://www.example.com/' is not of type array)"
}
}
}
}
}
},
"401": {
"description": "Not authenticated to post catalogs items",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"UnauthenticatedAccess": {
"value": {
"code": 2,
"message": "Authentication failed."
}
}
}
}
}
},
"403": {
"description": "Not authorized to post catalogs items",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"catalogs"
]
}
},
"/catalogs/products/get_by_product_group_filters": {
"post": {
"x-ratelimit-category": "catalogs_read",
"summary": "List filtered products",
"description": "List products Pins owned by the \"operation user_account\" that meet the criteria specified in the Catalogs Product Group Filter given in the request.\n- This endpoint has been implemented in POST to allow for complex filters. This specific POST endpoint is designed to be idempotent.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more",
"operationId": "products_by_product_group_filter/list",
"security": [
{
"pinterest_oauth2": [
"boards:read",
"catalogs:read",
"pins:read"
]
}
],
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/query_bookmark"
},
{
"$ref": "#/components/parameters/query_page_size"
},
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"requestBody": {
"description": "Object holding a group of filters for a catalog product group",
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogsListProductsByFilterRequest"
}
}
}
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Paginated"
},
{
"properties": {
"items": {
"description": "Pins",
"items": {
"$ref": "#/components/schemas/CatalogsProduct"
}
}
}
}
]
}
}
},
"description": "Success"
},
"401": {
"description": "Unauthorized access.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"UnauthorizedAccess": {
"value": {
"code": 29,
"message": "You are not permitted to access that resource."
}
}
}
}
}
},
"409": {
"description": "Conflict. Can't get products.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"CatalogsMerchantNotCreated": {
"value": {
"code": 4182,
"message": "Can't acccess this feature without an existing catalog."
}
},
"CatalogsProductGroupFiltersInvalid": {
"value": {
"code": 4183,
"message": "Catalog product group filters failed validation, please ensure all filters are set correctly."
}
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"catalogs"
]
}
},
"/catalogs/product_groups/{product_group_id}": {
"get": {
"x-ratelimit-category": "catalogs_read",
"summary": "Get product group",
"description": "Get a singe product group for a given Catalogs Product Group Id owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more",
"operationId": "catalogs_product_groups/get",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_catalogs_product_group_id"
},
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"security": [
{
"pinterest_oauth2": [
"catalogs:read"
]
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/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 owned by the \"operation user_account\" from being in use in Catalogs.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more",
"operationId": "catalogs_product_groups/delete",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_catalogs_product_group_id"
},
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"security": [
{
"pinterest_oauth2": [
"catalogs:write"
]
}
],
"responses": {
"204": {
"description": "Catalogs Product Group deleted successfully."
},
"400": {
"description": "Invalid catalogs product group id parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"InvalidRequest": {
"value": {
"code": 1,
"message": "'product_group_id' value '11851494501_' must match the pattern: ^\\d+$\"}"
}
}
}
}
}
},
"401": {
"description": "Unauthorized access.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"UnauthorizedAccess": {
"value": {
"code": 29,
"message": "You are not permitted to access that resource."
}
}
}
}
}
},
"403": {
"description": "Forbidden. Account not approved for catalog product group mutations yet.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"MerchantDisapproved": {
"value": {
"code": 2625,
"message": "Sorry, you cannot perform this action. Account is disapproved."
}
},
"MerchantUnderReview": {
"value": {
"code": 2626,
"message": "Sorry, you cannot perform this action. Account is under review."
}
}
}
}
}
},
"404": {
"description": "Catalogs product group not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"CatalogsProductGroupNotFound": {
"value": {
"code": 4180,
"message": "Sorry! We could not find your catalogs product group."
}
}
}
}
}
},
"409": {
"description": "Conflict. Can't delete this catalogs product group.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"CatalogsProductGroupHasActivePromotions": {
"value": {
"code": 4176,
"message": "We can't delete a Catalogs Product Group with active promotions."
}
},
"CannotAlterAutoGeneratedCatalogsProductGroup": {
"value": {
"code": 4177,
"message": "You cannot alter an auto generated catalogs product group."
}
},
"CatalogsMerchantNotCreated": {
"value": {
"code": 4182,
"message": "Can't access this feature without an existing catalog."
}
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"catalogs"
]
},
"patch": {
"x-ratelimit-category": "catalogs_write",
"summary": "Update product group",
"description": "Update product group owned by the \"operation user_account\" to use in Catalogs.\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more",
"operationId": "catalogs_product_groups/update",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_catalogs_product_group_id"
},
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"security": [
{
"pinterest_oauth2": [
"catalogs:write"
]
}
],
"requestBody": {
"description": "Request object used to Update a catalogs product group.",
"required": true,
"content": {
"application/json": {
"schema": {
"$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 owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more",
"operationId": "catalogs_product_group_pins/list",
"security": [
{
"pinterest_oauth2": [
"boards:read",
"catalogs:read",
"pins:read"
]
}
],
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/query_bookmark"
},
{
"$ref": "#/components/parameters/query_page_size"
},
{
"$ref": "#/components/parameters/path_catalogs_product_group_id"
},
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Paginated"
},
{
"properties": {
"items": {
"description": "Pins",
"items": {
"$ref": "#/components/schemas/CatalogsProduct"
}
}
}
}
]
}
}
},
"description": "Success"
},
"400": {
"description": "Invalid parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"InvalidRequest": {
"value": {
"code": 1,
"message": "'product_group_id' value '11851494501_' must match the pattern: ^\\d+$\"}"
}
}
}
}
}
},
"401": {
"description": "Unauthorized access.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"UnauthorizedAccess": {
"value": {
"code": 29,
"message": "You are not permitted to access that resource."
}
}
}
}
}
},
"404": {
"description": "Catalogs product group not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"CatalogsProductGroupNotFound": {
"value": {
"code": 4180,
"message": "Sorry! We could not find your catalogs product group."
}
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"catalogs"
]
}
},
"/catalogs/product_groups/{product_group_id}/product_counts": {
"get": {
"x-ratelimit-category": "catalogs_read",
"summary": "Get product counts",
"description": "Get a product counts for a given Catalogs Product Group owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more",
"operationId": "catalogs_product_groups/product_counts_get",
"security": [
{
"pinterest_oauth2": [
"catalogs:read"
]
}
],
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_catalogs_product_group_id"
},
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CatalogsProductGroupProductCounts"
}
}
},
"description": "Success"
},
"404": {
"description": "Product Group Not Found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"CatalogsProductGroupNotFound": {
"value": {
"code": 4180,
"message": "Sorry! We could not find your catalogs product group."
}
}
}
}
}
},
"409": {
"description": "Can't access this feature without an existing catalog.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"CatalogsMerchantNotCreated": {
"value": {
"code": 4182,
"message": "Can't access this feature without an existing catalog."
}
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"catalogs"
]
}
},
"/catalogs/product_groups": {
"get": {
"x-ratelimit-category": "catalogs_read",
"summary": "List product groups",
"description": "Get a list of product groups for a given Catalogs Feed Id owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more",
"operationId": "catalogs_product_groups/list",
"security": [
{
"pinterest_oauth2": [
"catalogs:read"
]
}
],
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/query_catalogs_feed_id"
},
{
"$ref": "#/components/parameters/query_bookmark"
},
{
"$ref": "#/components/parameters/query_page_size"
},
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Paginated"
},
{
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/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 owned by the \"operation user_account\".\n- By default, the \"operation user_account\" is the token user_account.\n\nOptional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the \"operation user_account\". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account: Owner, Admin, Catalogs Manager.\n\nLearn more",
"operationId": "catalogs_product_groups/create",
"security": [
{
"pinterest_oauth2": [
"catalogs:write"
]
}
],
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/query_ad_account_id"
}
],
"requestBody": {
"description": "Request object used to created a catalogs product group.",
"required": true,
"content": {
"application/json": {
"schema": {
"$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"
]
}
},
"/ad_accounts/{ad_account_id}/order_lines": {
"get": {
"summary": "Get Order Lines",
"description": "List existing order lines associated with an ad account.",
"operationId": "order_lines/list",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "enabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_page_size"
},
{
"$ref": "#/components/parameters/query_order"
},
{
"$ref": "#/components/parameters/query_bookmark"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Paginated"
},
{
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/OrderLine"
}
}
}
}
]
}
}
},
"description": "Success"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"order_lines"
]
}
},
"/ad_accounts/{ad_account_id}/order_lines/{order_line_id}": {
"get": {
"summary": "Get order line",
"description": "Get a specific existing order line associated with an ad account.",
"operationId": "order_lines/get",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "enabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/path_order_line_id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OrderLine"
}
}
},
"description": "Success"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"order_lines"
]
}
},
"/integrations/commerce": {
"post": {
"summary": "Create commerce integration",
"description": "Create commerce integration metadata to link an external business ID with a Pinterest merchant & ad account.",
"operationId": "integrations_commerce/post",
"security": [
{
"pinterest_oauth2": [
"ads:write"
]
}
],
"x-ratelimit-category": "ads_write",
"x-sandbox": "disabled",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegrationRequest"
}
}
},
"description": "Parameters to get create/update the Integration Metadata"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegrationMetadata"
}
}
},
"description": "Success"
},
"404": {
"description": "Integration not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"IntegrationNotFound": {
"value": {
"code": 4180,
"message": "Sorry! We could not find your integration."
}
}
}
}
}
},
"409": {
"description": "Can't access this integration metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"NotIntegrationOwner": {
"value": {
"code": 4182,
"message": "Can't access this integration metadata."
}
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"integrations"
]
}
},
"/integrations/commerce/{external_business_id}": {
"get": {
"summary": "Get commerce integration",
"description": "Get commerce integration metadata associated with the given external business ID",
"operationId": "integrations_commerce/get",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_external_business_id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegrationMetadata"
}
}
},
"description": "Success"
},
"404": {
"description": "Integration not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"IntegrationNotFound": {
"value": {
"code": 4180,
"message": "Sorry! We could not find your integration."
}
}
}
}
}
},
"409": {
"description": "Can't access this integration metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"NotIntegrationOwner": {
"value": {
"code": 4182,
"message": "Can't access this integration metadata."
}
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"integrations"
]
},
"patch": {
"summary": "Update commerce integration",
"description": "Update commerce integration metadata for the given external business ID",
"operationId": "integrations_commerce/patch",
"security": [
{
"pinterest_oauth2": [
"ads:write"
]
}
],
"x-ratelimit-category": "ads_write",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_external_business_id"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegrationRequestPatch"
}
}
},
"description": "Parameters to get create/update the Integration Metadata"
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/IntegrationMetadata"
}
}
},
"description": "Success"
},
"404": {
"description": "Integration not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"IntegrationNotFound": {
"value": {
"code": 4180,
"message": "Sorry! We could not find your integration."
}
}
}
}
}
},
"409": {
"description": "Can't access this integration metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"NotIntegrationOwner": {
"value": {
"code": 4182,
"message": "Can't access this integration metadata."
}
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"integrations"
]
},
"delete": {
"summary": "Delete commerce integration",
"description": "Delete commerce integration metadata for the given external business ID.",
"operationId": "integrations_commerce/del",
"security": [
{
"pinterest_oauth2": [
"ads:write"
]
}
],
"x-ratelimit-category": "ads_write",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_external_business_id"
}
],
"responses": {
"204": {
"description": "Commerce Integration deleted successfully"
},
"404": {
"description": "Integration not found.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"IntegrationNotFound": {
"value": {
"code": 4180,
"message": "Sorry! We could not find your integration."
}
}
}
}
}
},
"409": {
"description": "Can't access this integration metadata.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"NotIntegrationOwner": {
"value": {
"code": 4182,
"message": "Can't access this integration metadata."
}
}
}
}
}
},
"default": {
"description": "Unexpected error.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"integrations"
]
}
},
"/resources/ad_account_countries": {
"get": {
"summary": "Get ad accounts countries",
"description": "Get Ad Accounts countries",
"operationId": "ad_account_countries/get",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "enabled",
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AdAccountsCountryResponse"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"tags": [
"resources"
]
}
},
"/resources/delivery_metrics": {
"get": {
"summary": "Get available metrics' definitions",
"description": "Get the definitions for ads and organic metrics available across both synchronous and asynchronous report endpoints.\nThe `display_name` attribute will match how the metric is named in our native tools like Ads Manager.\nSee Organic Analytics and Ads Analytics for more information.",
"operationId": "delivery_metrics/get",
"security": [
{
"pinterest_oauth2": [
"ads:read",
"pins:read",
"user_accounts:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "enabled",
"parameters": [
{
"$ref": "#/components/parameters/query_report_type"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeliveryMetricsResponse"
}
}
},
"description": "Success"
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"resources"
]
}
},
"/resources/metrics_ready_state": {
"get": {
"summary": "Get metrics ready state",
"description": "Learn whether conversion or non-conversion metrics are finalized and ready to query.",
"operationId": "metrics_ready_state/get",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_analytics",
"x-sandbox": "enabled",
"parameters": [
{
"name": "date",
"description": "Analytics reports request date (UTC). Format: YYYY-MM-DD",
"in": "query",
"required": true,
"style": "form",
"schema": {
"type": "string",
"pattern": "^(\\d{4})-(\\d{2})-(\\d{2})$",
"example": "2022-07-13"
}
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BookClosedResponse"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"tags": [
"resources"
]
}
},
"/resources/targeting/interests/{interest_id}": {
"get": {
"summary": "Get interest details",
"description": "Get details of a specific interest given interest ID.
Click here for a spreadsheet listing interests and their IDs.
", "operationId": "interest_targeting_options/get", "security": [ { "pinterest_oauth2": [ "ads:read" ] } ], "x-ratelimit-category": "ads_read", "x-sandbox": "enabled", "parameters": [ { "$ref": "#/components/parameters/path_interest_id" } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SingleInterestTargetingOptionResponse" } } }, "description": "Success" }, "default": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "description": "Unexpected error" } }, "tags": [ "resources" ] } }, "/resources/targeting/{targeting_type}": { "get": { "summary": "Get targeting options", "description": "You can use targeting values in ads placement to define your intended audience.
Targeting metrics are organized around targeting specifications.
For more information on ads targeting, see Audience targeting.
\nSample return:
[{"36313": "Australia: Moreton Bay - North", "124735": "Canada: North Battleford", "36109": "Australia: Murray", "36108": "Australia: Mid North Coast", "36101": "Australia: Capital Region", "811": "U.S.: Reno", "36103": "Australia: Central West", "36102": "Australia: Central Coast", "36105": "Australia: Far West and Orana", "36104": "Australia: Coffs Harbour - Grafton", "36107": "Australia: Illawarra", "36106": "Australia: Hunter Valley Exc Newcastle", "554017": "New Zealand: Wanganui", "554016": "New Zealand: Marlborough", "554015": "New Zealand: Gisborne", "554014": "New Zealand: Tararua", "554013": "New Zealand: Invercargill", "GR": "Greece", "554011": "New Zealand: Whangarei", "554010": "New Zealand: Far North", "717": "U.S.: Quincy-Hannibal-Keokuk", "716": "U.S.: Baton Rouge",...}] ",
"operationId": "targeting_options/get",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "enabled",
"parameters": [
{
"$ref": "#/components/parameters/path_targeting_type"
},
{
"$ref": "#/components/parameters/query_client_id"
},
{
"$ref": "#/components/parameters/query_oauth_signature"
},
{
"$ref": "#/components/parameters/query_timestamp"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TargetingOptionResponse"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"tags": [
"resources"
]
}
},
"/search/pins": {
"get": {
"description": "Request to get a list of user pins matching your search query.",
"operationId": "search_user_pins/list",
"security": [
{
"pinterest_oauth2": [
"user_accounts:read"
]
}
],
"x-ratelimit-category": "org_read",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/query_query"
},
{
"$ref": "#/components/parameters/query_board"
},
{
"$ref": "#/components/parameters/query_topic_based"
},
{
"$ref": "#/components/parameters/query_richtype"
},
{
"$ref": "#/components/parameters/query_rs"
},
{
"$ref": "#/components/parameters/query_bookmark"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Paginated"
},
{
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Pin"
}
}
}
}
]
}
}
},
"description": "Success"
},
"404": {
"description": "User not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"examples": {
"UserNotFound": {
"value": {
"code": 30,
"message": "User not found."
}
}
}
}
}
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"summary": "Search user's Pins",
"tags": [
"search"
]
}
},
"/terms/related": {
"get": {
"summary": "List related terms",
"description": "Get a list of terms logically related to each input term. \nExample: the term 'workout' would list related terms like 'one song workout', 'yoga workout', 'workout motivation', etc.",
"tags": [
"terms"
],
"operationId": "terms_related/list",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "enabled",
"parameters": [
{
"$ref": "#/components/parameters/query_list_input_terms"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RelatedTerms"
}
}
},
"description": "Success"
},
"400": {
"description": "Invalid terms related parameters.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 400,
"message": "Invalid terms related parameters."
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}
}
},
"/ad_accounts/{ad_account_id}/conversion_tags": {
"get": {
"summary": "Get conversion tags",
"description": "List conversion tags associated with an ad account.",
"operationId": "conversion_tags/list",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_filter_deleted"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversionTagListResponse"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"tags": [
"conversion_tags"
],
"x-sandbox": "disabled"
},
"post": {
"x-sandbox": "disabled",
"summary": "Create conversion tag",
"description": "Create a conversion tag, also known as Pinterest tag, with the option to enable enhanced match.\nThe Pinterest Tag tracks actions people take on the ad account’s website after they view the ad account's ad on Pinterest. The advertiser needs to customize this tag to track conversions.\nFor more information, see:\nSet up the Pinterest tag\nPinterest Tag\nEnhanced match",
"operationId": "conversion_tags/create",
"security": [
{
"pinterest_oauth2": [
"ads:write"
]
}
],
"x-ratelimit-category": "ads_write",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversionTagCreate"
}
}
},
"description": "Conversion Tag to create",
"required": true
},
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversionTagResponse"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"tags": [
"conversion_tags"
]
}
},
"/ad_accounts/{ad_account_id}/conversion_tags/page_visit": {
"get": {
"summary": "Get page visit conversion tags",
"description": "Get all page visit conversion tag events for an ad account.",
"operationId": "page_visit_conversion_tags/get",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"x-sandbox": "disabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/query_page_size"
},
{
"$ref": "#/components/parameters/query_order"
},
{
"$ref": "#/components/parameters/query_bookmark"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Paginated"
},
{
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ConversionEventResponse"
}
}
}
}
]
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"tags": [
"conversion_tags"
]
}
},
"/ad_accounts/{ad_account_id}/conversion_tags/{conversion_tag_id}": {
"get": {
"x-sandbox": "disabled",
"summary": "Get conversion tag",
"description": "Get information about an existing conversion tag.",
"operationId": "conversion_tags/get",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
},
{
"$ref": "#/components/parameters/path_conversion_tag_id"
}
],
"responses": {
"200": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversionTagResponse"
}
}
},
"description": "Success"
},
"default": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
},
"description": "Unexpected error"
}
},
"tags": [
"conversion_tags"
]
}
},
"/ad_accounts/{ad_account_id}/conversion_tags/ocpm_eligible": {
"get": {
"summary": "Get Ocpm eligible conversion tags",
"description": "Get Ocpm eligible conversion tag events for an ad account.",
"security": [
{
"pinterest_oauth2": [
"ads:read"
]
}
],
"x-ratelimit-category": "ads_read",
"operationId": "ocpm_eligible_conversion_tags/get",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
}
],
"x-sandbox": "disabled",
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConversionTagsOcpmEligibleResponse"
}
}
}
},
"default": {
"description": "Unexpected errors",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"conversion_tags"
]
}
},
"/ad_accounts/{ad_account_id}/sandbox": {
"delete": {
"summary": "Delete ads data for ad account in API Sandbox",
"description": "Delete an ad account and all the ads data associated with that account. \nA string message is returned indicating the status of the delete operation.\n\nNote: This endpoint is only allowed in the Pinterest API Sandbox (https://api-sandbox.pinterest.com/v5). \nGo to https://developers.pinterest.com/docs/dev-tools/sandbox/ for more information.",
"operationId": "sandbox/delete",
"security": [
{
"pinterest_oauth2": [
"ads:write"
]
}
],
"x-ratelimit-category": "ads_write",
"x-sandbox": "enabled",
"parameters": [
{
"$ref": "#/components/parameters/path_ad_account_id"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"type": "string",
"example": "Delete Success"
}
}
}
},
"400": {
"description": "Invalid ad account id.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
},
"example": {
"code": 400,
"message": "Invalid ad account id"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"tags": [
"ad_accounts"
]
}
},
"/users/{username}/interests/follow": {
"get": {
"summary": "List following interests",
"description": "Get a list of a user's following interests in one place.",
"tags": [
"interests"
],
"operationId": "interests/followed_interests",
"security": [
{
"pinterest_oauth2": [
"user_accounts:read"
]
}
],
"x-ratelimit-category": "org_read",
"parameters": [
{
"$ref": "#/components/parameters/path_username"
},
{
"$ref": "#/components/parameters/query_bookmark"
},
{
"$ref": "#/components/parameters/query_page_size"
}
],
"responses": {
"200": {
"description": "Success",
"content": {
"application/json": {
"schema": {
"allOf": [
{
"$ref": "#/components/schemas/Paginated"
},
{
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Interest"
}
}
}
}
]
}
}
}
},
"400": {
"description": "Invalid parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Authorization failed",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "User not found",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"default": {
"description": "Unexpected error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
},
"x-sandbox": "enabled"
}
}
},
"components": {
"securitySchemes": {
"pinterest_oauth2": {
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://www.pinterest.com/oauth/",
"tokenUrl": "https://api.pinterest.com/v5/oauth/token",
"scopes": {
"ads:read": "See all of your advertising data, including ads, ad groups, campaigns etc.",
"ads:write": "Create, update, or delete ads, ad groups, campaigns etc.",
"boards:read": "See your public boards, including group boards you join",
"boards:read_secret": "See your secret boards",
"boards:write": "Create, update, or delete your public boards",
"boards:write_secret": "Create, update, or delete your secret boards",
"catalogs:read": "See all of your catalogs data",
"catalogs:write": "Create, update, or delete your catalogs data",
"pins:read": "See your public Pins",
"pins:read_secret": "See your secret Pins",
"pins:write": "Create, update, or delete your public Pins",
"pins:write_secret": "Create, update, or delete your secret Pins",
"user_accounts:read": "See your user accounts and followers",
"user_accounts:write": "Update your user accounts and followers"
}
}
}
},
"conversion_token": {
"type": "http",
"scheme": "bearer",
"description": "This security scheme only applies to the conversion events endpoint (POST /ad_accounts/{ad_account_id}/events). This endpoint requires a bearer token generated via Ads Manager (ads.pinterest.com)."
},
"basic": {
"type": "http",
"scheme": "basic"
}
},
"schemas": {
"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
},
"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"
},
{
"$ref": "#/components/schemas/AdPinId"
},
{
"type": "object",
"title": "Request schema for creating ads",
"required": [
"ad_group_id",
"pin_id",
"creative_type"
]
}
]
},
"AdPinId": {
"type": "object",
"properties": {
"pin_id": {
"description": "Pin ID.",
"example": "394205773611545468",
"type": "string",
"pattern": "^\\d+$"
}
}
},
"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": {
"SAVE": 20,
"SAVE_RATE": 0.18,
"IMPRESSION": 240,
"OUTBOUND_CLICK": 200,
"PIN_CLICK": 37,
"VIDEO_10S_VIEW": 2,
"VIDEO_V50_WATCH_TIME": 10031,
"QUARTILE_95_PERCENT_VIEW": 8,
"VIDEO_AVG_WATCH_TIME": 2507.75,
"VIDEO_START": 2,
"VIDEO_MRC_VIEW": 2
}
}
}
},
"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"
},
{
"$ref": "#/components/schemas/AdPinId"
},
{
"type": "object",
"properties": {
"ad_account_id": {
"description": "The ID of the advertiser that this ad belongs to.",
"example": "549755885175",
"type": "string",
"pattern": "^\\d+$"
},
"campaign_id": {
"description": "ID of the ad campaign that contains this ad.",
"example": "626735565838",
"type": "string",
"pattern": "^\\d+$"
},
"collection_items_destination_url_template": {
"description": "Destination URL template for all items within a collections drawer.",
"type": "string",
"nullable": true
},
"created_time": {
"description": "Pin creation time. Unix timestamp in seconds.",
"example": 1451431341,
"type": "integer"
},
"id": {
"description": "The ID of this ad.",
"example": "687195134316",
"type": "string",
"pattern": "^\\d+$"
},
"rejected_reasons": {
"description": "Enum reason why the pin was rejected. Returned if review_status is \"REJECTED\".",
"type": "array",
"items": {
"type": "string",
"description": "ad disapproval reasons",
"enum": [
"HASHTAGS",
"PROMOTIONS_AND_PRICES",
"TARGETING",
"LANDING_PAGE",
"CAPS_AND_SYMBOLS",
"SHOCKING",
"WEIGHT_LOSS",
"PROHIBITED_PRODUCT",
"AUTHENTICITY",
"NUDITY",
"CONFUSING_DESIGN",
"URGENCY",
"RATINGS",
"APP",
"ALCOHOL",
"CONTESTS",
"POLITICAL",
"OTHER",
"IMAGE",
"NAR",
"INCONSISTENT",
"CLICKBAIT",
"NO_DESCRIPTION",
"LOW_QUALITY",
"EXAGGERATED_CLAIMS",
"PINTEREST_BRAND",
"ALCOHOL_NO_SALE",
"LANDING_PAGE_SPEED",
"LANDING_PAGE_HARDWALL",
"LANDING_PAGE_BROKEN",
"LANDING_PAGE_QUALITY",
"OUT_OF_STOCK",
"IMAGE_LOW_QUALITY",
"IMAGE_BUSY",
"IMAGE_POORLY_EDITED",
"IMAGE_BEFORE_AFTER",
"UGC",
"FAKE_BUTTONS",
"WEAPONS",
"SENSITIVE",
"UNACCEPTABLE_BUSINESS",
"SUSPICIOUS_CLAIMS",
"PHARMA",
"SUSPICIOUS_SUPPLEMENTS",
"ILLEGAL_RECREATIONAL_DRUG",
"LOW_QUALITY_LANDING_PAGE",
"RESTRICTED_HEALTHCARE",
"INCONSISTENT_LANG_FR"
]
}
},
"rejection_labels": {
"description": "Text reason why the pin was rejected. Returned if review_status is \"REJECTED\".",
"type": "array",
"items": {
"type": "string"
}
},
"review_status": {
"type": "string",
"description": "Ad review status",
"example": "PENDING",
"enum": [
"OTHER",
"PENDING",
"REJECTED",
"APPROVED"
]
},
"type": {
"description": "Always \"ad\".",
"example": "pinpromotion",
"type": "string"
},
"updated_time": {
"description": "Last update time. Unix timestamp in seconds.",
"example": 1451431341,
"type": "integer"
},
"summary_status": {
"type": "string",
"allOf": [
{
"$ref": "#/components/schemas/PinPromotionSummaryStatus"
}
],
"description": "Ad summary status"
}
}
}
]
},
"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",
"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
},
"optimization_goal_metadata": {
"type": "object",
"allOf": [
{
"$ref": "#/components/schemas/OptimizationGoalMetadata"
}
],
"description": "Optimization goals for objective-based performance campaigns.",
"nullable": true
},
"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.Catalog product group type
\nMERCHANT_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.
<= 2000 characters
\nThe 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
\nThe 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
\nCustom grouping of products.
", "example": "Best sellers", "type": "string", "nullable": true }, "custom_label_1": { "description": "<= 1000 characters
\nCustom grouping of products.
", "example": "Summer promotion", "type": "string", "nullable": true }, "custom_label_2": { "description": "<= 1000 characters
\nCustom grouping of products.
", "example": "Winter sales", "type": "string", "nullable": true }, "custom_label_3": { "description": "<= 1000 characters
\nCustom grouping of products.
", "example": "Woman dress", "type": "string", "nullable": true }, "custom_label_4": { "description": "<= 1000 characters
\nCustom grouping of products.
", "example": "Man hat", "type": "string", "nullable": true }, "description": { "description": "<= 10000 characters
\nThe 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
\nThe 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
\nThe 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
\nThe 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
\nThe 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
\nThe 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" } } } }, "Interest": { "title": "Interest", "type": "object", "properties": { "canonical_url": { "type": "string" }, "id": { "type": "string", "pattern": "^\\d+$", "example": "903972677830" }, "key": { "type": "string", "example": "man cave" }, "name": { "type": "string", "example": "Man cave" } } }, "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).", "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": "integer", "description": "Keyword custom bid in microcurrency - null if inherited from parent ad group.", "example": 200000, "nullable": true }, "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).", "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: