PIpinterest
pins

Create Pin

Changed on

Create a Pin on a board or board section owned by the "operation user_account".

Note: If the current "operation user_account" (defined by the access token) has access to another user's Ad Accounts via Pinterest Business Access, you can modify your request to make use of the current operation_user_account's permissions to those Ad Accounts by including the ad_account_id in the path parameters for the request (e.g. .../?ad_account_id=12345&...).

  • This function is intended solely for publishing new content created by the user. If you are interested in saving content created by others to your Pinterest boards, sometimes called 'curated content', please use our Save button instead. For more tips on creating fresh content for Pinterest, review our Content App Solutions Guide.

Learn more about video Pin creation.

Learn more about image Pin creation.

post/pins

Request

  • Base URL
    https://api.pinterest.com/v5
  • Auth
    • OAuth 2
      Authorization codehttps://www.pinterest.com/oauth/
      Token URLhttps://api.pinterest.com/v5/oauth/token
      Scopesboards:read, boards:write, pins:read, pins:write
    • or OAuth 2
      Client credentials
      Token URLhttps://api.pinterest.com/v3/oauth/access_token/
      Scopesboards:read, boards:write, pins:read, pins:write
  • TypeScript
    A function with typed inputs. Its response is checked against the schema.

Query parameters

ad_account_idstring

Unique identifier of an ad account.

Request body

alt_textstring nullable
board_idstring

The board to which this Pin belongs.

board_section_idstring nullable

The board section to which this Pin belongs.

descriptionstring nullable
dominant_colorstring nullable

Dominant pin color. Hex number, e.g. #6E7874.

linkstring nullable
parent_pin_idstring nullable

The source pin id if this pin was saved from another pin. Learn more.

sponsor_idstring nullable

The sponsor account id to request paid partnership from. Currently the field is only available to a list of users in a closed beta.

titlestring nullable

Response

The request has succeeded.

board_idstring

The board to which this Pin belongs.

board_section_idstring nullable

The board section to which this Pin belongs.

created_atstring date-time
creative_type'REGULAR' | 'VIDEO' | 'SHOPPING' | 'CAROUSEL' | 'MAX_VIDEO' | 'SHOP_THE_PIN' | 'COLLECTION' | 'IDEA' | 'SHOWCASE' | 'QUIZ' | 'COLLAGE' | 'MAX_WIDTH_REGULAR_COLLECTION' | 'MAX_WIDTH_VIDEO_COLLECTION' | 'APP'

Ad creative type enum. Note: SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.

dominant_colorstring nullable

Dominant pin color. Hex number, e.g. #6E7874.

has_been_promotedboolean

Whether the Pin has been promoted or not.

idstring required
is_ownerboolean

Whether the "operation user_account" is the Pin owner.

is_productboolean

Whether the Pin is a product Pin.

is_standardboolean

Whether the Pin is standard or not. See documentation on Changes to Pin creation for more information.

parent_pin_idstring nullable

The source pin id if this pin was saved from another pin. Learn more.

pin_metricsobject nullable

Pin metrics with associated time intervals if any.

Example response

{
  "media": {
    "images": {
      "150x150": {
        "width": 150,
        "height": 150,
        "url": "https://i.pinimg.com/150x150/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg"
      },
      "400x300": {
        "width": 400,
        "height": 300,
        "url": "https://i.pinimg.com/400x300/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg"
      },
      "600x": {
        "width": 600,
        "height": 600,
        "url": "https://i.pinimg.com/600x/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg"
      },
      "1200x": {
        "width": 1200,
        "height": 1200,
        "url": "https://i.pinimg.com/1200x/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg"
      }
    }
  },
  "pin_metrics": {
    "90d": {
      "pin_click": 7,
      "impression": 2,
      "clickthrough": 3
    },
    "lifetime_metrics": {
      "pin_click": 7,
      "impression": 2,
      "clickthrough": 3,
      "reaction": 10,
      "comment": 2
    }
  }
}

Changes

  • v5b698c180678aRevision changes
    • breaking

      removed the required property from the response with the status

    • breaking

      removed the required property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • info

      added the new optional request property

    • info

      added to the response body allOf list for the response status

    • info

      added to the response body allOf list for the response status

  • v514c297539b64Revision changes
    • warning

      removed the request property

    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status

    • warning

      added the new COLLAGE enum value to the / response property for the response status

    • warning

      added the new COLLAGE enum value to the / response property for the response status

    • warning

      added the new MAX_WIDTH_REGULAR_COLLECTION enum value to the / response property for the response status

    • warning

      added the new MAX_WIDTH_REGULAR_COLLECTION enum value to the / response property for the response status

    • warning

      added the new MAX_WIDTH_VIDEO_COLLECTION enum value to the / response property for the response status

    • warning

      added the new MAX_WIDTH_VIDEO_COLLECTION enum value to the / response property for the response status