Skip to main content
POST
/
api
/
v1
/
ghl
/
appointments
/
manage
Manage GHL Appointment
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 '
{
  "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
}
'
{
  "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 operation to perform. Use values such as create, reschedule, cancel, or list, depending on the appointment workflow.
​
agent_id
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.
​
org_id
string
required
The organization ID that owns the resource. Use the organization ID from your Agni account.
​
name
string
The customer’s full name for the appointment.
​
email
string
The contact email address. Use a valid email format such as alex@example.com.
​
phone
string
The contact phone number in E.164 format. Example: +14157774444.
​
appointment_datetime
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.
​
appointment_id
string
The unique appointment ID. Use the ID returned when the appointment was created or listed.
​
call_session_id
string
The unique call session ID associated with the conversation or appointment. Use it to connect call activity with follow-up actions.
​
notes
string
Additional notes for the appointment, contact, or call. These notes can include context for follow-up.
​
days_ahead
integer
The number of days ahead to search for available appointment slots.

​
Response

​
success
boolean
Whether the request succeeded.
​
message
string
Natural language message to relay directly to the user
​
data
object
data field.
{
  "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)

​
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

Successful response

​
success
boolean
​
message
string

Natural language message to relay directly to the user

​
data
object