​
Posting an Image Pin to Pinterest

The Pinterest API requires an image to be included in the post. Other parameters are optional. Please see Pinterest Media Guidelines and Pinterest Authorization for more information.
Pinterest Post
{
  "post": "The best Pinterest API ever!", // Maximum 500 characters or empty string
  "platforms": ["pinterest"],
  "mediaUrls": ["https://images.ayrshare.com/imgs/GhostBusters.jpg"]
}

​
Pinterest Options

You can set additional options for a post by using the pinterestOptions parameter.
Pinterest Post
{
  "post": "The best Pinterest API ever!", // Maximum 500 characters or empty string
  "platforms": ["pinterest"],
  "mediaUrls": ["https://images.ayrshare.com/imgs/GhostBusters.jpg"],
  "pinterestOptions": {
    "altText": ["This is my best pic", "😃 here is the next one"], // maximum 500 characters
    "boardId": "93383204522",
    "carouselOptions": [
      {
        "title": "Image 1",
        "link": "https://www.cnn.com",
        "description": "Super Image 1"
      },
      {
        "title": "Image 2",
        "link": "https://www.google.com",
        "description": "Super Image 2"
      }
    ],
    "link": "https://www.ayrshare.com", // maximum 2048 characters
    "note": "Private note", // maximum 1000 characters
    "thumbNail": "https://images.ayrshare.com/imgs/GhostBusters.jpg",
    "title": "A Pinterest Board for You" // maximum 100 characters
  }
}
Pinterest options are optional fields that can be used to control the post.
​
altText
array of strings
The alternative text for images and videos for accessibility and screen readers. Maximum 500 characters.See Pinterest Alternative Text for more information.
​
boardId
string
Post to another one of the user’s Pinterest Boards by specifying the ID from the /user/details endpoint.If not specified, posts to the default linked board.See Pinterest Board ID for more information.
​
carouselOptions
array of objects
Add up to 5 images as a Pinterest carousel with optional titles, links, and descriptions.Each object can contain: title, link, and description.See Pinterest Image Carousel for more information.
​
link
string
The destination URL users will be directed to when clicking the pin image. Maximum 2048 characters.Creates a clickable link attached to your pin.See Pin Link for more information.
​
note
string
Add private notes to individual Pins that only you and board collaborators can see. Maximum 1000 characters.See Pin Note for more information.
​
thumbNail
string
Set a thumbnail for video pins. Must be PNG or JPG, same dimensions as video, under 10MB.Required for video pins.See Video Pin (Thumbnail) for more information.
​
title
string
The title of the pin to display in the “Add your title” section. Maximum 100 characters.See Pin Title for more information.
*Links in the post field are not clickable. Please use the link field to add a clickable link to the Pin. See Pinterest Media Guidelines for more information.

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

​
Board ID

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. Use the boardId in the pinterestOptions object.
Pinterest Board ID
{
  "pinterestOptions": {
    "boardId": "93383204522"
  }
}

​
Character Limits

Please see Pinterest Character Limits for more information. 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. Use the link in the pinterestOptions object.
Pin Link
{
  "pinterestOptions": {
    "link": "https://www.ayrshare.com"
  }
}

​
Pin Note

You can add private notes to individual Pins on your boards. Only you and board collaborators will be able to see them. Use the note in the pinterestOptions object.
Pin Note
{
  "pinterestOptions": {
    "note": "Private note for collaborators"
  }
}
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.

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

​
Pin Title

The title of the pin to display. This appears in the “Add your title” section of a new pin. Maximum 100 characters. Use the title in the pinterestOptions object.
Pin Title
{
  "pinterestOptions": {
    "title": "A Pinterest Board for You"
  }
}

​
Video Pin (Thumbnail)

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 as image/jpeg. Please see requirements.
Video Pin with 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.