Check Availability

API reference for checking available appointment time slots using natural language queries.

Check available appointment time slots with a natural language query.

Endpoint

POST /api/v1/check-availability

Request Body

{
  "calendarId": "YOUR_CALENDAR_ID",
  "query": "next Monday at 10 AM"
}

Field	Type	Required	Description
calendarId	string	Yes	Your calendar ID — determines which calendar the request targets
query	string	Yes*	Natural language availability query in German or English (max. 500 characters)
requestedDateTime	string	Yes*	Alternative to `query`: desired time as an ISO 8601 timestamp
serviceName	string	No	Desired service — its duration determines the slot calculation
serviceNames	string[]	No	Multiple desired services (max. 10, durations are added up)
language	string	No	`"de"` or `"en"` (default: `"de"`) — response language for `requestedDateTime`

* Send either query or requestedDateTime. If both are missing, the API responds with 400.

calendarId is required on every request. You can find it pre-filled under Calendar › Name › API, section Integration Guide. Send it as a field in the JSON body. If your platform wraps the body in an envelope (e.g. Retell's args object), pass it as a URL query parameter instead — ?calendarId=YOUR_CALENDAR_ID — because the API only reads calendarId from the top-level body, the query string, or route parameters, never from a nested args object.

Response — Time Available

{
  "action": "confirm",
  "success": true,
  "humanReadable": "Monday, 02.03 at 10:00 AM is available",
  "result": "Time is available",
  "day": "Monday",
  "date": "02.03",
  "time": "10:00"
}

date uses the format DD.MM, time the format HH:mm.

Response — Suggesting Alternatives

When the requested time is taken, FlowCaptain suggests alternative slots:

{
  "action": "suggest",
  "success": false,
  "humanReadable": "10:00 AM on Monday, 02.03 is taken. Alternatively: 11:00 AM, 2:00 PM or 3:00 PM",
  "result": "requested time not available but 3 alternative time slots available",
  "day": "Monday",
  "date": "02.03",
  "time1": "11:00",
  "time2": "14:00",
  "time3": "15:00"
}

A single alternative comes back as time; multiple as time1, time2, time3. How many alternatives are offered is controlled via Max. suggestions on your assistant's Appointments & calendars tab.

Response — No Availability

When the day is fully booked or closed (e.g. a closed day or a public holiday), humanReadable explains the reason:

{
  "action": "reject",
  "success": false,
  "humanReadable": "Friday, 25.12 is a public holiday",
  "result": "Public holiday",
  "day": "Friday",
  "date": "25.12",
  "time": "10:00"
}

Response — Follow-up Question

With action: "clarify", the API signals that something is missing or unclear — for example when the query wasn't understood, a weekday could mean this week or next, the service wasn't found, or the calendar requires a service to be selected. humanReadable contains the matching follow-up question for your voice bot to read out.

Natural Language Examples

The query field accepts free text in German or English:

"nächsten Montag"
"morgen um 14 Uhr"
"next week Tuesday"
"tomorrow afternoon"
"Haben Sie am Freitag noch etwas frei?"
"Do you have anything on Friday?"

Notes

humanReadable is meant to be read out directly by your voice bot
With query, the API responds in the language the query is written in; with requestedDateTime, language sets the language
Alternative suggestions take appointment duration, slot increment, buffer time, and minimum lead time into account
If Google Calendar is temporarily unreachable, the API responds with action: "clarify" and a corresponding notice instead of assuming the calendar is free