Free/busy and availability

BentoCal has two scheduling calls:

• POST /free_busy returns when each user is busy.
• POST /availability does the maths for you and returns times when people are free.

Both read calendars live from Google and Microsoft, so results are always current.

Which calendars are read

By default, BentoCal reads the primary calendar of every active connection the user has. A user with a work Microsoft account and a personal Google account is busy whenever either calendar is.

To read other calendars, pass calendar_ids (up to 50 per user). Each entry can be:

• a calendar id from any of the user's connections (list them with GET /connections/{connection_id}/calendars),
• primary, meaning the default connection's primary calendar, or
• an account's email address, meaning that account's primary calendar.

Free/busy

curl -X POST https://api.bentocal.com/au/v1/free_busy \
  -H "Authorization: Bearer $BENTOCAL_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_ids": ["user_123", "user_456"],
    "start": "2026-10-20T00:00:00Z",
    "end": "2026-10-27T00:00:00Z",
    "calendar_ids": { "user_456": ["primary", "team-rota@example.com"] }
  }'

{
  "users": [
    { "user_id": "user_123", "busy": [{ "start": "2026-10-20T01:00:00Z", "end": "2026-10-20T02:30:00Z" }] },
    { "user_id": "user_456", "busy": [] }
  ],
  "errors": []
}

• Up to 100 users and a range of up to 62 days.
• Busy means the provider's busy, tentative and out-of-office statuses. Free time and "working elsewhere" don't count.
• Intervals are merged across calendars, sorted, and returned in UTC.

Availability

Availability takes the people who need to attend and the windows to search, and returns times that work:

curl -X POST https://api.bentocal.com/au/v1/availability \
  -H "Authorization: Bearer $BENTOCAL_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "participants": [{ "user_id": "user_123" }, { "user_id": "user_456" }],
    "required": "all",
    "periods": [
      { "start": "2026-10-20T09:00:00+11:00", "end": "2026-10-20T17:00:00+11:00" },
      { "start": "2026-10-21T09:00:00+11:00", "end": "2026-10-21T17:00:00+11:00" }
    ],
    "slot_duration_minutes": 45,
    "slot_interval_minutes": 15,
    "buffer_after_minutes": 10
  }'

{
  "slots": [
    { "start": "2026-10-19T22:00:00Z", "end": "2026-10-19T22:45:00Z", "user_ids": ["user_123", "user_456"] },
    { "start": "2026-10-19T22:15:00Z", "end": "2026-10-19T23:00:00Z", "user_ids": ["user_123", "user_456"] }
  ],
  "errors": []
}

Options

A slot is returned only when it fits inside a period and every required participant is free for the whole slot plus its buffers.

Slots or periods

• format: "slots" returns bookable slots of slot_duration_minutes on the slot_interval_minutes grid. Use it to show a list of times to pick from.
• format: "periods" returns the longest free stretches (no grid) that are at least slot_duration_minutes long. Use it to draw free time on a calendar. With required: "any", a period ends wherever the set of free participants changes.

When a calendar can't be read

Both calls return 200 even when some users fail. Those users are left out of the results and listed in errors:

{
  "errors": [
    {
      "user_id": "user_456",
      "connection_id": "conn_7rD1sW8eYq2KjH6b",
      "code": "relink_required",
      "message": "The calendar connection must be re-linked by the user."
    }
  ]
}