Booking quickstart
Show a practice's free times and book a patient in, in five minutes.
For a website, an app or a phone assistant that books into a practice's own diary. You can only ever book a time the practice's own booking page would offer, so you never double-book a clinician or use a slot the practice keeps back.
You need a key with booking.read and booking.write, and the practice's id.
1. See what the practice offers
curl "https://api.orkero.app/v1/booking/visits?practice_id=$PRACTICE" \
-H "Authorization: Bearer $ORKERO_KEY"
{"ok": true,
"practice": {"id": "…", "name": "Demo Opticians", "time_zone": "Europe/London"},
"currency": "GBP", "first_day": "2026-11-23", "last_day": "2027-02-12",
"visits": [{"id": "…", "name": "Adult Comprehensive Eye Examination",
"minutes": 40, "fee_pence": 9900, "nhs_fee_pence": 0}]}
Prices are whole pence. nhs_fee_pence of null means the visit is not offered on the NHS.
2. Find a free time
curl "https://api.orkero.app/v1/booking/times?practice_id=$PRACTICE&visit_id=$VISIT" \
-H "Authorization: Bearer $ORKERO_KEY"
Each time has starts_at, ends_at, and clinician (an opaque key for the person, with
their first name and role). A time reserves nothing: ask again just before you show it, and
show it in the practice's time_zone. Two weeks a request at most; covered_to is the last
day searched.
3. Book
curl https://api.orkero.app/v1/booking/bookings \
-H "Authorization: Bearer $ORKERO_KEY" \
-H "Content-Type: application/json" \
-d '{
"practice_id": "'$PRACTICE'",
"request_id": "web-000123",
"visit_id": "'$VISIT'",
"starts_at": "2026-11-24T09:00:00+00:00",
"clinician": "3f9a1c…",
"person": {"first_name": "Jane", "last_name": "Smith",
"date_of_birth": "1980-02-03", "email": "jane@example.org"}
}'
201 means booked. Keep booking.id. The practice finds its existing patient on an exact
match, or adds a new one, and emails the patient their confirmation with a private "Manage
my booking" link ("emailed": true).
If the time went a moment before, you get 409 time_gone: ask for the times again. With a
test key the booking is checked all the way through and undone, so nothing is booked.
4. Move or cancel
curl https://api.orkero.app/v1/booking/bookings/cancel \
-H "Authorization: Bearer $ORKERO_KEY" \
-H "Content-Type: application/json" \
-d '{"practice_id": "'$PRACTICE'", "id": "'$BOOKING'"}'
Both are open until 24 hours before the appointment (409 too_late after). Your key only
ever sees, moves and cancels the bookings it made.
5. Hear about changes
A patient can move or cancel through their email link, and the practice can change a
booking at the desk. Add a webhook for booking.booked, booking.changed and
booking.cancelled: data.by says who did it (api, patient or practice).
Full detail: Booking reference.