Manage GHL 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/ghl/appointments/manage

Manage GHL Appointment

cURL

curl --request POST \
  --url https://api.ravan.ai/api/v1/ghl/appointments/manage \
  --header 'Content-Type: application/json' \
  --header 'X-Api-Key: <api-key>' \
  --data '
{
  "action": "book",
  "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
}
'

200

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

action · string · required

The appointment action to perform. Required for all requests. Allowed values: book, reschedule, cancel, suggest, availability. For cancel and reschedule, provide appointment_id. For book, provide name, and either email or phone. For suggest and availability, use days_ahead to control the search window.

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

success · boolean

Whether the request succeeded.

message · string

Natural language message to relay directly to the user

data · object

data field.

Show data

success · boolean

success field.

message · string

message field.

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)

Show available_slots[]

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)

200

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

422

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

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<int32>

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

Response

200

application/json

Successful response

success · boolean

message · string

Natural language message to relay directly to the user

data · object

Show child attributes