Posts

Publish pins to Pinterest via API

A POST /posts with the pinterest connection creates a pin on the board you choose. Connect lists the customer account's boards and sections live, so your product doesn't implement Pinterest OAuth or store tokens.

The request

POST /api/posts?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>
Idempotency-Key: <unique key>

{
  "external_reference": "pin-3301",
  "format": "feed",
  "caption": "Linen sofa in warm oat. Free shipping this month.",
  "media": [
    {
      "type": "image",
      "url": "https://cdn.example.com/sofa.jpg",
      "alt_text": "Oat linen sofa in a bright living room"
    }
  ],
  "pinterest": {
    "board_id": "<board id>",
    "board_section_id": "<section id>",
    "title": "Oat linen sofa",
    "link": "https://shop.example.com/sofa"
  }
}

What you can do

  • Publish an image pin or a video pin.
  • List the account's boards with GET /posts/pinterest/boards and the sections with GET /posts/pinterest/boards/{board_id}/sections.
  • Set the pin's title, destination link and description.
  • Save the pin to a specific board section with board_section_id.
  • Add alt_text of up to 500 characters for accessibility.

Rules and limits

  • A pin is exactly 1 media item (image or video) and the format is always feed.
  • pinterest.board_id is required. pinterest.cover_url is required on a video pin and refused on an image pin.
  • When choosing the account by name, only source_name is used, without integration_slug.
  • POST /posts responds 202 and publishing runs afterwards. Track it with GET /posts/{uuid}.
  • external_reference is required and the Idempotency-Key header prevents duplicating the request.

Main fields

FieldTypeRequiredDescription
external_referencestringYesThe pin's id in your system (up to 100 characters). Stops the same pin from being published twice on the same account.
formatstringYesAlways feed on Pinterest.
captionstringNoThe pin description, up to 800 characters.
mediaarrayYesExactly 1 image or 1 video. alt_text goes up to 500 characters.
pinterest.board_idstringYesThe board the pin is saved to (numeric string, up to 50 characters). Comes from GET /posts/pinterest/boards.
pinterest.board_section_idstringNoThe board section. Comes from GET /posts/pinterest/boards/{board_id}/sections.
pinterest.titlestringNoPin title, up to 100 characters.
pinterest.linkstringNoDestination URL when the pin is clicked (http or https).
pinterest.cover_urlstringNoThe pin cover. Required on a video pin and refused on an image pin.

Who it is for

  • E-commerce and catalogs

    The store publishes each new product as a pin on the collection's board, with a link back to the purchase page.

  • Content marketing platform

    Each published article becomes a pin with a cover image, title and link, in the right board section.

  • Social media AI agent

    An agent lists the account's boards, picks the best fit and publishes the pin with generated description and alt_text.

Works with

  • Pinterest

Frequently asked questions

How do I find the board_id?

Call GET /posts/pinterest/boards with the customer's connection. The response carries id, name, description and privacy for each board.

Can I publish a video?

Yes: 1 video per pin, with pinterest.cover_url required as the cover.

How many media items fit in a pin?

Exactly 1, an image or a video.

Related

See everything you can do with Posts

See Connect applied to your product.

Try it for 15 days with no card, or walk our team through your use case.