Skip to content

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.

POST /v1/posts Pinterest field map
FieldLocationRequiredness in sourcePurpose
contentTop levelUsed in all examplesPin description; used by Pinterest for search
platforms[].platformplatforms entryUsed in all examplesSet to pinterest for a pin
platforms[].accountIdplatforms entryUsed in all examplesConnected Pinterest account ID
platforms[].platformSpecificData.boardIdplatformSpecificDataRequiredBoard where the pin is created
platforms[].platformSpecificData.titleplatformSpecificDataUsed in all examplesPin title shown in the feed
platforms[].platformSpecificData.linkplatformSpecificDataUsed in all examplesDestination URL for pin clicks
mediaItems[]Top levelUsed in all examplesImage media with type image and url
publishNowTop levelUsed for immediate publishingSet to true to publish now
scheduledForTop levelUsed for scheduled publishingScheduled date and time
timezoneTop levelUsed with scheduledForTimezone 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 failure matrix
Pre-flight checkFailure symptom to check forCorrection
Missing x-access-key headerRequest sent without the API key headerAdd the x-access-key header with your API key
Missing accountIdPlatform entry has no accountIdList integrations and copy the Pinterest account ID
Missing boardIdplatformSpecificData has no boardIdList boards for the account and copy the board ID
Wrong board/account pairingboardId belongs to a different accountRe-list boards using the same accountId used in the pin payload
Unreachable image URLmediaItems url does not resolveHost the image at a publicly reachable URL and retest
Missing title or linkPin would lack a title or destinationSet title and link inside platformSpecificData
Missing schedule fieldsNeither publishNow nor scheduledFor is setSet publishNow true, or scheduledFor together with timezone

Pre-flight checks only; these are not verified error responses from the API.

Connect a Pinterest account
curl {{API_BASE_URL}}/v1/connect/pinterest \
  -H "x-access-key: YOUR_API_KEY"
List connected integrations
curl {{API_BASE_URL}}/v1/connect/integrations \
  -H "x-access-key: YOUR_API_KEY"
List Pinterest boards for an account
curl "{{API_BASE_URL}}/v1/connect/pinterest/boards?accountId=your-account-id" \
  -H "x-access-key: YOUR_API_KEY"
Create a Pinterest pin and publish now
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
  }'
Schedule a Pinterest pin
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"
  }'
Cross-post to Pinterest, Twitter, 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": "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
  }'