---
title: "Manage Cal.com Appointment"
method: POST
path: "/api/v1/calcom/appointments/manage"
tags: ["AppointmentService"]
---

# Manage Cal.com Appointment

`POST /api/v1/calcom/appointments/manage`

Unified appointment management endpoint for Cal.com. Supports book, reschedule, cancel, suggest, and availability actions. No X-Api-Key required — org_id comes from the request body.

## Request body

- ManageAppointmentRequest
  - `action` 'book' | 'reschedule' | 'cancel' | 'suggest' | 'availability', required — The appointment action to perform
  - `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)
  - `email` 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 — Days ahead to look for available slots (default: 7, max: 30). Used for suggest and availability.

## Response `200`

Successful response

- ManageAppointmentResponse
  - `success` boolean
  - `message` string — Natural language message to relay directly to the user
  - `data` object
    - `success` boolean
    - `message` string
    - `summary` string — Short label (e.g. Appointment confirmed, Cancelled, Rescheduled)
    - `action` string — The action that was performed
    - `appointment_id` string — Appointment ID (returned for book, reschedule, cancel)
    - `date_time` string — Confirmed appointment datetime in ISO 8601
    - `agent_name` string — Name of the agent handling the appointment
    - `action_required` string — Next action required if the request could not be completed (e.g. reschedule)
    - `available_slots` object[] — Available time slots grouped by date (returned for suggest, availability, and slot-unavailable responses)
      - `date` string — Date in YYYY-MM-DD format
      - `date_label` string — Human-readable date label (e.g. Today, Tomorrow)
      - `slots` string[] — Available time slots (e.g. 9:00 AM)

## Other responses

- `422` — Slot unavailable

---

[API](https://skmtc.net/ravan/apis/agni-api.md) · [All operations](https://skmtc.net/ravan/apis/agni-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ravan/agni-api/revisions/48f45dc58534/schema)