Check Availability

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

Check Availability

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 afternoon"
}

Field	Type	Required	Description
calendarId	string	Yes	Your calendar ID — determines which calendar the request targets
query	string	Yes	Natural language availability query (German or English)
requestedDateTime	string	No	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
language	string	No	`"de"` or `"en"` (default: `"de"`) — language of the response

calendarId is required on every request. You can find it pre-filled under Dashboard → Calendar → API → 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, March 3rd at 10:00 AM is available.",
  "day": "Monday",
  "date": "2026-03-03",
  "time": "10:00"
}

Response — Suggesting Alternatives

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

{
  "action": "suggest",
  "humanReadable": "10:00 AM is already taken. On Monday, 11:00, 14:00, or 15:00 would still be free.",
  "day": "Monday",
  "date": "2026-03-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 in the assistant settings.

Response — No Availability

When the day is fully booked or closed (including public holidays and closures), humanReadable explains the reason:

{
  "action": "reject",
  "humanReadable": "We're closed on Monday, October 3rd for German Unity Day."
}

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
The response language is controlled by the language parameter
Alternative suggestions take appointment duration, slot increment, buffer time, and minimum lead time into account
If Google Calendar is temporarily unreachable, the API returns an error instead of assuming the calendar is free