​
Posting an Image Pin to Pinterest

Pinterest requires an image to be included in the post. Other parameters are optional. Please see Pinterest Media Guidelines and Pinterest Authorization for more information.

  • post: The description of the pin. Maximum 500 characters.*

  • title: The title of the pin to display. This appears in the “Add your title” section of a new pin. Maximum 100 characters.

  • link: The destination URL that users will be directed to when they click on your pin image. This creates a clickable link attached to your pin. Maximum length is 2048 characters.

  • boardId: Post to another one of the user’s Pinterest Boards by specifying the ID obtained from the /user/details endpoint. Otherwise post to the default linked board.

  • note: You can add private notes to individual Pins on your boards. Only you and board collaborators will be able to see them.

*Links in the post field are not clickable. Please use the link field to add a clickable link to the Pin.

Pinterest Post
{
  "post": "The best Pinterest API ever!", // Maximum 500 characters
  "platforms": ["pinterest"],
  "mediaUrls": ["https://images.ayrshare.com/imgs/GhostBusters.jpg"],
  "pinterestOptions": {
    "title": "A Pinterest Board for You", // optional, maximum 100 characters
    "link": "https://www.ayrshare.com", // optional, maximum 2048 characters
    "boardId": "93383204522" // optional
  }
}

See Pinterest Media Guidelines for more information.

​
Posting a Video Pin to Pinterest

A video may be posted as a Pin using the standard mediaUrls field in the /post endpoint.Additionally, a thumbnail image URL **must be included** with the video with a valid media Content-Type such asimage/jpeg`. Please see requirements.

Pinterest Video Thumbnail
{
  "pinterestOptions": {
    // required
    "thumbNail": "https://images.unsplash.com/photo-1513093496871-0a81425386e5?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=MnwxNjQ1ODN8MHwxfHJhbmRvbXx8fHx8fHx8fDE2Mzg0ODAzNDA&ixlib=rb-1.2.1&q=80&w=400"
  }
}

Additional information on posting Pins using the API.

If your video doesn’t end in a known video extension such as mp4, please use the isVideo parameter. See the /post endpoint for details.

Post up to five images as a Pinterest carousel. By adding more than one media URL, a carousel is automatically created. You can also add in optional carousel parameter. Please see below.

Pinterest Carousel Post
{
  "post": "Carousel Time",
  "platforms": ["pinterest"],
  "mediaUrls": [
    "https://img.ayrshare.com/random/photo-1.jpg",
    "https://img.ayrshare.com/random/photo-2.jpg"
  ],
  "pinterestOptions": {
    "carouselOptions": [
      // optional
      {
        "title": "Image 1",
        "link": "https://www.cnn.com",
        "description": "Super Image 1"
      },
      {
        "title": "Image 2",
        "link": "https://www.google.com",
        "description": "Super Image 2"
      }
    ]
  }
}

The optional carouselOptions field takes an array of objects. Each carousel object corresponds to the equivalent media URL string, e.g. the first carousel object refers to the first mediaUrl string.

  • title: The image title.
  • link: The external destination link for the image.
  • description: The image description.

​
Alternative Text

Add alternative text, also known as alt text, to a Pinterest image or video. Pinterest alt text is an accessibility feature used for additional user info and screen readers.

Use the altText in the pinterestOptions object.

Pinterest Alt Text
{
  "pinterestOptions": {
    "altText": ["This is my best pic", "😃 here is the next one"]
  }
}

The alt text is limited to 500 characters.

​
Pinterest Mentions

While you can add a @handle to a Pinterest post, Pinterest does not support resolving mentions in the post text. The @handle will remain as plain text.