Create Waitlist Request

Adds a patient to the waitlist for a clinic and appointment type.

Endpoint

POST /v2/waitlist-requests

Request Body

Parameter	Type	Required	Description
patient_id	string	Yes	The patient. Correlate on this — it's a stable id, and there's no external-reference field.
clinic_id	string	Yes	The clinic this record belongs to.
appointment_type_id	string	Yes	The appointment type, from List Appointment Types. A single id, not a list.
payment_mode	string	Yes	How the visit is paid for. Required on create; omitting it fails the booking with an unhelpful error. One of SELF_PAY, INSURANCE_PAY.
appointment_type	string	No	Derived from appointment_type_id when omitted on write. One of INITIAL_EVAL, FOLLOW_UP.
preferred_provider_ids	array of string	No	Providers the patient would prefer. Empty means no preference.
preferred_days	array of string	No	Any of MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY.
preferred_time_slots	array of string	No	Any of MORNING, AFTERNOON, EVENING, ANYTIME.
date_range_start	string (date)	Yes	Start of the window the patient can be seen in. Required. YYYY-MM-DD.
date_range_end	string (date)	Yes	End of the window the patient can be seen in. Required. YYYY-MM-DD.
priority	integer	No
notes	string	No

Request

curl --location '{base_url}/v2/waitlist-requests' \
  --header 'Authorization: Bearer JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '{
  "patient_id": "63120",
  "clinic_id": "5831",
  "appointment_type_id": "318",
  "payment_mode": "INSURANCE_PAY",
  "appointment_type": "INITIAL_EVAL",
  "preferred_provider_ids": [],
  "preferred_days": [
    "MONDAY"
  ],
  "preferred_time_slots": [
    "MORNING"
  ],
  "date_range_start": "2026-09-15",
  "date_range_end": "2026-10-15",
  "priority": 3,
  "notes": null
}'

Response

Success Response

Code: 201 Created

{
  "id": "3f9c1d4e-72ab-4c58-9e11-8b6d0a5427f3",
  "patient_id": "63120",
  "clinic_id": "5831",
  "appointment_type_id": "318",
  "preferred_provider_ids": [],
  "preferred_days": [
    "MONDAY"
  ],
  "preferred_time_slots": [
    "MORNING"
  ],
  "date_range_start": "2026-09-15",
  "date_range_end": "2026-10-15",
  "appointment_type": "INITIAL_EVAL",
  "payment_mode": "INSURANCE_PAY",
  "priority": 3,
  "notes": null,
  "status": "ACTIVE",
  "created_at": "2026-08-27T14:30:00Z",
  "updated_at": "2026-08-27T14:30:00Z"
}

The Location header carries the URL of the created resource.

Response Fields

Field	Type	Description
id	string	The waitlist request id, a UUID.
patient_id	string	The patient. Correlate on this — it's a stable id, and there's no external-reference field.
clinic_id	string	The clinic this record belongs to.
appointment_type_id	string	The appointment type, from List Appointment Types. A single id, not a list.
preferred_provider_ids	array of string	Providers the patient would prefer. Empty means no preference.
preferred_days	array of string	Any of MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, SUNDAY.
preferred_time_slots	array of string	Any of MORNING, AFTERNOON, EVENING, ANYTIME.
date_range_start	string (date) or null	Start of the window the patient can be seen in. Required. YYYY-MM-DD.
date_range_end	string (date) or null	End of the window the patient can be seen in. Required. YYYY-MM-DD.
appointment_type	string	Derived from appointment_type_id when omitted on write. One of INITIAL_EVAL, FOLLOW_UP.
payment_mode	string	How the visit is paid for. Required on create; omitting it fails the booking with an unhelpful error. One of SELF_PAY, INSURANCE_PAY.
priority	integer
notes	string or null
status	string	One of ACTIVE, FULFILLED, CANCELLED, EXPIRED.
created_at	string (date-time) or null
updated_at	string (date-time) or null

Error Response

Code: 400 Bad Request

{
  "code": "bad_request",
  "message": "Validation failed",
  "errors": [
    {
      "field": "patient_id",
      "message": "must be a string"
    }
  ]
}

Every error has the same shape — a machine-readable code, a message, and an errors[] array that's empty when there's nothing field-specific to report. The HTTP status is authoritative.

Status	code	Meaning
400 Bad Request	bad_request	The request body or parameters failed validation. errors[] names the offending fields.
401 Unauthorized	unauthorized	The access token is missing, malformed or expired.
403 Forbidden	forbidden	The request references a resource outside the token's organisation or clinic scope.
404 Not Found	not_found	No such resource, or it's outside your scope.
429 Too Many Requests	rate_limited	Rate limit exceeded. Back off and retry.
500 Internal Server Error	internal_error	Unexpected server error.
502 Bad Gateway	upstream_error	Upstream service failed or timed out.