Create Waitlist Request¶

Create a new patient waitlist request describing the appointment a patient is willing to be matched against when slots become available.

Endpoint¶

POST /apis/v1/waitlist-requests

For patient users (USER role), patient_id is taken from the JWT token and the patient_id query parameter is ignored. For clinician/staff users, patient_id must be supplied as a query parameter.

Query Parameters¶

Parameter	Type	Required	Description
`patient_id`	string	Conditional	Patient ID. Required for clinician/staff requests; ignored for patient users.

Request Body¶

Parameter	Type	Required	Description
`clinic_id`	string	Yes	Clinic where the patient wants the appointment
`preferred_providers`	array	No	List of preferred provider IDs. Empty means any provider.
`preferred_time_slots`	array	No	Preferred parts of the day. Allowed values: `MORNING`, `AFTERNOON`, `EVENING`, `ANYTIME`.
`preferred_days`	array	No	Preferred days of the week. Allowed values: `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY`, `SUNDAY`.
`date_range_start`	string (date)	Yes	Earliest date for appointment search in `YYYY-MM-DD` format, interpreted in the clinic's timezone.
`date_range_end`	string (date)	Yes	Latest date for appointment search in `YYYY-MM-DD` format, interpreted in the clinic's timezone.
`appointment_category_id`	string	Yes	ID of the appointment category. Must be valid for the clinic.
`appointment_category`	string	No	Category label. If omitted, resolved from the category API.
`appointment_type`	string	No	Appointment type. Accepts `Initial Evaluation`, `Follow Up`, `INITIAL_EVAL`, or `FOLLOW_UP`. Derived from `appointment_category_id` if not provided.
`payment_type`	string	Yes	How the patient will pay. Allowed values: `SELF_PAY`, `INSURANCE_PAY`.
`priority`	integer	No	Urgency 1-5 (1 = highest). Defaults to `3`.
`notes`	string	No	Free-text notes about the request.

Request¶

curl --location '{base_url}/apis/v1/waitlist-requests' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
    "clinic_id": "clinic-123",
    "preferred_providers": ["provider-789", "provider-012"],
    "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_category": "Physical Therapy",
    "appointment_type": "Initial Evaluation",
    "payment_type": "INSURANCE_PAY",
    "priority": 3,
    "notes": "Patient prefers morning appointments"
  }'

Response¶

Success Response¶

Code: 201 Created

{
  "code": 2000,
  "message": "Success",
  "data": {
    "id": "req-123",
    "clinic_id": "clinic-123",
    "patient_id": "patient-012",
    "preferred_providers": ["provider-789", "provider-012"],
    "preferred_provider_details": [],
    "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"
    },
    "created_at": "2026-05-12T10:00:00Z",
    "created_at_epoch_ms": 1747044000000,
    "updated_at": "2026-05-12T10: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 (omitted if no providers are preferred)
`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	Resolved appointment type: `INITIAL_EVAL` or `FOLLOW_UP`
`appointment_duration`	integer	Appointment duration in minutes, derived from the category
`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
`created_at`	string (date-time)	Creation timestamp (UTC, RFC3339)
`created_at_epoch_ms`	integer	Creation timestamp as epoch milliseconds
`updated_at`	string (date-time)	Last update timestamp (UTC, RFC3339)
`created_by`	string	User that created the request
`updated_by`	string	User that last updated the request

Error Response¶

Code: 400 Bad Request

{
  "code": 4000,
  "message": "date_range_end must be on or after date_range_start",
  "data": null
}

Notes¶

The appointment_type field is case-insensitive and accepts either the human label (Initial Evaluation, Follow Up) or the enum form (INITIAL_EVAL, FOLLOW_UP).
The clinic must have the waitlist feature configured. Requests against unconfigured clinics return 400 with waitlist feature not configured for this organization.
Date range validation enforces an organization-configured maximum span (default 30 days).