Pinterest

Overview

Create pins with images or videos, target specific boards, and drive traffic with link attribution. PostPeer handles Pinterest's API and OAuth.

Quick Start

1. Connect a Pinterest Account

curl https://api.postpeer.dev/v1/connect/pinterest \
  -H "x-access-key: YOUR_API_KEY"

Returns a Pinterest OAuth URL. The user authorizes pin creation and board access permissions. See Connect Accounts for the full OAuth flow.

2. List Boards

Pinterest requires a target board for every pin. Fetch the user's boards to let them choose:

curl "https://api.postpeer.dev/v1/pinterest/boards?accountId=your-pinterest-account-id" \
  -H "x-access-key: YOUR_API_KEY"

The accountId parameter is optional. If omitted, boards are returned for the first connected Pinterest account. If you have multiple Pinterest accounts, pass the integration ID to specify which one.

Response:

{
  "success": true,
  "boards": [
    {
      "id": "596867825554313696",
      "name": "Hair",
      "description": "",
      "privacy": "PUBLIC"
    },
    {
      "id": "733523926748495119",
      "name": "Home interior design",
      "description": "",
      "privacy": "PUBLIC"
    }
  ]
}

Use the id field as the boardId in platformSpecificData when creating a pin.

3. Create a Pin

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "10 design tips for modern landing pages",
    "platforms": [
      {
        "platform": "pinterest",
        "accountId": "your-account-id",
        "platformSpecificData": {
          "boardId": "1143210755351402924",
          "title": "10 Design Tips",
          "link": "https://example.com/design-tips"
        }
      }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://cdn.example.com/pin-image.jpg" }
    ],
    "publishNow": true
  }'

Response:

{
  "success": true,
  "status": "published",
  "postId": "post_vwx234",
  "platforms": [
    {
      "platform": "pinterest",
      "success": true,
      "platformPostUrl": "https://www.pinterest.com/pin/98765/"
    }
  ]
}

Platform-Specific Data

Field	Type	Required	Description
`boardId`	string	Yes	Target board ID.
`title`	string	No	Pin title, max 100 characters. Defaults to first line of content.
`link`	string	No	HTTPS destination URL when the pin is clicked. Important for driving traffic.
`altText`	string	No	Accessible image description, max 500 characters.
`dominantColor`	string	No	Hex color for loading placeholder (e.g. `"#6E7874"`).
`coverImageUrl`	string	No	Custom cover image URL for video pins.

Media Requirements

Type	Formats	Recommended Size	Max Size
Image	JPG, PNG, WebP	1000x1500px (2:3 ratio)	32 MB
Video	MP4, MOV	1080p	2 GB

Pinterest requires exactly one media item per pin (1 image or 1 video). No carousels or multi-image posts.

Constraints

Description: max 500 characters (from content field)
Title: max 100 characters
Link: must use HTTPS
Media: publicly accessible URL required
Text-only pins are not supported — at least one image or video is required

Cross-Post

Post an image to Pinterest and LinkedIn in a single request:

curl -X POST "https://api.postpeer.dev/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Beautiful design inspiration",
    "platforms": [
      {
        "platform": "pinterest",
        "accountId": "pin_111",
        "platformSpecificData": {
          "boardId": "1143210755351402924",
          "link": "https://example.com"
        }
      },
      { "platform": "linkedin", "accountId": "li_456" }
    ],
    "mediaItems": [
      { "type": "image", "url": "https://cdn.example.com/image.jpg" }
    ],
    "publishNow": true
  }'

On this page