Manage Cal.com Appointment
curl --request POST \
--url https://api.ravan.ai/api/v1/calcom/appointments/manage \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"agent_id": "<string>",
"org_id": "<string>",
"name": "<string>",
"email": "<string>",
"phone": "<string>",
"appointment_datetime": "<string>",
"appointment_id": "<string>",
"call_session_id": "<string>",
"notes": "<string>",
"days_ahead": 123
}
'import requests
url = "https://api.ravan.ai/api/v1/calcom/appointments/manage"
payload = {
"agent_id": "<string>",
"org_id": "<string>",
"name": "<string>",
"email": "<string>",
"phone": "<string>",
"appointment_datetime": "<string>",
"appointment_id": "<string>",
"call_session_id": "<string>",
"notes": "<string>",
"days_ahead": 123
}
headers = {
"X-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_id: '<string>',
org_id: '<string>',
name: '<string>',
email: '<string>',
phone: '<string>',
appointment_datetime: '<string>',
appointment_id: '<string>',
call_session_id: '<string>',
notes: '<string>',
days_ahead: 123
})
};
fetch('https://api.ravan.ai/api/v1/calcom/appointments/manage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ravan.ai/api/v1/calcom/appointments/manage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agent_id' => '<string>',
'org_id' => '<string>',
'name' => '<string>',
'email' => '<string>',
'phone' => '<string>',
'appointment_datetime' => '<string>',
'appointment_id' => '<string>',
'call_session_id' => '<string>',
'notes' => '<string>',
'days_ahead' => 123
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Api-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.ravan.ai/api/v1/calcom/appointments/manage"
payload := strings.NewReader("{\n \"agent_id\": \"<string>\",\n \"org_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"phone\": \"<string>\",\n \"appointment_datetime\": \"<string>\",\n \"appointment_id\": \"<string>\",\n \"call_session_id\": \"<string>\",\n \"notes\": \"<string>\",\n \"days_ahead\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.ravan.ai/api/v1/calcom/appointments/manage")
.header("X-Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"agent_id\": \"<string>\",\n \"org_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"phone\": \"<string>\",\n \"appointment_datetime\": \"<string>\",\n \"appointment_id\": \"<string>\",\n \"call_session_id\": \"<string>\",\n \"notes\": \"<string>\",\n \"days_ahead\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ravan.ai/api/v1/calcom/appointments/manage")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"agent_id\": \"<string>\",\n \"org_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"phone\": \"<string>\",\n \"appointment_datetime\": \"<string>\",\n \"appointment_id\": \"<string>\",\n \"call_session_id\": \"<string>\",\n \"notes\": \"<string>\",\n \"days_ahead\": 123\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "Appointment confirmed successfully",
"data": {
"success": true,
"message": "Booked successfully",
"summary": "Appointment confirmed",
"action": "book",
"appointment_id": "appt_123",
"date_time": "2026-03-20T14:00:00Z",
"agent_name": "Dr. Rivera",
"action_required": "",
"available_slots": [
{
"date": "2026-03-21",
"date_label": "Tomorrow",
"slots": [
"9:00 AM",
"11:30 AM"
]
}
]
}
}
Appointment API
Manage Cal.com Appointment
Manage an appointment request for the AI agent; no X-Api-Key is required, and org_id is provided in the request body.
POST
/
api
/
v1
/
calcom
/
appointments
/
manage
Manage Cal.com Appointment
curl --request POST \
--url https://api.ravan.ai/api/v1/calcom/appointments/manage \
--header 'Content-Type: application/json' \
--header 'X-Api-Key: <api-key>' \
--data '
{
"agent_id": "<string>",
"org_id": "<string>",
"name": "<string>",
"email": "<string>",
"phone": "<string>",
"appointment_datetime": "<string>",
"appointment_id": "<string>",
"call_session_id": "<string>",
"notes": "<string>",
"days_ahead": 123
}
'import requests
url = "https://api.ravan.ai/api/v1/calcom/appointments/manage"
payload = {
"agent_id": "<string>",
"org_id": "<string>",
"name": "<string>",
"email": "<string>",
"phone": "<string>",
"appointment_datetime": "<string>",
"appointment_id": "<string>",
"call_session_id": "<string>",
"notes": "<string>",
"days_ahead": 123
}
headers = {
"X-Api-Key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'X-Api-Key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
agent_id: '<string>',
org_id: '<string>',
name: '<string>',
email: '<string>',
phone: '<string>',
appointment_datetime: '<string>',
appointment_id: '<string>',
call_session_id: '<string>',
notes: '<string>',
days_ahead: 123
})
};
fetch('https://api.ravan.ai/api/v1/calcom/appointments/manage', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.ravan.ai/api/v1/calcom/appointments/manage",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'agent_id' => '<string>',
'org_id' => '<string>',
'name' => '<string>',
'email' => '<string>',
'phone' => '<string>',
'appointment_datetime' => '<string>',
'appointment_id' => '<string>',
'call_session_id' => '<string>',
'notes' => '<string>',
'days_ahead' => 123
]),
CURLOPT_HTTPHEADER => [
"Content-Type: application/json",
"X-Api-Key: <api-key>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.ravan.ai/api/v1/calcom/appointments/manage"
payload := strings.NewReader("{\n \"agent_id\": \"<string>\",\n \"org_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"phone\": \"<string>\",\n \"appointment_datetime\": \"<string>\",\n \"appointment_id\": \"<string>\",\n \"call_session_id\": \"<string>\",\n \"notes\": \"<string>\",\n \"days_ahead\": 123\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("X-Api-Key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.ravan.ai/api/v1/calcom/appointments/manage")
.header("X-Api-Key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"agent_id\": \"<string>\",\n \"org_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"phone\": \"<string>\",\n \"appointment_datetime\": \"<string>\",\n \"appointment_id\": \"<string>\",\n \"call_session_id\": \"<string>\",\n \"notes\": \"<string>\",\n \"days_ahead\": 123\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.ravan.ai/api/v1/calcom/appointments/manage")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["X-Api-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"agent_id\": \"<string>\",\n \"org_id\": \"<string>\",\n \"name\": \"<string>\",\n \"email\": \"<string>\",\n \"phone\": \"<string>\",\n \"appointment_datetime\": \"<string>\",\n \"appointment_id\": \"<string>\",\n \"call_session_id\": \"<string>\",\n \"notes\": \"<string>\",\n \"days_ahead\": 123\n}"
response = http.request(request)
puts response.read_body{
"success": true,
"message": "Appointment confirmed successfully",
"data": {
"success": true,
"message": "Booked successfully",
"summary": "Appointment confirmed",
"action": "book",
"appointment_id": "appt_123",
"date_time": "2026-03-20T14:00:00Z",
"agent_name": "Dr. Rivera",
"action_required": "",
"available_slots": [
{
"date": "2026-03-21",
"date_label": "Tomorrow",
"slots": [
"9:00 AM",
"11:30 AM"
]
}
]
}
}
Body
string
required
The appointment operation to perform. Use values such as
create, reschedule, cancel, or list, depending on the appointment workflow.string
required
The unique ID of the agent that should own, handle, or be assigned to this resource. Use the
id returned by the Agent API.string
required
The organization ID that owns the resource. Use the organization ID from your Agni account.
string
The customer’s full name for the appointment.
string
The contact email address. Use a valid email format such as
alex@example.com.string
The contact phone number in E.164 format. Example:
+14157774444.string
The appointment date and time in ISO 8601 format. Include a timezone offset when possible, for example
2026-03-14T15:00:00+05:30.string
The unique appointment ID. Use the ID returned when the appointment was created or listed.
string
The unique call session ID associated with the conversation or appointment. Use it to connect call activity with follow-up actions.
string
Additional notes for the appointment, contact, or call. These notes can include context for follow-up.
integer
The number of days ahead to search for available appointment slots.
Response
boolean
Whether the request succeeded.
string
Natural language message to relay directly to the user
object
data field.
Show data
Show data
boolean
success field.
string
message field.
string
Short label (e.g. Appointment confirmed, Cancelled, Rescheduled)
string
The action that was performed
string
Appointment ID (returned for book, reschedule, cancel)
string
Confirmed appointment datetime in ISO 8601
string
Name of the agent handling the appointment
string
Next action required if the request could not be completed (e.g. reschedule)
{
"success": true,
"message": "Appointment confirmed successfully",
"data": {
"success": true,
"message": "Booked successfully",
"summary": "Appointment confirmed",
"action": "book",
"appointment_id": "appt_123",
"date_time": "2026-03-20T14:00:00Z",
"agent_name": "Dr. Rivera",
"action_required": "",
"available_slots": [
{
"date": "2026-03-21",
"date_label": "Tomorrow",
"slots": [
"9:00 AM",
"11:30 AM"
]
}
]
}
}
{
"success": false,
"message": "Requested slot is unavailable",
"error": {
"code": "SLOT_UNAVAILABLE",
"message": "The selected time is no longer available",
"details": {
"summary": "Please choose a different slot",
"action": "book",
"action_required": "reschedule",
"agent_name": "Dr. Rivera",
"available_slots": [
{
"date": "2026-03-21",
"date_label": "Tomorrow",
"slots": [
"10:00 AM",
"1:00 PM"
]
},
{
"date": "2026-03-22",
"date_label": "Friday",
"slots": [
"9:30 AM",
"3:00 PM"
]
}
]
}
}
}
Authorizations
Body
application/json
The appointment action to perform
Available options:
book, reschedule, cancel, suggest, availability UUID of the agent handling the appointment
UUID of the organization
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.