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
| Field | Type | Required | Description |
|---|---|---|---|
| customer_integration | string | No | The uuid of the Pinterest connection, in the query. Alternative to source_name. |
| source_name | string | No | The Pinterest account name (up to 255 characters). Used when there is no customer_integration. |
| name | string | Yes | Board name, up to 180 characters. |
| description | string | No | Board description, up to 500 characters. |
| privacy | string | No | Board visibility: PUBLIC, PROTECTED or SECRET. |
| id | string | No | In 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.
See Connect applied to your product.
Try it for 15 days with no card, or walk our team through your use case.
