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.
| 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. |
Exact source field map for platformSpecificData.
| Type | Formats | Recommended Size | Max Size |
|---|---|---|---|
| Image | JPG, PNG, WebP | 1000x1500px (2:3 ratio) | 32 MB |
| Video | MP4, MOV | 1080p | 2 GB |
Exactly one media item per pin; no carousels or multi-image posts.
| Check | Rule | Failure action |
|---|---|---|
| Content length | Maximum 800 characters from the content field | Shorten content before posting |
| Title length | Maximum 100 characters | Shorten title or rely on the first line of content within the limit |
| Link scheme | Must use HTTPS | Replace the link with an HTTPS destination URL |
| Media accessibility | Publicly accessible URL required | Host the media at a publicly accessible URL |
| Media presence | At least one image or video required; text-only pins are not supported | Add exactly one image or video to mediaItems |
| Media count | Exactly one media item per pin | Remove extra items so mediaItems contains one entry |
| Target board | boardId required in platformSpecificData | List boards and pass the selected board id as boardId |
Derived directly from stated source constraints.
curl {{API_BASE_URL}}/v1/connect/pinterest \
-H "x-access-key: YOUR_API_KEY"curl "{{API_BASE_URL}}/v1/pinterest/boards?accountId=your-pinterest-account-id" \
-H "x-access-key: YOUR_API_KEY"{
"success": true,
"boards": [
{
"id": "596867825554313696",
"name": "Hair",
"description": "",
"privacy": "PUBLIC"
},
{
"id": "733523926748495119",
"name": "Home interior design",
"description": "",
"privacy": "PUBLIC"
}
]
}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
}'{
"success": true,
"status": "published",
"postId": "post_vwx234",
"platforms": [
{
"platform": "pinterest",
"success": true,
"platformPostUrl": "https://www.pinterest.com/pin/98765/"
}
]
}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
}'