This endpoint does not require the X-Api-Key header. Instead, provide the org_id in the request body for authentication.
Body The appointment action to perform. Allowed values:
book — Book a new appointment (requires name and either email or phone).reschedule — Reschedule an existing appointment (requires appointment_id and appointment_datetime).cancel — Cancel an existing appointment (requires appointment_id).suggest — Get suggested available time slots.availability — Check all available slots for a date range. UUID of the AI agent handling the appointment.
UUID of your organization — used for authentication instead of an API key.
Customer’s full name. Required when action is book.
Customer’s email address. Required for book if phone is not provided.
Customer’s phone number in E.164 format. Required for book if email is not provided.
Customer’s IANA timezone (e.g. America/New_York, Europe/London). Used to display and confirm appointment times in the customer’s local time.
Desired appointment date and time in ISO 8601 format (e.g. 2026-03-25T14:00:00Z). Required for book and reschedule.
Existing appointment ID. Required for cancel and reschedule.
Call session ID to associate with the booking (optional, for tracking purposes).
Optional notes to attach to the appointment.
Number of days ahead to search for available slots (default: 7, max: 30). Used with suggest and availability actions.
Response Whether the request succeeded.
Natural language message suitable for relaying directly to the customer.
Appointment result data. Whether the appointment action was successful.
Short label (e.g. "Appointment confirmed", "Cancelled", "Rescheduled").
The action that was performed.
Appointment ID (returned for book, reschedule, cancel).
Confirmed appointment datetime in ISO 8601 format.
Name of the agent or calendar owner handling the appointment.
Next action required if the request could not be fully completed (e.g. "reschedule").
Available time slots grouped by date. Date in YYYY-MM-DD format.
Human-readable date label (e.g. "Today", "Tomorrow").
Array of available time strings (e.g. ["9:00 AM", "11:30 AM"]).
cURL (book)
Python
JavaScript
curl -X POST https://api.ravan.ai/api/v1/calcom/appointments/manage \ -H "Content-Type: application/json" \ -d '{ "action": "book", "agent_id": "019d1fdb-98e9-7c87-86c7-321e2fa98733", "org_id": "1268c1f0-19f3-47db-aefb-c16a7c3ace6e", "name": "Jane Doe", "email": "jane@example.com", "appointment_datetime": "2026-03-25T14:00:00Z" }'
{ "success" : true , "message" : "Appointment confirmed successfully" , "data" : { "success" : true , "message" : "Booked successfully" , "summary" : "Appointment confirmed" , "action" : "book" , "appointment_id" : "appt_a1b2c3d4e5" , "date_time" : "2026-03-25T14:00:00Z" , "agent_name" : "Dr. Rivera" , "action_required" : "" , "available_slots" : [] } }
The appointment action to perform
Available options:
book,
reschedule,
cancel,
suggest,
availability
UUID of the agent handling the appointment
Customer full name (required for book)
Customer email (required for book if no phone)
Customer phone in E.164 format (required for book if no email)
ISO 8601 datetime for book or reschedule
Existing appointment ID (required for cancel and reschedule)
Optional call session ID for book
Optional notes for the appointment
Days ahead to look for available slots (default: 7, max: 30). Used for suggest and availability.
Customer IANA timezone (e.g. America/New_York)
Natural language message to relay directly to the user
