Immediate token
Take a token in a queue that is already running.
POST /v1/qms-appointments/immediate/bookThe walk-in case: the shift has started, the doctor is seeing patients, and this
patient joins the back of the queue now. Use it for a shift whose
isStarted is true and
isEnded is false.
OTP-gated
The patient's phone must have been verified in the last 30 minutes, and this
request must carry the same x-end-user-id as that verification. See
OTP-gated routes. Calling with an x-api-key instead of a session token? The gate does not
apply — see Booking without OTP.
Same contract as pre-booking
The body, the response and the failure modes are identical to pre-book — the two routes exist to keep the intent visible in your code and in Medos's logs. Everything documented there applies here.
What differs is when you may call it, and what the patient is told:
| Pre-book | Immediate | |
|---|---|---|
| Shift state | Not started | Running |
position on the response | Where they will stand when the queue opens | Where they stand right now |
Typical bookingChannel | PHONE_CALL, WHATSAPP | WALK_IN, SELF_QR |
Try it
/v1/qms-appointments/immediate/bookBody
POST /v1/qms-appointments/immediate/book{
"addressId": "1",
"doctorId": "4",
"mode": "OFFLINE"
}https://api.medos.oneUse a dedicated test key, and put your browser's address on its allowlist
A Developer API key authenticates on its own, so it only works from the addresses registered against it — and this page calls from your browser, not your servers. Unless your own public address is on the list you get a 403 naming it, which is the allowlist doing its job. Your browser may also reach us over IPv6 even when your server does not, so the address in the error is often not the one you expected. The key here is kept in memory only and never written to storage, but create a test key for it and deactivate that key when you are done.
Request
curl -sX POST "https://api.medos.one/v1/qms-appointments/immediate/book" \
-H "x-api-key: $MEDOS_API_KEY" \
-H "x-end-user-id: $PATIENT_ID" \
-H "Content-Type: application/json" \
-d '{
"workspaceId": 1,
"addressId": 1,
"doctorId": 4,
"patientId": 774,
"qmsWorkShiftId": 331,
"appointmentDate": "2026-09-20",
"mode": "OFFLINE",
"bookingChannel": "WALK_IN",
"paymentMode": "CASH",
"paymentStatus": "PAID",
"paymentReference": "counter-4471",
"source": "DEVELOPER_API"
}'Response
201, in the same envelope
pre-book returns. Show
tokenDisplay to the patient and position to whoever is managing the queue.
Common failures
| Status | Cause |
|---|---|
400 | The shift is full, or has already ended. |
400 | bookingChannel missing. |
403 | The OTP gate. |
Re-read the shift before booking
Capacity and queue state change by the minute on a running shift. Fetch doctor shifts immediately before booking rather than reusing a grid you loaded earlier.