Find available times

Finds times when the participants are free inside the given periods (up to 100 participants and 200 periods spanning at most 62 days).

With format: "slots" it returns bookable slots that fit inside a period, start on the slot_interval_minutes grid from 00:00 UTC and leave every required participant free for the whole slot plus buffers. With format: "periods" it returns maximal free intervals instead.

Participants whose calendars can't be read are reported in errors and left out. With required: "all" any such error means no results.

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

Authentication

AuthorizationstringheaderBearer <token>required

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

Request body

application/jsonrequired

participantsarray of objectrequired
requiredstringdefault: allall | any
all: every participant must be free. any: at least one must be; each result lists who is.
periodsarray of objectrequired
Windows to search. Each must end after it starts, and together they span at most 62 days.
slot_duration_minutesintegerrange: 5…1440required
Length of each slot.
slot_interval_minutesintegerrange: 5…1440
Gap between slot start times, which align to this grid from 00:00 UTC. Defaults to slot_duration_minutes.
buffer_before_minutesintegerdefault: 0range: 0…240
Free time required before each slot.
buffer_after_minutesintegerdefault: 0range: 0…240
Free time required after each slot.
formatstringdefault: slotsslots | periods
slots: bookable slots of slot_duration_minutes on the slot_interval_minutes grid. periods: maximal free intervals (no grid) at least slot_duration_minutes long; with required: "any" an interval ends wherever the set of free participants changes.

Responses

slotsarray of AvailabilitySlot
Present when format is slots.
periodsarray of AvailabilitySlot
Present when format is periods.
errorsarray of ParticipantErrorrequired
Participants whose calendars could not be read. They are left out; with required: "all" that means no results.

Errors

curl -X POST "https://api.bentocal.com/au/v1/availability" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "participants": [
    {
      "user_id": "user_123"
    },
    {
      "user_id": "user_456"
    }
  ],
  "required": "all",
  "periods": [
    {
      "start": "2026-10-20T22:00:00Z",
      "end": "2026-10-21T07:00:00Z"
    }
  ],
  "slot_duration_minutes": 30,
  "buffer_after_minutes": 10
}'

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

Authentication

Request body

Responses

Was this page helpful?