Book, Cancel & Reschedule

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

Book, Cancel & Reschedule

Three endpoints for managing the full appointment lifecycle.

Book Appointment

Create a new appointment on the connected Google Calendar.

POST /api/v1/book-appointment

Request Body:

{
  "query": "Monday March 3rd at 10am",
  "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 (used for notifications)
callerIdNumber	string	No	Caller ID from telephony (used for 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

Cancel an existing appointment. The event is marked as cancelled in Google Calendar but not deleted.

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 (most reliable)

Lookup Order: The API finds the appointment using this cascade: callerIdNumber, then callerPhone, then callerName, then date. If one method misses (e.g. different phone), the next is tried silently.

Success Response:

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

Reschedule Appointment

Move an existing appointment to a new time. The API checks availability at the new time before rescheduling.

POST /api/v1/reschedule-appointment

Request Body:

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

Field	Type	Required	Description
query	string	Yes	Natural language request including new desired 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"
  }
}

Common Error Responses

Appointment not found:

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

New time not available (reschedule):

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