Create Pin API: Post Pins on Pinterest via API
The Create Pin API workflow lets you create pins programmatically with a Pinterest API request that combines an image, a destination link, and board targeting. Connect the account first, find the board ID, then submit the pin payload. This guide walks through each step, including how to schedule a pin and how to cross-post the same content to other platforms.
What you need before you call the API
Before you call the API, gather three things: an API key, a connected Pinterest business account, and at least one Pinterest board. Retrieve the API key from the Access Keys page in your dashboard and treat it like a password. Keep it in an environment variable or secret store rather than committing it to source control. Confirm the Pinterest account is connected and that the board you intend to use belongs to that account, because the pin request pairs an accountId with a boardId from the same account.
Connect your Pinterest account
Start the connection flow with a GET request to the Pinterest connect endpoint, passing your key in the x-access-key header. Open the returned URL, authorize with your Pinterest account, and complete the flow. Then list your integrations with a GET request to the integrations endpoint using the same header, and note the account ID for the Pinterest account you just connected. Accounts can also be connected through the dashboard, which gives a visual overview of connected accounts. The source contract also describes connection via GET /v1/connect/{platform}, where the platform segment varies by platform.
Find your board ID
Pins are published to boards, so board targeting requires the board ID for the destination board. List the boards for your connected account with a GET request to the Pinterest boards endpoint, passing accountId as a query parameter and your key in the x-access-key header. The response lists boards with their IDs; pick the board that matches your content theme. If you only need the ID of one public board, you can paste its URL into the Pinterest board ID finder instead of listing all boards. Record the boardId exactly as returned, because it is a required field in the pin payload.
Create a pin with POST /v1/posts
Create the pin with a POST request to the posts endpoint. Set the x-access-key header and Content-Type to application/json. In the body, the top-level content field becomes the pin description, which Pinterest uses for search, so include relevant keywords naturally. The platforms array contains one entry for Pinterest with platform set to pinterest, accountId set to your connected account, and platformSpecificData holding the Pinterest-specific fields. Inside platformSpecificData, boardId is required and identifies where the pin is created, title is the pin title shown prominently in the feed, and link is the destination URL that visitors reach when they click the pin. The mediaItems array carries the image, with type set to image and url pointing to a publicly reachable image. Set publishNow to true to publish immediately. See the worked example titled Create a Pinterest pin and publish now for the full request.
Pin image guidance
Pinterest is a visual platform, so the image deserves as much attention as the copy. The source guidance recommends a 2:3 aspect ratio, such as 1000x1500 pixels, because vertical images occupy more feed space. Use PNG or JPEG and keep the file size under 20MB. Readable text on the image, such as a blog post title or how-to steps, can help viewers understand the pin at a glance. Faces are not necessary; infographics, screenshots, and product shots can work well. Treat these as starting guidance and check your own results rather than assuming any single format guarantees engagement.
Schedule a pin
To schedule a pin instead of publishing immediately, omit publishNow and set scheduledFor to the desired date and time together with timezone. In the worked example titled Schedule a pin, scheduledFor is set to 2026-04-20T14:00:00 and timezone to America/New_York. Because pins can remain discoverable for a long time, spreading pins across the week is a practical alternative to batch posting the same image everywhere. Try modest edits to the artwork and distribute those versions over separate days and boards. After scheduling, check the posts dashboard to confirm the scheduled status and manage your content calendar.
Why pins can suit evergreen content
Pins can suit evergreen content because every pin carries a link back to a destination URL, and that link attribution is built into the pin format. A pin may continue to surface in search and feed results long after it is posted, which makes Pinterest a useful channel for blogs, documentation, and product pages. Well-written titles and descriptions help people understand what the linked page offers. Measure your own traffic and saves over time to judge whether the channel is worthwhile for your content, rather than relying on general claims about ranking or shelf life.
Cross-post the same content to multiple platforms
A single POST request can publish to several platforms at once. Add one entry per platform to the platforms array: the Pinterest entry carries platformSpecificData with boardId, title, and link, while the Twitter and LinkedIn entries carry their own platform and accountId values. Each platform receives the content in its native format, so Pinterest gets a pin with board, title, and link, while Twitter and LinkedIn get an image post with the text content. See the worked example titled Cross-post to Pinterest, Twitter, and LinkedIn. Before sending a multi-platform request, verify each accountId and, for Pinterest, the boardId pairing, so one bad target does not undermine the whole batch.
Next steps and pre-flight checklist
Run through the pre-flight checklist before every submission: the x-access-key header is present, accountId matches the connected Pinterest account, boardId was returned for that same account, title and link are set, the mediaItems image URL is reachable, and either publishNow or scheduledFor plus timezone is set. If any check fails, fix the payload before sending. The failure matrix below lists common pre-flight failures and the correction for each. Once the request succeeds, confirm the pin appears on the intended board and that the link resolves to the correct page.
| Field | Location | Requiredness in source | Purpose |
|---|---|---|---|
| content | Top level | Used in all examples | Pin description; used by Pinterest for search |
| platforms[].platform | platforms entry | Used in all examples | Set to pinterest for a pin |
| platforms[].accountId | platforms entry | Used in all examples | Connected Pinterest account ID |
| platforms[].platformSpecificData.boardId | platformSpecificData | Required | Board where the pin is created |
| platforms[].platformSpecificData.title | platformSpecificData | Used in all examples | Pin title shown in the feed |
| platforms[].platformSpecificData.link | platformSpecificData | Used in all examples | Destination URL for pin clicks |
| mediaItems[] | Top level | Used in all examples | Image media with type image and url |
| publishNow | Top level | Used for immediate publishing | Set to true to publish now |
| scheduledFor | Top level | Used for scheduled publishing | Scheduled date and time |
| timezone | Top level | Used with scheduledFor | Timezone for the scheduled time |
Pre-flight field map derived from the source payload; boardId is the only field explicitly marked required in the source.
| Pre-flight check | Failure symptom to check for | Correction |
|---|---|---|
| Missing x-access-key header | Request sent without the API key header | Add the x-access-key header with your API key |
| Missing accountId | Platform entry has no accountId | List integrations and copy the Pinterest account ID |
| Missing boardId | platformSpecificData has no boardId | List boards for the account and copy the board ID |
| Wrong board/account pairing | boardId belongs to a different account | Re-list boards using the same accountId used in the pin payload |
| Unreachable image URL | mediaItems url does not resolve | Host the image at a publicly reachable URL and retest |
| Missing title or link | Pin would lack a title or destination | Set title and link inside platformSpecificData |
| Missing schedule fields | Neither publishNow nor scheduledFor is set | Set publishNow true, or scheduledFor together with timezone |
Pre-flight checks only; these are not verified error responses from the API.
curl {{API_BASE_URL}}/v1/connect/pinterest \
-H "x-access-key: YOUR_API_KEY"curl {{API_BASE_URL}}/v1/connect/integrations \
-H "x-access-key: YOUR_API_KEY"curl "{{API_BASE_URL}}/v1/connect/pinterest/boards?accountId=your-account-id" \
-H "x-access-key: YOUR_API_KEY"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": "your-board-id",
"title": "10 Terminal Shortcuts That Save You 30 Min/Day",
"link": "https://yourblog.com/terminal-shortcuts"
}
}
],
"mediaItems": [
{ "type": "image", "url": "https://your-cdn.com/terminal-tips-pin.png" }
],
"publishNow": true
}'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": "your-board-id",
"title": "CI/CD for Side Projects: The Simple Guide",
"link": "https://yourblog.com/cicd-guide"
}
}
],
"mediaItems": [
{ "type": "image", "url": "https://your-cdn.com/cicd-pin.png" }
],
"scheduledFor": "2026-04-20T14:00:00",
"timezone": "America/New_York"
}'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": "acc_pin_123",
"platformSpecificData": {
"boardId": "board_456",
"title": "Build a REST API in 10 Minutes",
"link": "https://yourblog.com/rest-api-guide"
}
},
{ "platform": "twitter", "accountId": "acc_tw_789" },
{ "platform": "linkedin", "accountId": "acc_li_012" }
],
"mediaItems": [
{ "type": "image", "url": "https://your-cdn.com/rest-api-pin.png" }
],
"publishNow": true
}'