Book, Cancel, Reschedule & Callback

Book, Cancel, Reschedule & Callback

Four endpoints covering the full appointment lifecycle.

Each of the following requests requires calendarId as a field in the JSON body. You can find it pre-filled under Dashboard → Calendar → API → Integration Guide. 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.

Book an Appointment

Creates a new appointment in the connected Google Calendar. FlowCaptain automatically verifies that the requested slot is actually available before booking.

POST /api/v1/book-appointment

Request body:

{
  "calendarId": "YOUR_CALENDAR_ID",
  "dateTime": "2026-03-03T10:00:00+01:00",
  "callerName": "Max Mustermann",
  "callerIdNumber": "+491761234567",
  "reason": "Initial consultation"
}

Success response:

{
  "action": "booked",
  "success": true,
  "humanReadable": "Your appointment on Monday, March 3rd at 10:00 AM has been booked.",
  "day": "Monday",
  "date": "2026-03-03",
  "time": "10:00",
  "appointmentId": "550e8400-e29b-41d4-a716-446655440000"
}

Slot taken: The response is action: "suggest" with alternative suggestions (time1–time3) — same as the availability check.

Approval enabled: If the calendar uses Require Approval, the response is action: "pending_approval" instead of booked — the appointment is entered as a request and only becomes final once the calendar owner approves it.

Cancel an Appointment

Cancels an existing appointment. The event is marked as cancelled in Google Calendar but not deleted — so it remains visible for your records.

POST /api/v1/cancel-appointment

Request body:

{
  "calendarId": "YOUR_CALENDAR_ID",
  "callerIdNumber": "+491761234567",
  "callerName": "Max Mustermann",
  "appointmentDate": "2026-03-03"
}

*FlowCaptain uses multiple attributes to identify the right appointment. The more information you pass (caller ID, name, date), the more reliable the match. If several appointments match, the API responds with action: "clarify" and an appointments[] list for follow-up.

Success response:

{
  "action": "cancelled",
  "success": true,
  "humanReadable": "Your appointment on Monday, March 3rd at 10:00 AM has been cancelled."
}

SMS verification: If the Verification Code is enabled on the calendar, the API requires a code before cancelling:

{
  "action": "verification_required",
  "success": false,
  "verificationPhone": "***4567"
}

The code is sent via SMS to the number on file. Repeat the request with the verificationCode field. A wrong code results in action: "verification_failed".

Reschedule an Appointment

Moves an existing appointment to a new time. FlowCaptain verifies availability at the new time before rescheduling.

POST /api/v1/reschedule-appointment

Request body:

{
  "calendarId": "YOUR_CALENDAR_ID",
  "callerIdNumber": "+491761234567",
  "callerName": "Max Mustermann",
  "newDateTime": "2026-03-04T14:00:00+01:00"
}

*Appointment lookup and SMS verification work the same as for cancellation.

Success response:

{
  "action": "rescheduled",
  "success": true,
  "humanReadable": "Your appointment has been moved to Tuesday, March 4th at 2:00 PM.",
  "day": "Tuesday",
  "date": "2026-03-04",
  "time": "14:00",
  "previousDay": "Monday",
  "previousDate": "2026-03-03",
  "previousTime": "10:00"
}

New time taken: The response is action: "suggest" with alternative suggestions.

Request a Callback

Requests a callback from the business owner when the voice bot cannot resolve the caller's issue.

POST /api/v1/request-callback

Request body:

{
  "calendarId": "YOUR_CALENDAR_ID",
  "callerName": "Max Mustermann",
  "callerPhone": "+491761234567",
  "issueDescription": "Wants a callback",
  "language": "en"
}

*Pass at least one of callerName, callerPhone, or callerIdNumber so the business can call back.

Success response:

{
  "action": "callback_requested",
  "success": true,
  "humanReadable": "Callback request submitted"
}

The business owner receives an email with the caller's contact details. Callback requests are rate-limited to protect against abuse (5 per business per hour, 2 per caller per hour).