---
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 [Save button](/docs/web-features/add-ons-overview/) instead. For more tips on creating fresh content for Pinterest, review our [Content App Solutions Guide](/docs/api-features/content-overview/).

**[Learn more](/docs/api-features/creating-boards-and-pins/#creating-video-pins)** about video Pin creation.

**[Learn more](/docs/api-features/creating-boards-and-pins/#creating-image-pins)** about image Pin creation.

## Query parameters

- `ad_account_id` string

## Request body

- PinCreate — Resource create operation model.
  - `ai_disclosures` AiDisclosures — AI disclosure declarations the creator has made about the Pin.
    - `values` AiDisclosureItem[], required — List of AI disclosure declarations the creator has made about this Pin.
  - `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.
  - `description` string, nullable
  - `dominant_color` string, nullable — Dominant pin color. Hex number, e.g. `#6E7874`.
  - `link` string, nullable
  - `media_source` union — Pin media source that can be an image, video, or a mix of both passed in as a request.
    - object — Image Base64-based media source.
      - `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.
      - `source_type` 'image_base64', required — The source type of the media.
    - object — Image URL-based media source.
      - `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.
      - `source_type` 'image_url', required — The source type of the media.
      - `url` string, required
    - object — Video ID-based media source.
      - `cover_image_content_type` 'image/jpeg' | 'image/png'
      - `cover_image_data` string — Cover image Base64.
      - `cover_image_key_frame_time` integer — Keyframe timestamp for cover image (seconds). If entered time exceeds video duration, the last frame is used.
      - `cover_image_url` string — Cover image URL.
      - `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.
      - `media_id` string, required
      - `source_type` 'video_id', required
    - object — Multiple Base64-based images media source
      - `index` integer
      - `items` PinMediaSourceImagesBase64Item[], required — Array with image objects.
        - `content_type` 'image/jpeg' | 'image/png', required
        - `data` string, required
        - `description` string
        - `link` string
        - `title` string
      - `source_type` 'multiple_image_base64', required — The source type of the media.
    - object — Multiple URL-based images media source
      - `index` integer
      - `items` PinMediaSourceImagesURLItem[], required — Array with image objects.
        - `description` string
        - `link` string
        - `title` string
        - `url` string, required
      - `source_type` 'multiple_image_urls', required — The source type of the media.
    - object — Pin URL-based media source for product pin creation. Currently the field is only available to a list of beta users.
      - `is_affiliate_link` boolean — This is an affiliate link or sponsored product. The FTC requires disclosure for paid partnerships and affiliate products.
      - `source_type` 'pin_url', required
  - `parent_pin_id` string, nullable — The source pin id if this pin was saved from another pin. [Learn more](https://help.pinterest.com/article/save-pins-on-pinterest).
  - `sponsor_id` string, 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.
  - `title` string, nullable

## Response `200`

The request has succeeded.

- Pin
  - `ai_disclosures` AiDisclosures — AI disclosure declarations the creator has made about the Pin.
    - `values` AiDisclosureItem[], required — List of AI disclosure declarations the creator has made about this Pin.
  - `board_id` string — The board to which this Pin belongs.
  - `board_owner` BoardOwner
    - `username` string
  - `board_section_id` string, nullable — The board section to which this Pin belongs.
  - `created_at` string, 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_color` string, nullable — Dominant pin color. Hex number, e.g. `#6E7874`.
  - `has_been_promoted` boolean — Whether the Pin has been promoted or not.
  - `id` string, required
  - `is_owner` boolean — Whether the "operation user_account" is the Pin owner.
  - `is_product` boolean — Whether the Pin is a product Pin.
  - `is_standard` boolean — Whether the Pin is standard or not. See documentation on [Changes to Pin creation](/docs/api-features/content-overview/) for more information.
  - `media` union — Pin media that can be an image, video, or a mix of both.
    - object — Pin with image.
      - `images` ImageSize
        - `1200x` ImageDetails
          - `height` integer, nullable, required
          - `url` string, required
          - `width` integer, nullable, required
        - `150x150` ImageDetails
          - `height` integer, nullable, required
          - `url` string, required
          - `width` integer, nullable, required
        - `400x300` ImageDetails
          - `height` integer, nullable, required
          - `url` string, required
          - `width` integer, nullable, required
        - `600x` ImageDetails
          - `height` integer, nullable, required
          - `url` string, required
          - `width` integer, nullable, required
      - `media_type` 'image', required
    - object — Pin with video.
      - `cover_image_url` string
      - `duration` number, nullable — Duration (in miliseconds). Field maybe null after creation due to video processing time.
      - `height` integer, nullable — Height (in pixels). Field maybe null after creation due to video processing time.
      - `images` ImageSize
        - `1200x` ImageDetails
          - `height` integer, nullable, required
          - `url` string, required
          - `width` integer, nullable, required
        - `150x150` ImageDetails
          - `height` integer, nullable, required
          - `url` string, required
          - `width` integer, nullable, required
        - `400x300` ImageDetails
          - `height` integer, nullable, required
          - `url` string, required
          - `width` integer, nullable, required
        - `600x` ImageDetails
          - `height` integer, nullable, required
          - `url` string, required
          - `width` integer, nullable, required
      - `media_type` 'video', required
      - `video_url` string, nullable — Video url (720p). **Note:** This field is limited and not available to all apps.
      - `video_url_hls` string, nullable — Video url (HLS). **Note:** This field is limited and not available to all apps.
      - `width` integer, nullable — Width (in pixels). Field maybe null after creation due to video processing time.
    - object — Pin with multiple images.
      - `items` ImageMetadata[]
        - `description` string, nullable
        - `images` ImageSize
          - `1200x` ImageDetails
            - `height` integer, nullable, required
            - `url` string, required
            - `width` integer, nullable, required
          - `150x150` ImageDetails
            - `height` integer, nullable, required
            - `url` string, required
            - `width` integer, nullable, required
          - `400x300` ImageDetails
            - `height` integer, nullable, required
            - `url` string, required
            - `width` integer, nullable, required
          - `600x` ImageDetails
            - `height` integer, nullable, required
            - `url` string, required
            - `width` integer, nullable, required
        - `item_type` 'image', required — Discriminator literal identifying this as image metadata inside a `PinMediaMetadata` payload.
        - `link` string, nullable
        - `title` string, nullable
      - `media_type` 'multiple_images', required
    - object — Pin with multiple videos.
      - `items` VideoMetadataWithItemType[]
        - `cover_image_url` string
        - `duration` number, nullable — Duration (in miliseconds). Field maybe null after creation due to video processing time.
        - `height` integer, nullable — Height (in pixels). Field maybe null after creation due to video processing time.
        - `item_type` 'video', required — Discriminator literal identifying this as video metadata inside a `PinMediaMetadata` payload.
        - `video_url` string, nullable — Video url (720p). **Note:** This field is limited and not available to all apps.
        - `video_url_hls` string, nullable — Video url (HLS). **Note:** This field is limited and not available to all apps.
        - `width` integer, nullable — Width (in pixels). Field maybe null after creation due to video processing time.
      - `media_type` 'multiple_videos', required
    - object — Pin with a mix of images and videos.
      - `items` PinMediaMetadata[]
        - union — Per-item entry inside `PinMedia.items` for mixed image/video pins. Discriminated by `item_type`.
          - object
            - `description` string, nullable
            - `images` ImageSize
              - …
            - `item_type` 'image', required — Discriminator literal identifying this as image metadata inside a `PinMediaMetadata` payload.
            - `link` string, nullable
            - `title` string, nullable
          - object
            - `cover_image_url` string
            - `duration` number, nullable — Duration (in miliseconds). Field maybe null after creation due to video processing time.
            - `height` integer, nullable — Height (in pixels). Field maybe null after creation due to video processing time.
            - `item_type` 'video', required — Discriminator literal identifying this as video metadata inside a `PinMediaMetadata` payload.
            - `video_url` string, nullable — Video url (720p). **Note:** This field is limited and not available to all apps.
            - `video_url_hls` string, nullable — Video url (HLS). **Note:** This field is limited and not available to all apps.
            - `width` integer, nullable — Width (in pixels). Field maybe null after creation due to video processing time.
      - `media_type` 'multiple_mixed', required
  - `parent_pin_id` string, nullable — The source pin id if this pin was saved from another pin. [Learn more](https://help.pinterest.com/article/save-pins-on-pinterest).
  - `pin_metrics` object, nullable — Pin metrics with associated time intervals if any.

## Other responses

- `201` — Resource create operation completed successfully.
- `400` — The request could not be understood by the server due to unexpected data.
- `401` — Authentication is required and has either failed or not been provided.
- `403` — The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
- `404` — The requested resource could not be found on this server.
- `429` — The user has sent too many requests in a given amount of time and is being rate limited.
- `default` — An unexpected error response.

---

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