How to Post a Pin via API
The request flow for creating a Pin programmatically, from board selection to publish confirmation.
By André LugTo post a Pin via API: connect the Pinterest account through PostGate’s hosted OAuth URL, list the profile’s boards so the user picks a destination, then send POST /api/posts with the board_id under post.options.pinterest plus one image or video, and confirm delivery via GET /api/posts/{id} or a webhook. No separate Pinterest developer app or access-tier approval is needed.
This is the complete flow for publishing a Pin via API: connect a Pinterest account, let the user choose a destination board, create the Pin, and confirm it actually published. Every step below uses PostGate’s API, so there’s no separate Pinterest developer app or access-tier approval to sort out first — sign up and connect an account to follow along.
Step 1 — Connect the Pinterest account
curl -X POST https://postgate.studio/api/profiles/connect \
-H "Authorization: Bearer $POSTGATE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"platform": "pinterest",
"profile_group_id": "grp_acme123",
"return_url": "https://app.example.com/settings/social"
}'Step 2 — List boards and let the user pick one
curl https://postgate.studio/api/profiles/pro_pinterest123/boards \
-H "Authorization: Bearer $POSTGATE_API_KEY"
{
"data": [
{ "id": "1099...", "name": "Launches", "description": "Product news", "privacy": "PUBLIC" }
],
"meta": { "profile_id": "pro_pinterest123", "fetched_at": "2026-08-25T10:00:00.000Z" }
}Step 3 — Create the Pin
board_id under post.options.pinterest, attach one image or video, and send the request with a stable Idempotency-Key. Omit scheduled_at to publish immediately, or see Pinterest Scheduling API to publish later instead.curl -X POST https://postgate.studio/api/posts \
-H "Authorization: Bearer $POSTGATE_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: launch-pin-001" \
-d '{
"post": {
"body": "New arrivals just dropped.",
"options": { "pinterest": { "board_id": "1099...", "title": "Launch story" } }
},
"profiles": ["pro_pinterest123"],
"media": ["https://cdn.example.com/launch.jpg"]
}'Step 4 — Confirm it actually published
GET /api/posts/{id} — or better, subscribe to a delivery webhook — and read the target’s status, platform_id, and permalink once it lands. Board ID mistakes, expired sandbox connections, and missing scopes all surface here as a structured target error instead of a silent failure.curl https://postgate.studio/api/posts/post_01JXYZ \
-H "Authorization: Bearer $POSTGATE_API_KEY"Frequently asked questions
Do I need a Pinterest developer app to post a Pin via API?
Not with PostGate — every step uses PostGate’s API, so there’s no separate Pinterest developer app or access-tier approval to sort out first. Pinterest’s OAuth screen still runs on Pinterest’s own domain when the user connects; your product never sees the access token, and PostGate never exposes it back to you either.
Can I create a Pin without choosing a board?
No — a Pin can’t be created without a target board, so the board-selection step isn’t optional. Read boards live via the profile’s boards endpoint rather than asking the user to type a board ID: names change, and PostGate doesn’t keep a cached copy to go stale. The chosen board_id goes under post.options.pinterest.
How do I know my Pin actually published?
The create call returns almost immediately with a pending target while PostGate delivers in the background. Poll GET /api/posts/{id} — or better, subscribe to a delivery webhook — and read the target’s status, platform_id, and permalink once it lands. Board ID mistakes, expired sandbox connections, and missing scopes all surface there as structured target errors instead of silent failures.
Can I schedule a Pin instead of publishing immediately?
Yes. Omitting scheduled_at publishes the Pin immediately; including it publishes later. The same create request applies either way — see the Pinterest Scheduling API guide for the scheduled path.
