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"
        ]
      }
    ]
  }
}

POST

api

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

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)

object[]

Available time slots grouped by date (returned for suggest, availability, and slot-unavailable responses)

Show available_slots[]

string

Date in YYYY-MM-DD format

string

Human-readable date label (e.g. Today, Tomorrow)

string[]

Available time slots (e.g. 9:00 AM)

{
  "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

X-Api-Key

string

header

required

Body

application/json

action

enum<string>

required

The appointment action to perform

Available options:

book,

reschedule,

cancel,

suggest,

availability

agent_id

string

required

UUID of the agent handling the appointment

org_id

string

required

UUID of the organization

name

string

Customer full name (required for book)

string

Customer email (required for book if no phone)

phone

string

Customer phone in E.164 format (required for book if no email)

appointment_datetime

string

ISO 8601 datetime for book or reschedule

appointment_id

string

Existing appointment ID (required for cancel and reschedule)

call_session_id

string

Optional call session ID for book

notes

string

Optional notes for the appointment

days_ahead

integer<int32>

Days ahead to look for available slots (default: 7, max: 30). Used for suggest and availability.

Response

Successful response

success

boolean

message

string

Natural language message to relay directly to the user

data

object

Show child attributes

Introduction

Agent API

Organization API

Agent Tool API

Phone Number & Telephony API

Campaign API

Contact API

Calling API

Appointment API

GHL Integration API

Cal.com Integration API

RAG Knowledge Base API

Webhooks

Health API

Manage Cal.com Appointment

Body

Response

Authorizations

Body

Response

​Body

​Response

Authorizations

Body

Response

Body

Response