---
title: "List appointments"
method: GET
path: "/v2/appointments"
tags: ["Appointments"]
---

# List appointments

`GET /v2/appointments`

## Request

- Base URL: `https://api.carecycle.ai`
- URL: `https://api.carecycle.ai/v2/appointments`
- Auth: API key in header `x-api-key`

List your organization's appointments.

## Query parameters

- `startDate` string, date-time
- `endDate` string, date-time
- `member` string: Comma-separated member UUIDs. Filter to appointments assigned to any of these members. Include `unassigned` for appointments booked with the whole organization.
- `clientCustomerId` string, uuid
- `appointmentConfigId` string: Comma-separated appointment config UUIDs. Filter to appointments using any of these scheduling configs.
- `campaignId` string: Comma-separated campaign UUIDs. Filter to appointments originating from any of these campaigns.
- `status` string: Comma-separated status filter. Omit to return all statuses.
- `bookingSource` string: Comma-separated booking source filter
- `appointmentMode` string: Comma-separated appointment mode filter
- `search` string: Match the customer's first name, last name, or phone number
- `sort` 'asc' | 'desc'
- `limit` integer
- `cursor` string

## Response `200`

GET /v2/appointments Positive response

- GetV2AppointmentsPositiveResponse
  - `appointments` object[], required
    - `id` string, uuid, required
    - `startTime` string, date-time, required: Appointment start time. ISO 8601 timestamp
    - `endTime` string, date-time, required: Appointment end time. ISO 8601 timestamp
    - `timezone` string, required
    - `status` 'scheduled' | 'confirmed' | 'cancelled' | 'completed' | 'no_show', required
    - `title` string, nullable, required
    - `appointmentMode` 'phone_call' | 'in_person' | 'video_call' | 'agent_phone_call' | 'null', nullable, required
    - `appointmentConfigId` string, uuid, nullable, required
    - `bookingSource` 'ai_assistant' | 'manual' | 'scheduling_page' | 'null', nullable, required
    - `originCallId` string, uuid, nullable, required
    - `confirmedAt` string, date-time, nullable, required: Appointment confirmation time. ISO 8601 timestamp
    - `additionalNotes` string, nullable, required
    - `calendarEventId` string, nullable, required
    - `location` string, nullable, required
    - `meetingUrl` string, nullable, required
    - `cancelledAt` string, date-time, nullable, required: Appointment cancellation time. ISO 8601 timestamp
    - `cancellationReason` string, nullable, required
    - `createdAt` string, date-time, nullable, required: Appointment creation time. ISO 8601 timestamp
    - `updatedAt` string, date-time, nullable, required: Appointment last update time. ISO 8601 timestamp
    - `customer` object, nullable, required
      - `id` string, uuid, required
      - `firstName` string, nullable, required
      - `lastName` string, nullable, required
      - `callerId` string, required
    - `member` object, nullable, required
      - `id` string, uuid, required
      - `name` string, nullable, required
      - `image` string, nullable, required
    - `appointmentConfig` object, nullable, required
      - `id` string, uuid, required
      - `name` string, nullable, required
    - `campaign` object, nullable, required
      - `id` string, uuid, required
      - `name` string, nullable, required
    - `callbackAttempt` object, nullable
      - `callId` string, uuid, required
      - `attemptedAt` string, date-time, required
      - `status` 'attempted' | 'attempted_failed' | 'attempted_no_answer' | 'completed', required
      - `label` string, required
  - `total` integer, required
  - `nextCursor` string, nullable, required

## Other responses

- `400`: GET /v2/appointments Negative response 400
- `401`: GET /v2/appointments Negative response 401
- `403`: GET /v2/appointments Negative response 403
- `404`: GET /v2/appointments Negative response 404
- `409`: GET /v2/appointments Negative response 409
- `422`: GET /v2/appointments Negative response 422
- `429`: GET /v2/appointments Negative response 429
- `500`: GET /v2/appointments Negative response 500
- `502`: GET /v2/appointments Negative response 502
- `503`: GET /v2/appointments Negative response 503

## Changes

- **2026-11-03** `9534fc3b0a65`: 1 info
  - added the new optional `query` request parameter `search`

[Operation history](https://skmtc.dev/carecycle/apis/carecycle-public-api/changes/v2/appointments/get.md)

---

[API](https://skmtc.dev/carecycle/apis/carecycle-public-api.md) - [All operations](https://skmtc.dev/carecycle/apis/carecycle-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/carecycle/apis/carecycle-public-api/revisions/9534fc3b0a65?raw)