GET

List Appointments in Date Range

Returns a paginated list of appointments in a sub-account, filterable by date range, calendar, Agent, and status.

GEThttps://api.vantaxai.com/v1/appointments

Appointments are returned newest-first by `appointment_date`. Use `start_date` and `end_date` (ISO-8601) to scope results to a window — for example, everything booked this week — and pass `calendar_id` to focus on a single calendar. You can also narrow by the `agent_id` that booked the appointment or by `status`. Page through large result sets with the `limit` and `starting_after` cursor parameters.

Scoping a calendar view

Combine `start_date`/`end_date` with `calendar_id` to render a day or week view for a single calendar, and add `agent_id` to see only the bookings a given Agent generated. Omitting the date range returns the most recent appointments across the whole sub-account.

Headers

Authorizationstringrequired
Bearer authentication with your secret API key.
example: Bearer vx_live_3fa9c2…

Query Parameters

sub_account_idstringrequired
The sub-account to list appointments for.
example: sub_8a1f4c2e
start_datestringoptional
Only return appointments at or after this ISO-8601 timestamp (inclusive).
example: 2026-06-08T00:00:00Z
end_datestringoptional
Only return appointments at or before this ISO-8601 timestamp (inclusive).
example: 2026-06-14T23:59:59Z
calendar_idstringoptional
Restrict results to a single calendar.
example: cal_22f9
agent_idstringoptional
Filter to appointments booked by a specific Agent.
example: agt_3d9b21
statusstringoptional
Filter by appointment status.
scheduledconfirmedcompletedcancelledno_show
example: confirmed
limitintegeroptional
Number of records to return (1–100). Defaults to 20.
example: 20
starting_afterstringoptional
Cursor for pagination — an appointment id to start after.
example: appt_7c1d90

Request

curl -G https://api.vantaxai.com/v1/appointments \
  -H "Authorization: Bearer vx_live_3fa9c2..." \
  --data-urlencode "sub_account_id=sub_8a1f4c2e" \
  --data-urlencode "start_date=2026-06-08T00:00:00Z" \
  --data-urlencode "end_date=2026-06-14T23:59:59Z" \
  --data-urlencode "calendar_id=cal_22f9"

const params = new URLSearchParams({
  sub_account_id: "sub_8a1f4c2e",
  start_date: "2026-06-08T00:00:00Z",
  end_date: "2026-06-14T23:59:59Z",
  calendar_id: "cal_22f9",
});
const res = await fetch(
  `https://api.vantaxai.com/v1/appointments?${params}`,
  { headers: { Authorization: "Bearer vx_live_3fa9c2..." } }
);
const { data: appointments } = await res.json();

import { Vantax } from "@vantax/sdk";

const vantax = new Vantax({ apiKey: process.env.VANTAX_API_KEY! });
const appointments = await vantax.appointments.list({
  subAccountId: "sub_8a1f4c2e",
  startDate: "2026-06-08T00:00:00Z",
  endDate: "2026-06-14T23:59:59Z",
  calendarId: "cal_22f9",
});

from vantax import Vantax

vantax = Vantax(api_key=os.environ["VANTAX_API_KEY"])
appointments = vantax.appointments.list(
    sub_account_id="sub_8a1f4c2e",
    start_date="2026-06-08T00:00:00Z",
    end_date="2026-06-14T23:59:59Z",
    calendar_id="cal_22f9",
)

Response

{
  "success": true,
  "data": [
    {
      "id": "appt_7c1d90",
      "contact_id": "ct_4f8a21",
      "calendar_id": "cal_22f9",
      "agent_id": "agt_3d9b21",
      "title": "Dental cleaning consultation",
      "description": "New patient — requested morning slot",
      "appointment_date": "2026-06-09T15:00:00Z",
      "duration": 30,
      "status": "confirmed",
      "location": "Downtown Clinic, Suite 200",
      "created_at": "2026-06-08T09:12:00Z"
    },
    {
      "id": "appt_3b02ee",
      "contact_id": "ct_9c11d4",
      "calendar_id": "cal_22f9",
      "agent_id": "agt_3d9b21",
      "title": "Follow-up call",
      "description": null,
      "appointment_date": "2026-06-10T18:30:00Z",
      "duration": 15,
      "status": "scheduled",
      "location": "Phone",
      "created_at": "2026-06-08T11:47:00Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 20,
    "has_more": false
  }
}

{
  "success": true,
  "data": [
    {
      "id": "appt_7c1d90",
      "contact_id": "ct_4f8a21",
      "calendar_id": "cal_22f9",
      "agent_id": "agt_3d9b21",
      "title": "Dental cleaning consultation",
      "appointment_date": "2026-06-09T15:00:00Z",
      "duration": 30,
      "status": "confirmed",
      "location": "Downtown Clinic, Suite 200",
      "created_at": "2026-06-08T09:12:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "has_more": false
  }
}

{
  "success": false,
  "message": "Invalid or revoked API key"
}