Book, Cancel, Reschedule & Callback

API reference for booking, cancelling, rescheduling appointments, and requesting callbacks via FlowCaptain.

Book, Cancel, Reschedule & Callback

Four endpoints for the complete appointment lifecycle.

Book Appointment

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

POST /api/v1/book-appointment

Request Body:

{
  "query": "Monday, March 3rd at 10 AM",
  "callerName": "Max Mustermann",
  "callerPhone": "+491761234567",
  "callerIdNumber": "+491761234567",
  "description": "Initial consultation"
}

Field	Type	Required	Description
query	string	Yes	Natural language date/time for the appointment
callerName	string	Yes	Name of the person booking
callerPhone	string	No	Phone number (for notifications)
callerIdNumber	string	No	Caller ID from telephony (for appointment lookup)
description	string	No	Appointment description

Success Response:

{
  "message": "Your appointment on Monday, March 3rd at 10:00 has been booked.",
  "status": "booked",
  "appointment": {
    "date": "2026-03-03",
    "time": "10:00",
    "day": "Monday",
    "callerName": "Max Mustermann"
  }
}

Cancel Appointment

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

POST /api/v1/cancel-appointment

Request Body:

{
  "query": "my appointment on Monday",
  "callerName": "Max Mustermann",
  "callerIdNumber": "+491761234567"
}

Field	Type	Required	Description
query	string	Yes	Natural language description of which appointment to cancel
callerName	string	No	Helps identify the appointment
callerIdNumber	string	No	Caller ID for lookup

FlowCaptain uses multiple identifiers to find the correct appointment. The more information provided (caller ID, name, date), the more reliable the match.

Success Response:

{
  "message": "Your appointment on Monday, March 3rd at 10:00 has been cancelled.",
  "status": "cancelled"
}

Reschedule Appointment

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

POST /api/v1/reschedule-appointment

Request Body:

{
  "query": "move my Monday appointment to Tuesday at 2 PM",
  "callerName": "Max Mustermann",
  "callerIdNumber": "+491761234567"
}

Field	Type	Required	Description
query	string	Yes	Natural language request with desired new time
callerName	string	No	Helps identify the appointment
callerIdNumber	string	No	Caller ID for lookup

Success Response:

{
  "message": "Your appointment has been moved to Tuesday, March 4th at 14:00.",
  "status": "rescheduled",
  "appointment": {
    "date": "2026-03-04",
    "time": "14:00",
    "day": "Tuesday"
  }
}

Request 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:

{
  "callerName": "Max Mustermann",
  "callerPhone": "+491761234567",
  "issueDescription": "Would like a callback",
  "language": "en"
}

Field	Type	Required	Description
callerName	string	No*	Caller's name
callerPhone	string	No*	Caller's phone number
callerIdNumber	string	No*	Caller ID from telephony
issueDescription	string	No	Brief description of the issue
language	string	No	"de" or "en" (default: "de")

*At least one of callerName, callerPhone, or callerIdNumber is required.

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 prevent abuse.

Common Error Responses

Appointment not found:

{
  "message": "No appointment found matching your request.",
  "status": "not_found"
}

New time not available (rescheduling):

{
  "message": "Tuesday at 2 PM is not available. Alternatives: Tuesday at 3 PM, Wednesday at 10 AM.",
  "status": "unavailable"
}