Get free/busy

Returns busy time for up to 100 users over at most 62 days. Busy means the provider's busy, tentative and out-of-office statuses; free and working-elsewhere time does not count.

A user whose calendars can't be read is reported in errors and the rest still succeed, so this returns 200 even when every user fails.

POSThttps://api.bentocal.com/au/v1/free_busy

Authentication

AuthorizationstringheaderBearer <token>required

An API key: bc_{live|test}_{region}_…, from the console.

Request body

application/jsonrequired

user_idsarray of stringrequired
startstringdate-timerequired
Start of the range.
endstringdate-timerequired
End of the range: after start and at most 62 days later.
calendar_idsmap of array of string
Calendars to read per user id: calendar ids from any of the user's connections, primary (the default connection's primary calendar) or an account's email address (its primary calendar). A user not listed is read on every active connection's primary calendar.

Responses

usersarray of objectrequired
errorsarray of ParticipantErrorrequired
Users whose calendars could not be read. They are left out of users.

Errors

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

{
  "users": [
    {
      "user_id": "user_123",
      "busy": [
        {
          "start": "2026-10-20T01:00:00Z",
          "end": "2026-10-20T02:30:00Z"
        }
      ]
    }
  ],
  "errors": [
    {
      "user_id": "user_456",
      "connection_id": "conn_7rD1sW8eYq2KjH6b",
      "code": "relink_required",
      "message": "The calendar connection must be re-linked by the user."
    }
  ]
}

Authentication

Request body

Responses

Was this page helpful?