Posts

Create and list Pinterest boards via API

A pin needs a board. With POST /posts/pinterest/boards your product creates the board on the account the customer connected, and with GET /posts/pinterest/boards it lists the existing ones, live. Connect handles the Pinterest token.

The request

POST /api/posts/pinterest/boards?customer_integration=<connection uuid>
Authorization: Bearer <merchant token>
x-customer-token: <customer token>

{
  "name": "Summer collection",
  "description": "Ideas and products for the season",
  "privacy": "PUBLIC"
}

What you can do

  • Create a board with a name, description and privacy.
  • List the account's boards in real time, with id, name, description and privacy.
  • Pick the account by connection (customer_integration) or by name (source_name).
  • List a board's sections with GET /posts/pinterest/boards/{board_id}/sections.
  • Use the id of the created board as pinterest.board_id in POST /posts.

Rules and limits

  • POST /posts/pinterest/boards responds 201 with the created board: id, name, description and privacy.
  • name is required and goes up to 180 characters. description goes up to 500. privacy accepts PUBLIC, PROTECTED or SECRET.
  • The account is given by customer_integration in the query or by source_name in the body, never both.
  • The listing is live, straight from the customer's Pinterest account, not a copy kept in Connect.

Main fields

FieldTypeRequiredDescription
customer_integrationstringNoThe uuid of the Pinterest connection, in the query. Alternative to source_name.
source_namestringNoThe Pinterest account name (up to 255 characters). Used when there is no customer_integration.
namestringYesBoard name, up to 180 characters.
descriptionstringNoBoard description, up to 500 characters.
privacystringNoBoard visibility: PUBLIC, PROTECTED or SECRET.
idstringNoIn the 201 response, the id of the created board. Use it as pinterest.board_id when publishing.

Who it is for

  • Brand onboarding

    When Pinterest is connected, your product automatically creates the brand's default boards (collections, launches).

  • Catalog organized by category

    An e-commerce platform creates one board per product category and then publishes pins to each.

  • Curation AI agent

    An agent checks whether the topic's board exists, creates it when it doesn't and publishes the pin to it.

Works with

  • Pinterest

Frequently asked questions

Do I need to create the board before publishing a pin?

A pin needs a pinterest.board_id. You can use an existing board, listed by GET /posts/pinterest/boards, or create a new one.

What changes between PUBLIC, PROTECTED and SECRET?

It is the board's visibility on Pinterest. Connect passes on the value you send in privacy.

How do I list the boards?

Call GET /posts/pinterest/boards with customer_integration or source_name. The response carries the account's list of boards.

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.