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
  }'

import PostPeer from '@postpeer/node';

const client = new PostPeer();
const { data } = await client.posts.create({
	body: {
		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,
	},
});

from postpeer import PostPeer

with PostPeer() as client:
    post = client.posts.create(
        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",
                },
            },
        ],
        media_items=[
            {"type": "image", "url": "https://cdn.example.com/pin-image.jpg"},
        ],
        publish_now=True,
    )

Response:

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

Platform-Specific Data

Pass this object in platformSpecificData when posting to Pinterest.

Field	Type	Required	Values and constraints	Description
`boardId`	string	Yes	—	Target board ID. Retrieve available boards via GET /v1/pinterest/boards.
`title`	string	No	Length: 0–100	Pin title. Max 100 characters. Defaults to first line of content.
`link`	string	No	Format: `uri`	HTTPS destination URL when the pin is clicked. Important for driving traffic.
`altText`	string	No	Length: 0–500	Accessible image description. Max 500 characters.
`dominantColor`	string	No	—	Hex color for the loading placeholder (e.g. "#6E7874").
`coverImageUrl`	string	No	Format: `uri`	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