Docs
View as Markdown

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.