​
Posting an Image Pin to Pinterest

Pinterest requires an image to be included in the post. Other parameters are optional.

  • 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.