---
title: "Create Pin"
method: POST
path: "/pins"
tags: ["pins"]
---

# Create Pin

`POST /pins`

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 <a href='/docs/add-ons/save-button'>Save button</a> instead. For more tips on creating fresh content for Pinterest, review our <a href='/docs/content/content-creation/'>Content App Solutions Guide</a>.

<strong><a href='/docs/content/content-creation/#Creating%20video%20Pins'>Learn more</a></strong> about video Pin creation.

## Query parameters

- `ad_account_id` string

## Request body

- PinCreate, nullable — Pin
  - `id` string
  - `created_at` string, date-time
  - `link` string, nullable
  - `title` string, nullable
  - `description` string, nullable
  - `dominant_color` string, nullable — Dominant pin color. Hex number, e.g. \"#6E7874\".
  - `alt_text` string, nullable
  - `board_id` string — The board to which this Pin belongs.
  - `board_section_id` string, nullable — The board section to which this Pin belongs.
  - `board_owner` BoardOwner
    - `username` string
  - `media` PinMedia — Pin media objects.
    - `media_type` string
  - `media_source` union — Pin media source.
    - PinMediaSourceImageBase64 — Base64-encoded image media source
      - `source_type` 'image_base64', required
      - `content_type` 'image/jpeg' | 'image/png', required
      - `data` string, required
      - `is_standard` boolean — Set the parameter to false to create the new simplified Pin instead of the standard pin. Currently the field is only available to a list of beta users.
    - PinMediaSourceImageURL — Image URL-based media source
      - `source_type` 'image_url', required
      - `url` string, required
      - `is_standard` boolean — Set the parameter to false to create the new simplified Pin instead of the standard pin. Currently the field is only available to a list of beta users.
    - PinMediaSourceVideoID — Video ID-based media source
      - `source_type` 'video_id', required
      - `cover_image_url` string — Cover image url.
      - `cover_image_content_type` 'image/jpeg' | 'image/png' — Content type for cover image Base64.
      - `cover_image_data` string — Cover image Base64.
      - `media_id` string, required
      - `is_standard` boolean — Set the parameter to false to create the new simplified Pin instead of the standard pin. Currently the field is only available to a list of beta users.
    - PinMediaSourceImagesBase64 — Multiple Base64-encoded images media source
      - `source_type` 'multiple_image_base64'
      - `items` object[], required — Array with image objects.
        - `title` string
        - `description` string
        - `link` string — Destination link for the image.
        - `content_type` 'image/jpeg' | 'image/png', required
        - `data` string, required — Image to upload as base64 string.
      - `index` integer
    - PinMediaSourceImagesURL — Multiple images urls-based media source
      - `source_type` 'multiple_image_urls'
      - `items` object[], required — Array with image objects.
        - `title` string
        - `description` string
        - `link` string — Destination link for the image.
        - `url` string, required — URL of image to upload.
      - `index` integer
    - PinMediaSourcePinURL — Pin URL-based media source for product pin creation. Currently the field is only available to a list of beta users.
      - `source_type` 'pin_url', required
      - `is_affiliate_link` boolean — This is an affiliate link or sponsored product. The FTC requires disclosure for paid partnerships and affiliate products.
  - `parent_pin_id` string, nullable — The source pin id if this pin was saved from another pin. <a href="https://help.pinterest.com/article/save-pins-on-pinterest">Learn more</a>.
  - `note` string, nullable — Private note for this Pin. <a href="https://help.pinterest.com/en/article/add-notes-to-your-pins">Learn more</a>.

## Response `201`

Successful pin creation.

- Pin, nullable — Pin
  - `id` string
  - `created_at` string, date-time
  - `link` string, nullable
  - `title` string, nullable
  - `description` string, nullable
  - `dominant_color` string, nullable — Dominant pin color. Hex number, e.g. \"#6E7874\".
  - `alt_text` string, nullable
  - `creative_type` 'REGULAR' | 'VIDEO' | 'SHOPPING' | 'CAROUSEL' | 'MAX_VIDEO' | 'SHOP_THE_PIN' | 'COLLECTION' | 'IDEA' | 'SHOWCASE' | 'QUIZ' — Ad creative type enum. </p><strong>Note:</strong> SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.
  - `board_id` string — The board to which this Pin belongs.
  - `board_section_id` string, nullable — The board section to which this Pin belongs.
  - `board_owner` BoardOwner
    - `username` string
  - `is_owner` boolean — Whether the "operation user_account" is the Pin owner.
  - `media` PinMedia — Pin media objects.
    - `media_type` string
  - `media_source` union — Pin media source.
    - PinMediaSourceImageBase64 — Base64-encoded image media source
      - `source_type` 'image_base64', required
      - `content_type` 'image/jpeg' | 'image/png', required
      - `data` string, required
      - `is_standard` boolean — Set the parameter to false to create the new simplified Pin instead of the standard pin. Currently the field is only available to a list of beta users.
    - PinMediaSourceImageURL — Image URL-based media source
      - `source_type` 'image_url', required
      - `url` string, required
      - `is_standard` boolean — Set the parameter to false to create the new simplified Pin instead of the standard pin. Currently the field is only available to a list of beta users.
    - PinMediaSourceVideoID — Video ID-based media source
      - `source_type` 'video_id', required
      - `cover_image_url` string — Cover image url.
      - `cover_image_content_type` 'image/jpeg' | 'image/png' — Content type for cover image Base64.
      - `cover_image_data` string — Cover image Base64.
      - `media_id` string, required
      - `is_standard` boolean — Set the parameter to false to create the new simplified Pin instead of the standard pin. Currently the field is only available to a list of beta users.
    - PinMediaSourceImagesBase64 — Multiple Base64-encoded images media source
      - `source_type` 'multiple_image_base64'
      - `items` object[], required — Array with image objects.
        - `title` string
        - `description` string
        - `link` string — Destination link for the image.
        - `content_type` 'image/jpeg' | 'image/png', required
        - `data` string, required — Image to upload as base64 string.
      - `index` integer
    - PinMediaSourceImagesURL — Multiple images urls-based media source
      - `source_type` 'multiple_image_urls'
      - `items` object[], required — Array with image objects.
        - `title` string
        - `description` string
        - `link` string — Destination link for the image.
        - `url` string, required — URL of image to upload.
      - `index` integer
    - PinMediaSourcePinURL — Pin URL-based media source for product pin creation. Currently the field is only available to a list of beta users.
      - `source_type` 'pin_url', required
      - `is_affiliate_link` boolean — This is an affiliate link or sponsored product. The FTC requires disclosure for paid partnerships and affiliate products.
  - `parent_pin_id` string, nullable — The source pin id if this pin was saved from another pin. <a href="https://help.pinterest.com/article/save-pins-on-pinterest">Learn more</a>.
  - `is_standard` boolean — Whether the Pin is standard or not. See documentation on <a href="https://developers.pinterest.com/docs/content/update/">Changes to Pin creation</a> for more information.
  - `has_been_promoted` boolean — Whether the Pin has been promoted or not.
  - `note` string, nullable — Private note for this Pin. <a href="https://help.pinterest.com/en/article/add-notes-to-your-pins">Learn more</a>.

## Other responses

- `400` — Invalid Pin parameters response
- `403` — The Pin's image is too small, too large or is broken
- `404` — Board or section not found
- `429` — This request exceeded a rate limit. This can happen if the client exceeds one of the published rate limits or if multiple write operations are applied to an object within a short time window.
- `default` — Unexpected error

## Changes

- **2023-08-17** (v5) `0ff12596bafd` — 2 info
  - added the new optional request property `media_source/allOf[subschema #1: Pin media source]/oneOf[subschema #6: Pin URL]/is_affiliate_link`
  - added the optional property `media_source/allOf[subschema #1: Pin media source]/oneOf[subschema #6: Pin URL]/is_affiliate_link` to the response with the `201` status
- **2023-07-14** (v5) `52586a274771` — 2 breaking, 15 info
  - the response property `media_source/allOf[subschema #1: Pin media source]/oneOf[subschema #3: Video ID]/cover_image_url` became optional for the status `201`
  - added `#/components/schemas/PinMediaSourcePinURL` to the `media_source/allOf[subschema #1: Pin media source]/` response property `oneOf` list for the response status `201`
  - added the new optional request property `media_source/allOf[subschema #1: Pin media source]/oneOf[subschema #3: Video ID]/cover_image_content_type`
  - added the new optional request property `media_source/allOf[subschema #1: Pin media source]/oneOf[subschema #3: Video ID]/cover_image_data`
  - …13 more
- …earlier changes not shown

[Full history](https://skmtc.dev/pinterest/apis/pinterest-rest-api/changes/pins/post.md)

---

[API](https://skmtc.dev/pinterest/apis/pinterest-rest-api.md) · [All operations](https://skmtc.dev/pinterest/apis/pinterest-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pinterest/pinterest-rest-api/revisions/0ff12596bafd/schema)