Skip to content

Create Pin API for Pinterest

The Create Pin API lets you create and publish pins with images or videos, target specific Pinterest boards, and drive traffic with link attribution. The API handles Pinterest's API and OAuth flow, so your application works with a board identifier and a single media item rather than managing platform authorization directly.

Overview

This guide covers publishing a pin built from a single image or video, choosing the destination board, and attaching a destination link so clicks can send readers onward. Authorization and the underlying Pinterest integration are handled by the API, leaving your code to supply the board identifier, the one media asset, and the pin metadata described below.

Quick Start

The workflow has three steps. First connect a Pinterest account and complete the authorization returned by the connect endpoint. Then list Pinterest boards so the user can choose a destination. Finally create the pin by passing the selected board's id as boardId inside platformSpecificData, together with exactly one entry in mediaItems and publishNow set to true for immediate publication.

1. Connect a Pinterest Account

Call GET {{API_BASE_URL}}/v1/connect/pinterest with the x-access-key header. The endpoint hands back a Pinterest OAuth URL for the account holder to approve. That approval covers creating pins and accessing boards. For the full OAuth flow, see the proposed Connect Accounts documentation linked below. Failure check: if no OAuth URL is returned, do not proceed to board listing or pin creation, because the account is not yet authorized for pin creation and board access.

2. List Boards

Every pin needs a destination board, so retrieve the available boards first. Call GET {{API_BASE_URL}}/v1/pinterest/boards with the x-access-key header. Supplying accountId is optional: leave it out and the response covers the earliest connected Pinterest account, while passing an integration ID selects a particular account when several are connected. Copy the chosen board's id into boardId within platformSpecificData for the create request. Failure check: if the boards list is empty or the chosen id is not present, stop and resolve the account selection before attempting to create a pin.

3. Create a Pin

Create the pin with POST {{API_BASE_URL}}/v1/posts. Send content, a platforms array containing platform pinterest with accountId and platformSpecificData, a mediaItems array with exactly one image or video, and publishNow true. In platformSpecificData, boardId is required, title and link are optional, and the other fields described below can be added when needed. After a successful request, read status, postId, and the Pinterest entry's platformPostUrl from the response to confirm publication and obtain the live pin URL. Failure check: verify that the response reports success for the Pinterest platform and that platformPostUrl is present before treating the pin as published.

Platform-Specific Data

Pass the Pinterest-specific object in platformSpecificData when posting to Pinterest. The boardId field is a required string identifying the target board, retrieved via GET /v1/pinterest/boards. The title field is an optional string of length 0-100 that defaults to the first line of content. The link field is an optional string in uri format and should be an HTTPS destination URL when the pin is clicked, which is important for driving traffic. The altText field is an optional string of length 0-500 providing an accessible image description. The dominantColor field is an optional string holding a hex color for the loading placeholder, such as #6E7874. The coverImageUrl field is an optional string in uri format for a custom cover image URL for video pins.

Media Requirements

Choose the media type first, because Pinterest requires exactly one media item per pin, either one image or one video, with no carousels or multi-image posts. For images, use JPG, PNG, or WebP, with 1000x1500px at a 2:3 ratio recommended and a maximum size of 32 MB. For videos, use MP4 or MOV, with 1080p recommended and a maximum size of 2 GB. For a video pin, consider supplying coverImageUrl in platformSpecificData so the pin has a custom cover image. Failure check: count the entries in mediaItems before sending the request; anything other than exactly one item violates the single-media rule.

Constraints

Validate every field before publishing. The content field is limited to a maximum of 800 characters. The title is limited to a maximum of 100 characters. The link must use HTTPS. The media must be a publicly accessible URL. Text-only pins are not supported, so at least one image or video is required, and boardId is required in platformSpecificData. Failure check: run through this list in order, content length, title length, link scheme, media accessibility, presence of media, and presence of boardId, and correct any failure before calling POST {{API_BASE_URL}}/v1/posts.

Cross-Post

A single POST {{API_BASE_URL}}/v1/posts request can publish to more than one platform. In the cross-post example, the same content and the same single image in mediaItems are sent to Pinterest, with boardId and link in platformSpecificData, and to LinkedIn, with its own accountId, in one request with publishNow true. This keeps the media and copy consistent across both destinations while each platform entry carries only the fields that platform needs. Failure check: confirm that each platform entry has its own accountId and that the Pinterest entry includes boardId, because the shared mediaItems array does not supply board targeting.

Pinterest platformSpecificData fields
FieldTypeRequiredValues and constraintsDescription
boardIdstringYes—Target board ID. Retrieve available boards via GET /v1/pinterest/boards.
titlestringNoLength: 0–100Pin title. Max 100 characters. Defaults to first line of content.
linkstringNoFormat: uriHTTPS destination URL when the pin is clicked. Important for driving traffic.
altTextstringNoLength: 0–500Accessible image description. Max 500 characters.
dominantColorstringNo—Hex color for the loading placeholder (e.g. "#6E7874").
coverImageUrlstringNoFormat: uriCustom cover image URL for video pins.

Exact source field map for platformSpecificData.

Image versus video media requirements
TypeFormatsRecommended SizeMax Size
ImageJPG, PNG, WebP1000x1500px (2:3 ratio)32 MB
VideoMP4, MOV1080p2 GB

Exactly one media item per pin; no carousels or multi-image posts.

Pin validation and failure checks
CheckRuleFailure action
Content lengthMaximum 800 characters from the content fieldShorten content before posting
Title lengthMaximum 100 charactersShorten title or rely on the first line of content within the limit
Link schemeMust use HTTPSReplace the link with an HTTPS destination URL
Media accessibilityPublicly accessible URL requiredHost the media at a publicly accessible URL
Media presenceAt least one image or video required; text-only pins are not supportedAdd exactly one image or video to mediaItems
Media countExactly one media item per pinRemove extra items so mediaItems contains one entry
Target boardboardId required in platformSpecificDataList boards and pass the selected board id as boardId

Derived directly from stated source constraints.

Connect a Pinterest account
curl {{API_BASE_URL}}/v1/connect/pinterest \
  -H "x-access-key: YOUR_API_KEY"
List Pinterest boards
curl "{{API_BASE_URL}}/v1/pinterest/boards?accountId=your-pinterest-account-id" \
  -H "x-access-key: YOUR_API_KEY"
List boards response
{
	"success": true,
	"boards": [
		{
			"id": "596867825554313696",
			"name": "Hair",
			"description": "",
			"privacy": "PUBLIC"
		},
		{
			"id": "733523926748495119",
			"name": "Home interior design",
			"description": "",
			"privacy": "PUBLIC"
		}
	]
}
Create a Pinterest pin with curl
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "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
  }'
Create pin response
{
	"success": true,
	"status": "published",
	"postId": "post_vwx234",
	"platforms": [
		{
			"platform": "pinterest",
			"success": true,
			"platformPostUrl": "https://www.pinterest.com/pin/98765/"
		}
	]
}
Cross-post to Pinterest and LinkedIn
curl -X POST "{{API_BASE_URL}}/v1/posts" \
  -H "x-access-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "A short example update.",
    "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
  }'