Skip to main content

​
Overview

Postiz integrates with Pinterest to create pins on your boards, supporting images, videos, and multi-image carousels with comprehensive analytics.
Pinterest requires at least one media attachment. For video pins, you must provide both a video file AND a cover image (2 attachments total).

​
Authentication

Pinterest uses OAuth 2.0 with refresh tokens.
1

Connect Pinterest

Click “Connect Pinterest” in Integrations
2

Authorize

Grant all requested permissions
3

Select Boards

Choose which boards to post to when creating pins

​
Required Permissions

  • boards:read - Read board information
  • boards:write - Create boards
  • pins:read - Read pin data
  • pins:write - Create pins
  • user_accounts:read - Access user info

​
Supported Features

​
Pin Types

Single Image:
  • One image per pin
  • Title (optional)
  • Description (500 chars)
  • Link (optional)
  • Board selection required
Image Carousel:
  • Multiple images in one pin
  • Swipeable gallery format
  • Same title/description for all

​
Pin Settings

Optional pin title for better discovery:
{
  title: "Your Pin Title"
}
Set accent color for pin:
{
  dominant_color: "#FF5722"
}
Required - choose which board:
{
  board: "board_id_12345"
}

​
Media Handling

​
Image Pins

Images are referenced by URL: 
{
  media_source: {
    source_type: "image_url",
    url: "https://example.com/image.jpg"
  }
}

​
Video Pins

Video upload is a multi-step process:
1

Initialize Upload

Request upload URL and credentials
2

Upload Video

Upload video file using FormData with upload parameters
3

Monitor Processing

Poll media status every 30 seconds until “succeeded”
4

Create Pin

Create pin with video media_id and cover image URL
{
  media_source: {
    source_type: "video_id",
    media_id: "v123456",
    cover_image_url: "https://example.com/cover.jpg"
  }
}
Video pins require BOTH video and cover image. Error cover_image_url or cover_image_content_type means cover image is missing.

​
Board Management

List available boards: 
GET /boards

Returns:
[
  {
    id: "123456789",
    name: "My Inspiration Board"
  },
  {
    id: "987654321",
    name: "Travel Ideas"
  }
]
Boards are created in Pinterest - Postiz doesn’t create boards.

​
Analytics

​
Account-Level Analytics

Track overall performance over time:
  • Pin Click Rate: CTR percentage
  • Impressions: Total pin views
  • Pin Clicks: Click-throughs
  • Engagement: Saves, clicks, etc.
  • Saves: Pin saves to boards
Data broken down by day.

​
Pin-Level Analytics

Detailed metrics per pin (lifetime):
  • Impressions: Total views
  • Pin Clicks: Clicks on pin
  • Outbound Clicks: Clicks to destination URL
  • Saves: Times saved to boards
{
  "label": "Impressions",
  "percentageChange": 0,
  "data": [
    {
      "total": "1523",
      "date": "2024-03-15"
    }
  ]
}
Pin analytics use a 2-year lookback period to capture lifetime metrics for older pins.

​
Rate Limits

Pinterest Rate Limits:
  • 3 concurrent posting jobs
  • Generous API limits
  • No strict daily pin limits
  • Video processing adds time

​
Best Practices

Image Size

Use 1000x1500px (2:3 ratio) for optimal display

Description Length

Use full 500 characters with keywords for SEO

Pin to Relevant Boards

Choose boards that match your content theme

Add Links

Pins with links drive 3x more traffic

​
Troubleshooting

For video pins:
  • Must provide exactly 2 attachments
  • First attachment: video (MP4)
  • Second attachment: cover image (JPG/PNG)
  • Cover image shows before video plays
If video processing doesn’t complete:
  • Check video format is MP4
  • Verify file size isn’t too large
  • Processing can take 5-10 minutes
  • If stuck over 30 minutes, retry
If board isn’t listed:
  • Create board in Pinterest first
  • Refresh integration
  • Verify board permissions
  • Check board isn’t deleted
Analytics issues:
  • New pins need 24-48 hours for data
  • Check date range covers pin creation
  • Some metrics may be zero initially
  • API may have temporary delays

Build docs developers (and LLMs) love

Get started for freeTalk to us