Getting Appointments
Fetch one appointment by ID or search appointments with filters and pagination.
Showing instructions for Xebit VoiceCloud.Showing instructions for Xebit VoiceKit, on your own infrastructure. Switch with the selector at the top. Updated 22 October 2026.
Fetch a single appointment by its ID, or search your appointments with filters and pages, using the GET /v1/appointments endpoints.
Before you begin
Your key needs the appointments:read scope.
Create it in the Xebit VoiceCloud dashboard under Integrations → API Keys.
Create it in the Xebit VoiceKit admin console under Integrations → API Keys.
Get one appointment
/v1/appointments/{appointment_id}Requires appointments:read.
curl -s "https://api.voice.xebit.ai/v1/appointments/appt_a1b2c3d4e5" \
-H "x-api-key: $XEBIT_API_KEY"import os
import requests
BASE_URL = "https://api.voice.xebit.ai/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
appointment_id = "appt_a1b2c3d4e5"
response = requests.get(
f"{BASE_URL}/appointments/{appointment_id}",
headers={"x-api-key": API_KEY}
)
print(response.status_code, response.json())const BASE_URL = "https://api.voice.xebit.ai/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const appointmentId = "appt_a1b2c3d4e5";
const response = await fetch(`${BASE_URL}/appointments/${appointmentId}`, {
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());curl -s "https://<your-xebit-voicekit-host>/v1/appointments/appt_a1b2c3d4e5" \
-H "x-api-key: $XEBIT_API_KEY"import os
import requests
BASE_URL = "https://<your-xebit-voicekit-host>/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
appointment_id = "appt_a1b2c3d4e5"
response = requests.get(
f"{BASE_URL}/appointments/{appointment_id}",
headers={"x-api-key": API_KEY}
)
print(response.status_code, response.json())const BASE_URL = "https://<your-xebit-voicekit-host>/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const appointmentId = "appt_a1b2c3d4e5";
const response = await fetch(`${BASE_URL}/appointments/${appointmentId}`, {
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());Response, 200 OK:
{
"success": true,
"data": {
"appointment_id": "appt_a1b2c3d4e5",
"appointment_type": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"branch_id": "branch_uuid_here",
"date": "2026-06-15",
"session": "Morning",
"batch": "MA",
"token": null,
"patient_name": "Aadhi",
"parent_phone": "+919840XXXXXX",
"assigned_doctor": null,
"status": "confirmed",
"external_reference_id": null,
"created_at": "2026-05-26T10:00:00.000Z",
"updated_at": "2026-05-26T10:00:00.000Z"
}
}Returns 404 NOT_FOUND when no appointment with that ID exists in your organisation.
Search appointments
/v1/appointmentsRequires appointments:read. Every query parameter is optional. Results are ordered by appointment date, earliest first.
| Name | Type | Required | Description |
|---|---|---|---|
date | string | No | Date, YYYY-MM-DD. Matches the whole day in UTC. |
status | string | No | confirmed, rescheduled, cancelled or completed. |
appointment_type | string | No | Service UUID. |
branch_id | string | No | Branch UUID. |
session | string | No | Morning, Afternoon or Evening. |
batch | string | No | Batch label, for example "MA". |
page | integer | No | Page number. Defaults to 1. |
limit | integer | No | Results per page. Defaults to 50, maximum 200. |
curl -s "https://api.voice.xebit.ai/v1/appointments?date=2026-06-15&session=Morning&page=1&limit=50" \
-H "x-api-key: $XEBIT_API_KEY"import os
import requests
BASE_URL = "https://api.voice.xebit.ai/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
response = requests.get(
f"{BASE_URL}/appointments",
headers={"x-api-key": API_KEY},
params={
"date": "2026-06-15",
"session": "Morning",
"page": 1,
"limit": 50
}
)
print(response.status_code, response.json())const BASE_URL = "https://api.voice.xebit.ai/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const params = new URLSearchParams({
date: "2026-06-15",
session: "Morning",
page: "1",
limit: "50"
});
const response = await fetch(`${BASE_URL}/appointments?${params}`, {
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());curl -s "https://<your-xebit-voicekit-host>/v1/appointments?date=2026-06-15&session=Morning&page=1&limit=50" \
-H "x-api-key: $XEBIT_API_KEY"import os
import requests
BASE_URL = "https://<your-xebit-voicekit-host>/v1"
API_KEY = os.environ["XEBIT_API_KEY"]
response = requests.get(
f"{BASE_URL}/appointments",
headers={"x-api-key": API_KEY},
params={
"date": "2026-06-15",
"session": "Morning",
"page": 1,
"limit": 50
}
)
print(response.status_code, response.json())const BASE_URL = "https://<your-xebit-voicekit-host>/v1";
const API_KEY = process.env.XEBIT_API_KEY;
const params = new URLSearchParams({
date: "2026-06-15",
session: "Morning",
page: "1",
limit: "50"
});
const response = await fetch(`${BASE_URL}/appointments?${params}`, {
headers: { "x-api-key": API_KEY }
});
console.log(response.status, await response.json());Response, 200 OK:
{
"success": true,
"data": [
{
"appointment_id": "appt_a1b2c3d4e5",
"appointment_type": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"branch_id": "branch_uuid_here",
"date": "2026-06-15",
"session": "Morning",
"batch": "MA",
"token": null,
"patient_name": "Aadhi",
"parent_phone": "+919840XXXXXX",
"assigned_doctor": null,
"status": "confirmed",
"external_reference_id": null,
"created_at": "2026-05-26T10:00:00.000Z",
"updated_at": "2026-05-26T10:00:00.000Z"
}
],
"pagination": {
"total": 1,
"page": 1,
"limit": 50,
"total_pages": 1
}
}Error codes
| Status | Code | Cause |
|---|---|---|
404 | NOT_FOUND | Appointment not found (single fetch only). |
403 | INSUFFICIENT_SCOPE | The key lacks appointments:read. |