Skip to content
Tailwind API

Scheduling Pins

This guide walks you through the complete process of scheduling a pin to Pinterest using the Tailwind API.

Overview

Scheduling a pin involves four steps:

  1. Get your Pinterest accounts
  2. Choose a board to pin to
  3. Create the post with a schedule time
  4. Verify the post was scheduled

Prerequisites

  • A Tailwind account with at least one Pinterest account connected
  • Your API key
  • An image URL to pin

Step 1: List Your Accounts

First, retrieve your Pinterest accounts to get the account ID you’ll use for scheduling.

Terminal window
curl -X GET https://api-v1.tailwind.ai/v1/accounts \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": {
    "accounts": [
      {
        "id": "acc_123456",
        "userId": "987654321",
        "displayName": "My Pinterest",
        "username": "mypinterest",
        "avatarUrl": "https://...",
        "tokenAuthorized": true,
        "isDomainVerified": true,
        "createdAt": "2024-01-15T10:30:00Z"
      }
    ]
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

Note the id field (acc_123456) - you’ll need this for subsequent requests.

Step 2: Get Available Boards

List the boards for your account to find where you want to pin.

Terminal window
curl -X GET https://api-v1.tailwind.ai/v1/accounts/acc_123456/boards \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": {
    "boards": [
      {
        "id": "board_789",
        "name": "Recipe Ideas",
        "isCollaborator": false,
        "isSecret": false
      },
      {
        "id": "board_456",
        "name": "Home Decor",
        "isCollaborator": false,
        "isSecret": false
      }
    ]
  },
  "meta": {
    "requestId": "req_def456"
  }
}

Step 3: Create and Schedule the Post

Create a post with all the pin details and a scheduled time.

Terminal window
curl -X POST https://api-v1.tailwind.ai/v1/accounts/acc_123456/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaUrl": "https://example.com/my-beautiful-image.jpg",
    "title": "Amazing Recipe You Must Try",
    "description": "This delicious recipe will become your new favorite! Easy to make and perfect for weeknight dinners. #recipes #cooking #dinner",
    "url": "https://myblog.com/amazing-recipe",
    "boardId": "board_789",
    "altText": "A colorful plate of pasta with fresh vegetables",
    "sendAt": "2024-01-20T14:00:00Z"
  }'

Response:

{
  "data": {
    "post": {
      "id": "post_abc123",
      "status": "queued",
      "mediaUrl": "https://example.com/my-beautiful-image.jpg",
      "mediaType": "image",
      "title": "Amazing Recipe You Must Try",
      "description": "This delicious recipe will become your new favorite!...",
      "url": "https://myblog.com/amazing-recipe",
      "boardId": "board_789",
      "altText": "A colorful plate of pasta with fresh vegetables",
      "sendAt": 1705758000,
      "sentAt": null,
      "createdAt": 1705320000,
      "pinId": null
    }
  },
  "meta": {
    "requestId": "req_ghi789"
  }
}

The post is now scheduled! The status: "queued" confirms it’s in the queue.

Step 4: Verify Your Scheduled Post

List your queued posts to verify everything looks correct.

Terminal window
curl -X GET "https://api-v1.tailwind.ai/v1/accounts/acc_123456/posts?status=queued" \
  -H "Authorization: Bearer YOUR_API_KEY"

Creating Draft Posts

If you want to save a post without scheduling it, simply omit the sendAt field:

Terminal window
curl -X POST https://api-v1.tailwind.ai/v1/accounts/acc_123456/posts \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "mediaUrl": "https://example.com/image.jpg",
    "title": "Draft Post",
    "description": "I will schedule this later"
  }'

The post will be created with status: "draft".

Scheduling a Draft Post

To schedule a draft post later, use the schedule endpoint:

Terminal window
curl -X POST https://api-v1.tailwind.ai/v1/accounts/acc_123456/posts/post_abc123/schedule \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sendAt": "2024-01-25T09:00:00Z"
  }'

Using Smart Schedule Timeslots

Instead of picking a specific time, you can use your smart schedule timeslots. First, list your timeslots:

Terminal window
curl -X GET https://api-v1.tailwind.ai/v1/accounts/acc_123456/timeslots \
  -H "Authorization: Bearer YOUR_API_KEY"

Response:

{
  "data": {
    "timeslots": [
      {
        "id": "slot_1",
        "accountId": "acc_123456",
        "dayPreference": 1,
        "timePreference": "09:00",
        "timezone": "America/New_York",
        "type": "optimal",
        "sendAt": 1705755600
      }
    ]
  }
}

Use the sendAt timestamp from a timeslot when creating your post.

Best Practices

Pin Titles

  • Keep titles under 100 characters
  • Make them descriptive and keyword-rich
  • Front-load the most important words

Pin Descriptions

  • Use up to 500 characters
  • Include relevant keywords naturally
  • Add 2-5 relevant hashtags at the end
  • Include a call to action

Alt Text

  • Describe the image for accessibility
  • Keep it factual and descriptive
  • Helps with Pinterest search too

Scheduling Times

  • Use ISO 8601 format: 2024-01-20T14:00:00Z
  • Schedule at least 15 minutes in the future
  • Consider your audience’s timezone

Error Handling

Common errors when scheduling:

Error CodeMeaningSolution
400Invalid requestCheck required fields and formats
401UnauthorizedVerify your API key
404Account not foundCheck the account ID

Example error response:

{
  "error": {
    "code": "BAD_REQUEST",
    "message": "sendAt must be at least 15 minutes in the future"
  },
  "meta": {
    "requestId": "req_xyz789"
  }
}

Next Steps