List Waitlist Requests

Retrieve a paginated list of patient waitlist requests with optional filtering by clinic, patient, status, priority, providers, appointment type, and date range.

Endpoint

GET /apis/v1/waitlist-requests

Patient users (USER role) always see only their own requests; the patient_id query parameter is ignored for them and resolved from the JWT token.

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default 1, minimum 1).
page_size	integer	No	Items per page (default 20, max 100).
sort_by	string	No	Sort field. Allowed: created_at (default), updated_at, priority, date_range_start, date_range_end, available_slots.
sort_dir	string	No	Sort direction. Allowed: asc, desc (default).
clinic_id	string	No	Filter by clinic ID.
patient_id	string	No	Filter by patient ID. Clinician/staff only; ignored for patient users.
status	string	No	Filter by status. Allowed: ACTIVE, FULFILLED, CANCELLED, EXPIRED.
priority	integer	No	Filter by priority 1-5.
start_date	string (date)	No	Filter by request start date (YYYY-MM-DD).
end_date	string (date)	No	Filter by request end date (YYYY-MM-DD).
provider_ids	array	No	Filter by preferred provider IDs (comma-separated).
appointment_types	array	No	Filter by appointment types. Allowed values: INITIAL_EVAL, FOLLOW_UP.
appointment_categories	array	No	Filter by appointment category labels (comma-separated).
payment_type	string	No	Filter by payment type. Allowed: SELF_PAY, INSURANCE_PAY.
include_waitlists	boolean	No	When true, includes matched waitlist details and full invite details (slot times, status). Defaults to false.

Request

curl --location '{base_url}/apis/v1/waitlist-requests?clinic_id=clinic-123&status=ACTIVE&page=1&page_size=20' \
  --header 'Authorization: Bearer JWT_TOKEN'

Response

Success Response

Code: 200 OK

{
  "code": 2000,
  "message": "Success",
  "data": [
    {
      "id": "req-123",
      "clinic_id": "clinic-123",
      "patient_id": "patient-012",
      "preferred_providers": ["provider-345"],
      "preferred_time_slots": ["MORNING"],
      "preferred_days": ["MONDAY", "WEDNESDAY"],
      "date_range_start": "2026-05-15",
      "date_range_end": "2026-06-15",
      "appointment_category_id": "2058",
      "appointment_type": "INITIAL_EVAL",
      "appointment_duration": 60,
      "payment_type": "INSURANCE_PAY",
      "priority": 3,
      "status": "ACTIVE",
      "notes": "Patient prefers morning appointments",
      "patient": {
        "id": "patient-012",
        "first_name": "Jane",
        "last_name": "Doe"
      },
      "matched_invites": [
        { "invite_id": "invite-234", "waitlist_id": "waitlist-456" }
      ],
      "created_at": "2026-05-10T09:00:00Z",
      "created_at_epoch_ms": 1746867600000,
      "updated_at": "2026-05-10T09:00:00Z",
      "created_by": "user-123",
      "updated_by": "user-123"
    }
  ],
  "pagination": {
    "page": 1,
    "page_size": 20,
    "total": 1,
    "total_pages": 1
  }
}

Response Fields

Field	Type	Description
data	array	List of waitlist requests. Each item matches the shape returned by Get Waitlist Request.
pagination.page	integer	Current page number
pagination.page_size	integer	Number of items per page
pagination.total	integer	Total number of matching requests
pagination.total_pages	integer	Total number of pages

When include_waitlists=true, each request additionally includes matched_waitlists (deduplicated waitlist details) and full invite details inside matched_invites.

Error Response

Code: 400 Bad Request

{
  "code": 4000,
  "message": "invalid input",
  "data": null
}

Notes

• The default sort is created_at desc.
• include_waitlists=true performs additional lookups for waitlist and invite details; prefer it only when slot/status context is needed.