Booking reference
Online booking for practices that run their diary in Orkero.
Online booking for practices that run their diary in Orkero. The rules are the practice's own booking page's, with the key in place of the human check. A key reads back, changes and cancels only the bookings it made.
| Request | What it does | Scope |
|---|---|---|
GET /v1/booking/visits |
List the visits a practice offers online | booking.read |
GET /v1/booking/times |
List free times for a visit | booking.read |
GET /v1/booking/bookings |
Look up the key's bookings | booking.write |
POST /v1/booking/bookings |
Book an appointment | booking.write |
POST /v1/booking/bookings/change |
Move a booking to another time | booking.write |
POST /v1/booking/bookings/cancel |
Cancel a booking | booking.write |
List the visits a practice offers online
GET /v1/booking/visits
Scope: booking.read.
Query
| Name | Type | Needed | What it is |
|---|---|---|---|
practice_id |
string (uuid) | yes |
Example
curl "https://api.orkero.app/v1/booking/visits?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" \
-H "Authorization: Bearer $ORKERO_KEY"
const res = await fetch("https://api.orkero.app/v1/booking/visits?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.ORKERO_KEY}`,
},
});
const answer = await res.json();
import os, requests
res = requests.get(
"https://api.orkero.app/v1/booking/visits?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
)
answer = res.json()
Answer (200)
{
"ok": true,
"practice": {
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"name": "<name>",
"address": [
"<address>"
],
"postcode": "<postcode>",
"phone": "<phone>",
"email": "<email>",
"time_zone": "<time_zone>",
"privacy_url": "<privacy_url>"
},
"currency": "GBP",
"first_day": "2026-11-24",
"last_day": "2026-11-24",
"visits": [
{
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"name": "<name>",
"description": "<description>",
"minutes": 1,
"category": "<category>",
"fee_pence": 9900,
"nhs_fee_pence": 9900,
"care_plan_fee_pence": 9900
}
],
"request_id": "web-000123"
}
Errors
| Status | When |
|---|---|
| 401 | no_such_key, key_switched_off, key_ended. |
| 403 | not_allowed (the key lacks the scope), not_your_practice, whole_organisation. |
| 409 | booking_off, feedback_off, time_gone, too_late, booking_cancelled, booking_past, voice_off. |
| 422 | A field is wrong; the message says which and why. refused carries words for the person booking. |
| 429 | too_many_requests, too_many_requests_today, too_many_wrong_keys, booking_limit, practice_busy. |
List free times for a visit
GET /v1/booking/times
Times that fit the practice's diary well, exactly as its booking page offers them.
A time reserves nothing: ask again just before showing it. Two weeks a request at
most; covered_to is the last day searched in full.
Scope: booking.read.
Query
| Name | Type | Needed | What it is |
|---|---|---|---|
practice_id |
string (uuid) | yes | |
visit_id |
string (uuid) | yes | |
from |
string (date) | ||
to |
string (date) |
Example
curl "https://api.orkero.app/v1/booking/times?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99&visit_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" \
-H "Authorization: Bearer $ORKERO_KEY"
const res = await fetch("https://api.orkero.app/v1/booking/times?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99&visit_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.ORKERO_KEY}`,
},
});
const answer = await res.json();
import os, requests
res = requests.get(
"https://api.orkero.app/v1/booking/times?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99&visit_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
)
answer = res.json()
Answer (200)
{
"ok": true,
"practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"visit_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"time_zone": "<time_zone>",
"from": "2026-11-24",
"covered_to": "2026-11-24",
"first_day": "2026-11-24",
"last_day": "2026-11-24",
"times": [
{
"starts_at": "2026-11-24T09:00:00+00:00",
"ends_at": "2026-11-24T09:00:00+00:00",
"clinician": "<clinician>",
"name": "<name>",
"role": "<role>"
}
],
"request_id": "web-000123"
}
Errors
| Status | When |
|---|---|
| 401 | no_such_key, key_switched_off, key_ended. |
| 403 | not_allowed (the key lacks the scope), not_your_practice, whole_organisation. |
| 404 | no_such_visit, no_such_booking, no_such_line. |
| 409 | booking_off, feedback_off, time_gone, too_late, booking_cancelled, booking_past, voice_off. |
| 422 | A field is wrong; the message says which and why. refused carries words for the person booking. |
| 429 | too_many_requests, too_many_requests_today, too_many_wrong_keys, booking_limit, practice_busy. |
Look up the key's bookings
GET /v1/booking/bookings
With id: that booking, whatever has become of it. Without: the key's bookings still
to come at the practice, soonest first (200 at most). A booking the key did not make
is 404 no_such_booking.
Scope: booking.write.
Query
| Name | Type | Needed | What it is |
|---|---|---|---|
practice_id |
string (uuid) | yes | |
id |
string (uuid) |
Example
curl "https://api.orkero.app/v1/booking/bookings?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" \
-H "Authorization: Bearer $ORKERO_KEY"
const res = await fetch("https://api.orkero.app/v1/booking/bookings?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", {
method: "GET",
headers: {
Authorization: `Bearer ${process.env.ORKERO_KEY}`,
},
});
const answer = await res.json();
import os, requests
res = requests.get(
"https://api.orkero.app/v1/booking/bookings?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
)
answer = res.json()
Answer (200)
{
"ok": true,
"booking": {
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"state": "booked",
"first_name": "Jane",
"visit": {
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"name": "<name>",
"category": "<category>"
},
"starts_at": "2026-11-24T09:00:00+00:00",
"ends_at": "2026-11-24T09:00:00+00:00",
"clinician": {
"key": "<key>",
"name": "<name>",
"role": "<role>"
},
"funding": "private",
"can_change": true,
"change_until": "2026-11-24T09:00:00+00:00"
},
"bookings": [
{
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"state": "booked",
"first_name": "Jane",
"visit": {},
"starts_at": "2026-11-24T09:00:00+00:00",
"ends_at": "2026-11-24T09:00:00+00:00",
"clinician": {},
"funding": "private",
"can_change": true,
"change_until": "2026-11-24T09:00:00+00:00"
}
],
"request_id": "web-000123"
}
Errors
| Status | When |
|---|---|
| 401 | no_such_key, key_switched_off, key_ended. |
| 403 | not_allowed (the key lacks the scope), not_your_practice, whole_organisation. |
| 404 | no_such_visit, no_such_booking, no_such_line. |
| 429 | too_many_requests, too_many_requests_today, too_many_wrong_keys, booking_limit, practice_busy. |
Book an appointment
POST /v1/booking/bookings
Books a time /v1/booking/times offers at that moment. The practice finds its
patient on an exact match or adds one. Sending the same request_id again books
once (200, duplicate: true). With a test key the booking is checked all the way
through and undone (200, test: true, no id).
Scope: booking.write.
Body
| Field | Type | Needed | What it is |
|---|---|---|---|
practice_id |
string (uuid) | yes | |
request_id |
string | yes | Your own name for this request. Send it again unchanged when unsure; it is booked once. 8 to 100 characters. |
visit_id |
string (uuid) | yes | |
starts_at |
string (date‑time) | yes | |
clinician |
string | yes | |
funding |
string | One of private, nhs, care_plan. Default private. |
|
person |
object | yes | At least one of mobile, phone and email. |
person.first_name |
string | yes | |
person.last_name |
string | yes | |
person.date_of_birth |
string (date) | yes | |
person.mobile |
string | International form, e.g. +447700900123. | |
person.phone |
string | ||
person.email |
string (email) | ||
been_before |
string | One of yes, no, not_sure. Default not_sure. |
|
note |
string | 0 to 400 characters. |
Example
curl -X POST "https://api.orkero.app/v1/booking/bookings" \
-H "Authorization: Bearer $ORKERO_KEY" \
-H "Content-Type: application/json" \
-d '{"practice_id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99","request_id":"web-000123","visit_id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99","starts_at":"2026-11-24T09:00:00+00:00","clinician":"<clinician>","person":{"first_name":"Jane","last_name":"Smith","date_of_birth":"2026-11-24","mobile":"<mobile>","phone":"<phone>","email":"jane@example.org"}}'
const res = await fetch("https://api.orkero.app/v1/booking/bookings", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ORKERO_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"request_id": "web-000123",
"visit_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"starts_at": "2026-11-24T09:00:00+00:00",
"clinician": "<clinician>",
"person": {
"first_name": "Jane",
"last_name": "Smith",
"date_of_birth": "2026-11-24",
"mobile": "<mobile>",
"phone": "<phone>",
"email": "jane@example.org"
}
}),
});
const answer = await res.json();
import os, requests
res = requests.post(
"https://api.orkero.app/v1/booking/bookings",
headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
json={
"practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"request_id": "web-000123",
"visit_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"starts_at": "2026-11-24T09:00:00+00:00",
"clinician": "<clinician>",
"person": {
"first_name": "Jane",
"last_name": "Smith",
"date_of_birth": "2026-11-24",
"mobile": "<mobile>",
"phone": "<phone>",
"email": "jane@example.org"
}
},
)
answer = res.json()
Answer (200)
{
"ok": true,
"emailed": true,
"duplicate": true,
"test": true,
"booking": {
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"state": "booked",
"first_name": "Jane",
"visit": {
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"name": "<name>",
"category": "<category>"
},
"starts_at": "2026-11-24T09:00:00+00:00",
"ends_at": "2026-11-24T09:00:00+00:00",
"clinician": {
"key": "<key>",
"name": "<name>",
"role": "<role>"
},
"funding": "private",
"can_change": true,
"change_until": "2026-11-24T09:00:00+00:00"
},
"request_id": "web-000123"
}
Errors
| Status | When |
|---|---|
| 401 | no_such_key, key_switched_off, key_ended. |
| 403 | not_allowed (the key lacks the scope), not_your_practice, whole_organisation. |
| 409 | booking_off, feedback_off, time_gone, too_late, booking_cancelled, booking_past, voice_off. |
| 422 | A field is wrong; the message says which and why. refused carries words for the person booking. |
| 429 | too_many_requests, too_many_requests_today, too_many_wrong_keys, booking_limit, practice_busy. |
Move a booking to another time
POST /v1/booking/bookings/change
Open until 24 hours before the appointment (409 too_late after). Add visit_id
or funding to change those too. The patient's earlier "Manage my booking" link is
replaced by the one in the new email.
Scope: booking.write.
Body
| Field | Type | Needed | What it is |
|---|---|---|---|
practice_id |
string (uuid) | yes | |
id |
string (uuid) | yes | |
request_id |
string | yes | 8 to 100 characters. |
starts_at |
string (date‑time) | yes | |
clinician |
string | yes | |
visit_id |
string (uuid) | ||
funding |
string | One of private, nhs, care_plan. Default private. |
Example
curl -X POST "https://api.orkero.app/v1/booking/bookings/change" \
-H "Authorization: Bearer $ORKERO_KEY" \
-H "Content-Type: application/json" \
-d '{"practice_id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99","id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99","request_id":"web-000123","starts_at":"2026-11-24T09:00:00+00:00","clinician":"<clinician>"}'
const res = await fetch("https://api.orkero.app/v1/booking/bookings/change", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ORKERO_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"request_id": "web-000123",
"starts_at": "2026-11-24T09:00:00+00:00",
"clinician": "<clinician>"
}),
});
const answer = await res.json();
import os, requests
res = requests.post(
"https://api.orkero.app/v1/booking/bookings/change",
headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
json={
"practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"request_id": "web-000123",
"starts_at": "2026-11-24T09:00:00+00:00",
"clinician": "<clinician>"
},
)
answer = res.json()
Answer (200)
{
"ok": true,
"emailed": true,
"duplicate": true,
"test": true,
"booking": {
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"state": "booked",
"first_name": "Jane",
"visit": {
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"name": "<name>",
"category": "<category>"
},
"starts_at": "2026-11-24T09:00:00+00:00",
"ends_at": "2026-11-24T09:00:00+00:00",
"clinician": {
"key": "<key>",
"name": "<name>",
"role": "<role>"
},
"funding": "private",
"can_change": true,
"change_until": "2026-11-24T09:00:00+00:00"
},
"request_id": "web-000123"
}
Errors
| Status | When |
|---|---|
| 401 | no_such_key, key_switched_off, key_ended. |
| 403 | not_allowed (the key lacks the scope), not_your_practice, whole_organisation. |
| 404 | no_such_visit, no_such_booking, no_such_line. |
| 409 | booking_off, feedback_off, time_gone, too_late, booking_cancelled, booking_past, voice_off. |
| 422 | A field is wrong; the message says which and why. refused carries words for the person booking. |
| 429 | too_many_requests, too_many_requests_today, too_many_wrong_keys, booking_limit, practice_busy. |
Cancel a booking
POST /v1/booking/bookings/cancel
Open until 24 hours before. Asked again it answers the same, with duplicate.
Scope: booking.write.
Body
| Field | Type | Needed | What it is |
|---|---|---|---|
practice_id |
string (uuid) | yes | |
id |
string (uuid) | yes |
Example
curl -X POST "https://api.orkero.app/v1/booking/bookings/cancel" \
-H "Authorization: Bearer $ORKERO_KEY" \
-H "Content-Type: application/json" \
-d '{"practice_id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99","id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99"}'
const res = await fetch("https://api.orkero.app/v1/booking/bookings/cancel", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ORKERO_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99"
}),
});
const answer = await res.json();
import os, requests
res = requests.post(
"https://api.orkero.app/v1/booking/bookings/cancel",
headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"},
json={
"practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99"
},
)
answer = res.json()
Answer (200)
{
"ok": true,
"emailed": true,
"duplicate": true,
"test": true,
"booking": {
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"state": "booked",
"first_name": "Jane",
"visit": {
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"name": "<name>",
"category": "<category>"
},
"starts_at": "2026-11-24T09:00:00+00:00",
"ends_at": "2026-11-24T09:00:00+00:00",
"clinician": {
"key": "<key>",
"name": "<name>",
"role": "<role>"
},
"funding": "private",
"can_change": true,
"change_until": "2026-11-24T09:00:00+00:00"
},
"request_id": "web-000123"
}
Errors
| Status | When |
|---|---|
| 401 | no_such_key, key_switched_off, key_ended. |
| 403 | not_allowed (the key lacks the scope), not_your_practice, whole_organisation. |
| 404 | no_such_visit, no_such_booking, no_such_line. |
| 409 | booking_off, feedback_off, time_gone, too_late, booking_cancelled, booking_past, voice_off. |
| 429 | too_many_requests, too_many_requests_today, too_many_wrong_keys, booking_limit, practice_busy. |