Docs/API Reference/Pinterest

Pinterest API

Use the Crosspostify API to create image and video Pins on Pinterest — with full title, description, and board targeting support.

Post Types

Image Pin · Video Pin

Board Targeting

Required per Pin

Title

Supported

Unique Endpoint

/pinterest-boards

Pinterest is a visual discovery platform where content lives as Pins organized into Boards. The Crosspostify Pinterest API integration lets you programmatically create image and video Pins to any board on your account — with full title, description, and board targeting.

Pinterest is unique among Crosspostify-supported platforms in that every Pin must be assigned to a specific board. Use the GET /pinterest-boards/{accountId} endpoint to fetch your boards and their IDs before creating Pins.

This page covers everything specific to Pinterest when using the Crosspostify API. For general authentication, rate limits, and error handling, see the full API Reference.

Pinterest-Specific Parameters

Pinterest has one exclusive parameter — boardId — which is required for every Pin. This is the only platform on Crosspostify that requires content to be assigned to a specific destination before posting.

accountId✓ AppliesRequired. Your Pinterest account ID from /social-accounts.

title✓ AppliesThe Pin title. Shown above the description on the Pin detail page. Max 100 characters.

caption✓ AppliesThe Pin description. Helps with Pinterest search and SEO. Max 500 characters.

boardId✓ AppliesPinterest exclusive. Required. The board to save this Pin to. Fetch board IDs from GET /pinterest-boards/{accountId}.

is_aigc✗ IgnoredTikTok only — ignored for Pinterest.

facebookFirstComment✗ IgnoredFacebook only — ignored for Pinterest.

textFormatPresetId✗ IgnoredFacebook only — ignored for Pinterest.

privacy✗ IgnoredYouTube only — Pinterest pins inherit board privacy settings.

categoryId✗ IgnoredYouTube only — ignored for Pinterest.

tags✗ IgnoredYouTube only — use keywords in title and caption instead.

boardId is required for every Pin

Unlike other platforms where posts go to a general feed, every Pinterest Pin must be saved to a specific board. Always fetch your board IDs first using GET /pinterest-boards/{accountId} and store them for reuse.

Supported Endpoints

Pinterest supports image and video Pins, plus a dedicated endpoint for fetching your boards:

No text-only or carousel Pins

Pinterest does not support text-only posts or multi-image carousels via the API. Every Pin requires a media attachment — either an image or a video.

POST/post/imageImage Pin

Create an image Pin on a Pinterest board. Image Pins are the core Pinterest format — vertical images (2:3 ratio) perform best in the Pinterest feed.

Image Pin Notes

Vertical images (2:3 ratio, 1000×1500px) take up more feed space and get more clicks
title is shown prominently on the Pin detail page — make it keyword-rich
caption maps to the Pin description — include relevant keywords for Pinterest SEO
boardId is required — fetch your board IDs from GET /pinterest-boards/{accountId}
Upload your image first via POST /media and use the returned mediaId
All datetime values must be in UTC timezone (ISO 8601 format with Z suffix)

Request Body

mediaIdstringrequired

The ID of the uploaded image file. Obtain this from POST /media.

scheduledDatestringoptional

Schedule the Pin for a future time (ISO 8601 with 'Z' suffix). Omit to post immediately.

postsarrayrequired

Array of post objects. Include one object per Pinterest account.

posts[].accountIdstringrequired

The Pinterest account ID. Retrieve from GET /social-accounts.

posts[].boardIdstringrequired

The board to save this Pin to. Retrieve board IDs from GET /pinterest-boards/{accountId}.

posts[].titlestringoptional

The Pin title. Shown on the Pin detail page. Keyword-rich titles improve Pinterest SEO. Max 100 characters.

posts[].captionstringoptional

The Pin description. Supports plain text and keywords. Max 500 characters.

Response

{ "success": true, "data": { "postId": "post_pin_001", "status": "SCHEDULED", "scheduledDate": "2025-06-01T14:00:00Z", "accounts": [ { "accountId": "acc_pinterest_789", "platform": "pinterest", "boardId": "board_living_room_456", "status": "SCHEDULED" } ] } }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/image" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "img_12345",
    "scheduledDate": "2025-06-01T14:00:00Z",
    "posts": [
      {
        "accountId": "acc_pinterest_789",
        "title": "10 Minimalist Living Room Ideas for 2025",
        "caption": "Transform your living space with these clean, modern design ideas. Perfect for small apartments and open-plan homes.",
        "boardId": "board_living_room_456"
      }
    ]
  }'

POST/post/videoVideo Pin

Create a video Pin on a Pinterest board. Video Pins autoplay silently in the feed and are excellent for tutorials, recipes, and product demos.

Video Pin Notes

Video Pins autoplay silently in the feed — design for no-sound viewing
Vertical video (2:3 or 9:16) takes up more feed space and performs better
boardId is required — same as image Pins
Pinterest generates a thumbnail from the first frame — start with a strong visual
Upload your video first via POST /media and use the returned mediaId
All datetime values must be in UTC timezone (ISO 8601 format with Z suffix)

Request Body

mediaIdstringrequired

The ID of the uploaded video file. Obtain this from POST /media.

scheduledDatestringoptional

Schedule the Pin for a future time (ISO 8601 with 'Z' suffix). Omit to post immediately.

postsarrayrequired

Array of post objects. Include one object per Pinterest account.

posts[].accountIdstringrequired

The Pinterest account ID. Retrieve from GET /social-accounts.

posts[].boardIdstringrequired

The board to save this Pin to. Retrieve board IDs from GET /pinterest-boards/{accountId}.

posts[].titlestringoptional

The Pin title. Shown on the Pin detail page. Max 100 characters.

posts[].captionstringoptional

The Pin description. Supports plain text and keywords. Max 500 characters.

Response

{ "success": true, "data": { "postId": "post_pin_002", "status": "PROCESSING", "scheduledDate": "2025-06-01T14:00:00Z", "videoDuration": 62, "accounts": [ { "accountId": "acc_pinterest_789", "platform": "pinterest", "boardId": "board_recipes_123", "status": "PROCESSING" } ] } }

Code Example

curl -X POST "https://v1.api.crosspostify.com/post/video" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaId": "vid_12345",
    "scheduledDate": "2025-06-01T14:00:00Z",
    "posts": [
      {
        "accountId": "acc_pinterest_789",
        "title": "Easy 15-Minute Pasta Recipe",
        "caption": "This creamy garlic pasta comes together in just 15 minutes with pantry staples. Save this Pin for your next weeknight dinner!",
        "boardId": "board_recipes_123"
      }
    ]
  }'

GET/pinterest-boards/{accountId}

Fetch all boards for a connected Pinterest account. Use the returned boardId values when creating Pins. This is a Pinterest-exclusive endpoint not available for other platforms.

Fetching Boards

Replace {accountId} in the URL with the Pinterest account ID from GET /social-accounts
Returns all boards including secret boards visible to the authenticated user
Cache board IDs on your end — they don't change unless a board is deleted or renamed
Board IDs are stable — safe to store and reuse across multiple Pin creation requests

Path Parameters

accountIdstringrequired

The Pinterest account ID. Retrieve from GET /social-accounts.

Response

{ "success": true, "data": { "accountId": "acc_pinterest_789", "boards": [ { "boardId": "board_living_room_456", "name": "Living Room Inspiration", "description": "Modern and minimalist living room ideas", "pinCount": 142, "isSecret": false }, { "boardId": "board_recipes_123", "name": "Quick Weeknight Recipes", "description": "Meals ready in 30 minutes or less", "pinCount": 87, "isSecret": false }, { "boardId": "board_drafts_999", "name": "Drafts", "description": "", "pinCount": 12, "isSecret": true } ] } }

Code Example

curl -X GET "https://v1.api.crosspostify.com/pinterest-boards/acc_pinterest_789" \
  -H "X-API-Key: your_api_key_here"

Boards

Pinterest Boards are the organizational unit of Pinterest. Every Pin must belong to a board. Boards can be public or secret, and are managed directly in Pinterest — not via the Crosspostify API.

Public Boards

Visible to all Pinterest users
Pins appear in Pinterest search and recommendations
Best for content you want to be discovered
Returned in GET /pinterest-boards with isSecret: false

Secret Boards

Only visible to you and invited collaborators
Pins do not appear in search or recommendations
Useful for drafts, staging, or private collections
Returned in GET /pinterest-boards with isSecret: true

Pin to multiple boards in one call

You can include multiple entries in the posts array — each with a different boardId — to save the same Pin to multiple boards simultaneously in a single API call.

Content Guidelines

Pinterest is a visual search engine as much as a social platform. Optimizing your Pins for search and visual appeal is key to long-term discoverability.

Image Pin Requirements

Format: JPG or PNG
Recommended ratio: 2:3 (1000×1500px)
Square (1:1) and 4:5 also supported
Max file size: 20MB
Min width: 200px
Vertical images get more feed real estate

Video Pin Requirements

Format: MP4 recommended
Recommended ratio: 2:3 or 9:16 (vertical)
Square (1:1) also supported
Max duration: 15 minutes
Min duration: 4 seconds
Videos autoplay silently — design for mute

Pinterest SEO Tips

Title: max 100 chars — lead with keywords
Description: max 500 chars — use natural language
Pinterest is a search engine — keywords matter
Pins have a long shelf life (months to years)
Board name and description also affect SEO
Consistent pinning beats sporadic bulk posting

Scheduling

Minimum lead time: ~10 minutes ahead
All times must be UTC (ISO 8601 + Z)
Omit scheduledDate to post immediately
Best times: evenings and weekends
Pinterest content resurfaces over time — evergreen content wins