Get Waitlist Request¶

Retrieve a specific patient waitlist request by ID, including patient details and matched invites.

Endpoint¶

GET /apis/v1/waitlist-requests/{id}

Patient users (USER role) can only retrieve their own requests. Attempting to access another patient's request returns 403.

Path Parameters¶

Parameter	Type	Required	Description
`id`	string (uuid)	Yes	Unique identifier of the waitlist request.

Query Parameters¶

Parameter	Type	Required	Description
`include_waitlists`	boolean	No	When `true`, includes full matched waitlist and invite details (slot times, status, timestamps). Defaults to `false`.

Request¶

curl --location '{base_url}/apis/v1/waitlist-requests/req-123?include_waitlists=true' \
  --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", "provider-678"],
    "preferred_provider_details": [
      { "id": "provider-345", "first_name": "Alex", "last_name": "Kim" }
    ],
    "preferred_time_slots": ["MORNING", "AFTERNOON"],
    "preferred_days": ["MONDAY", "WEDNESDAY", "FRIDAY"],
    "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",
        "status": "SENT",
        "match_type": "EXACT",
        "slot_start": "2026-05-20T15:00:00Z",
        "slot_end": "2026-05-20T16:00:00Z",
        "sent_at": "2026-05-16T10:00:00Z"
      }
    ],
    "matched_waitlists": [
      {
        "id": "waitlist-456",
        "provider_id": "provider-345",
        "slot_start": "2026-05-20T15:00:00Z",
        "slot_end": "2026-05-20T16:00:00Z",
        "status": "ACTIVE",
        "workflow_type": "BROADCAST"
      }
    ],
    "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"
  }
}

Response Fields¶

Field	Type	Description
`id`	string	Unique identifier of the waitlist request
`clinic_id`	string	Clinic where the patient wants the appointment
`patient_id`	string	Patient on whose behalf the request was created
`preferred_providers`	array	List of preferred provider IDs
`preferred_provider_details`	array	Enriched provider details
`preferred_time_slots`	array	Preferred parts of the day
`preferred_days`	array	Preferred days of the week
`date_range_start`	string (date)	Earliest search date (`YYYY-MM-DD`)
`date_range_end`	string (date)	Latest search date (`YYYY-MM-DD`)
`appointment_category_id`	string	Appointment category ID
`appointment_type`	string	`INITIAL_EVAL` or `FOLLOW_UP`
`appointment_duration`	integer	Appointment duration in minutes
`payment_type`	string	`SELF_PAY` or `INSURANCE_PAY`
`priority`	integer	Urgency 1-5
`status`	string	Request status: `ACTIVE`, `FULFILLED`, `CANCELLED`, or `EXPIRED`
`notes`	string	Free-text notes
`patient`	object	Patient details
`matched_invites`	array	Invite references. By default contains only `invite_id` and `waitlist_id`. When `include_waitlists=true`, also includes invite `status`, `match_type`, slot times, and timestamps.
`matched_waitlists`	array	Unique waitlist details, only present when `include_waitlists=true`. Deduplicated across invites.
`created_at`	string (date-time)	Creation timestamp (UTC)
`created_at_epoch_ms`	integer	Creation timestamp as epoch milliseconds
`updated_at`	string (date-time)	Last update timestamp (UTC)
`created_by`	string	User that created the request
`updated_by`	string	User that last updated the request

Error Response¶

Code: 404 Not Found

{
  "code": 4040,
  "message": "waitlist request not found",
  "data": null
}

Code: 403 Forbidden

{
  "code": 4030,
  "message": "forbidden",
  "data": null
}