# Orkero API > Booking, patient feedback and the phone agent for healthcare practices, on one compliant patient database. Source: https://docs.orkero.app/ Orkero runs healthcare practices: the diary, records of care, the till, recalls and the phones. The API lets your software use the same building blocks, with the hard healthcare parts already done: consent, audit trails, UK GDPR, and data kept in the UK. ## What you can build today | Building block | What it does | Status | | --- | --- | --- | | [Booking](/quickstart/booking) | Show a practice's free times, book, move and cancel, and hear when a patient changes a booking. | Live | | [Feedback](/quickstart/feedback) | Tell us a visit is done; we ask the patient one question and give you the practice's Net Promoter Score. | Live | | [Voice](/quickstart/voice) | Give a practice an AI receptionist that answers calls, books and hands over to a person. | Early access | | [Accounts](/reference/accounts) | Each day's takings, VAT and payroll hours, for a ledger. | Live | ## How it works - **REST and JSON**, described by one [OpenAPI file](/openapi.yaml) that this site, our code library and our AI tools are all built from. - **Signed webhooks** tell you what happened, so you do not have to keep asking. See [Webhooks](/webhooks). - **Test keys** behave exactly like live ones, but nothing is kept, booked or sent. See [Keys and requests](/keys). - **Rules you cannot switch off**: a patient who says "don't ask me again" is never asked again; a booking is only ever made at a time the practice's own diary offers; nothing about a patient leaves the practice except what a request needs. ## Start in five minutes 1. Ask for early access and you will be sent a **test key**. 2. Check it works: ```bash curl https://api.orkero.app/v1/ping \ -H "Authorization: Bearer $ORKERO_KEY" ``` 3. Follow a quickstart: [Booking](/quickstart/booking), [Feedback](/quickstart/feedback) or [Voice](/quickstart/voice). ## Using an AI assistant? Every page here is also plain text. Press **Copy for AI** at the top of any page, or point your assistant at [/llms.txt](/llms.txt) (an index) or [/llms-full.txt](/llms-full.txt) (everything in one file). See [Orkero and AI tools](/ai). --- # Keys and requests > How to authenticate, what a key may do, limits, request ids and test keys. Source: https://docs.orkero.app/keys ## Your keys When you are set up you receive a **test key** and, when you are ready, a **live key**. Each key is shown once: keep it on your server, never in a web page or an app. | Key | What happens | | --- | --- | | Test | Checked exactly like a live key. Nothing is kept, booked or emailed, and the answer says `"test": true`. | | Live | Real bookings, real questions to real patients. | Keys start `vl_test_` and `vl_live_` today. They will start `ork_test_` and `ork_live_` once the new address is live; existing keys keep working. A key says what it may do (its **scopes**) and which practices it covers. Ask for a replacement at any time: the old key keeps working for a day so you can change over. | Scope | Lets you | | --- | --- | | `booking.read` | See the visits a practice offers online and its free times | | `booking.write` | Book, look up, move and cancel bookings your key made | | `feedback.signals` | Tell us a visit is done | | `feedback.figures` | Read the Net Promoter Score | | `feedback.events` | Ask for feedback events | | `accounts.feed` | Read each day's accounts figures | | `accounts.tally` | Read the tally between companies | | `payroll.hours` | Read each person's hours for a pay period | ## Every request ```http Authorization: Bearer Content-Type: application/json X-Request-Id: your-own-id ``` - Only the `Authorization` header is read. A key in the address is ignored. - `X-Request-Id` is optional: letters, numbers, `.`, `_` and `-`, up to 100 characters. Every answer carries a `request_id` (yours, or one we made). Quote it to support. - There are no CORS headers: call the API from your server. ## Limits 60 requests a minute and 10,000 a day per key, unless agreed otherwise. Over a limit the answer is `429` with a `Retry-After` header in seconds. Thirty wrong keys in ten minutes from one address and that address is told to wait. ## Sending the same thing twice Booking requests carry your own `request_id`; a visit carries your own `visit_id`. Send the same one again after a timeout and it is done once, with `"duplicate": true` in the answer. It is always safe to retry. ## Versions Today there is one version, `v1`, in the address. Dated versions chosen with an `Orkero-Version` header are coming; the version you start on stays yours until you choose to move. See the [Changelog](/changelog). --- # Errors > Every error has the same shape, with a code for your program and a message for a person. Source: https://docs.orkero.app/errors Every error looks like this: ```json { "error": { "code": "time_gone", "message": "That time has just been taken. Ask for the free times again." }, "request_id": "req_8f2c1a" } ``` `code` is for your program and never changes meaning. `message` is written for a person and says what to fix: show it, or log it. | Status | `code` | What to do | | --- | --- | --- | | 400 | `not_json`, `bad_request` | Send a JSON object. | | 401 | `no_such_key`, `key_switched_off`, `key_ended` | Check the header; ask for a key. | | 403 | `not_allowed` | The key lacks the scope for this address. | | 403 | `not_your_practice` | The key does not cover that practice. | | 403 | `whole_organisation` | This address needs a key that covers every practice. | | 404 | `no_such_path`, `no_such_visit`, `no_such_booking` | Check the address or id. | | 405 | `wrong_method` | Check the method. | | 409 | `booking_off`, `feedback_off`, `feed_off` | The practice has switched that off. | | 409 | `time_gone` | That time was taken. Ask for the times again. | | 409 | `too_late`, `booking_cancelled`, `booking_past` | The booking can no longer be changed here. | | 413 | `too_large` | A request is 100,000 bytes at most. | | 422 | `refused` | Something about the details; the message is written for the person booking. | | 422 | `bad_*`, `*_needed` | The message says which field and why. Do not retry unchanged. | | 429 | `too_many_requests`, `booking_limit`, `practice_busy` | Wait `Retry-After` seconds. | | 500, 503 | `failed`, `unavailable` | Our side. Retry with a pause; repeats are safe. | --- # Webhooks > Signed events sent to your server as things happen, and how to check them. Source: https://docs.orkero.app/webhooks Give us an `https://` address on the public internet and we `POST` each event to it as it happens. You can ask for some kinds of event only, or some practices only. ```json {"id": "8a6f0c0e-…", "type": "booking.changed", "created_at": "2026-11-21T10:02:11.5+00:00", "practice_id": "…", "data": {"booking_id": "…", "by": "patient", "starts_at": "2026-11-24T14:00:00+00:00"}} ``` An event never carries a patient's name, contact details or a comment. New kinds of event and new fields may be added: ignore what you do not know. ## Answer quickly Answer `2xx` within ten seconds and do your own work afterwards. Anything else is tried again after 1, 5 and 30 minutes and 2, 6 and 12 hours, then we stop. - **The same event may arrive twice.** Keep the event `id` and ignore one you have had. - **Events may arrive out of order.** Use `created_at`. ## Check the signature Each request carries a header `VroomLogic-Signature: t=,v1=` (to be renamed `Orkero-Signature`). Check it before you believe an event: 1. Take the body **exactly as received**, before parsing it. 2. Work out HMAC-SHA256 of `t + "." + body` with your webhook secret (the whole string, `whsec_` included) as the key, in hex. 3. Accept if it equals **any** `v1` (in constant time) and `t` is within five minutes of now. There are two `v1` values for a day after a secret is replaced, so you can change over without missing an event. ```typescript import { createHmac, timingSafeEqual } from 'node:crypto'; export function fromOrkero(secret: string, header: string, rawBody: string): boolean { const parts = (header ?? '').split(',').map((p) => p.trim()); const t = parts.find((p) => p.startsWith('t='))?.slice(2); const given = parts.filter((p) => p.startsWith('v1=')).map((p) => p.slice(3)); if (!t || given.length === 0) return false; if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false; const expected = Buffer.from(createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex')); return given.some((v) => v.length === expected.length && timingSafeEqual(Buffer.from(v), expected)); } ``` ```python import hashlib, hmac, time def from_orkero(secret: str, header: str, raw_body: bytes) -> bool: parts = [p.strip() for p in (header or "").split(",")] t = next((p[2:] for p in parts if p.startswith("t=")), None) given = [p[3:] for p in parts if p.startswith("v1=")] if not t or not given or abs(time.time() - int(t)) > 300: return False expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest() return any(hmac.compare_digest(v, expected) for v in given) ``` ## Kinds of event | `type` | When | | --- | --- | | `booking.booked`, `booking.changed`, `booking.cancelled` | A booking your key made was made, moved or cancelled. | | `feedback.request_sent` | The question went. | | `feedback.answer_received` | The person gave a score. | | `feedback.score_changed` | They changed it (within 24 hours). | | `feedback.comment_added` | They left a comment (the comment itself is not sent). | | `feedback.low_score` | A score of 0 to 6 (sent after two minutes, in case of a mis-tap). | | `feedback.opted_out` | "Don't ask me again." | | `accounts.day_ready`, `accounts.day_revised` | A day's figures were worked out, or worked out again. | | `call.completed`, `call.handover`, `call.callback_needed` | Voice (early access). | | `webhook.test` | A test sent at your request. | --- # Orkero and AI tools > Plain-text docs, llms.txt and the coming MCP server, for building with an AI assistant. Source: https://docs.orkero.app/ai These docs are written to be read by people and by AI assistants alike. - **Copy for AI** at the top of every page copies the page as plain Markdown, ready to paste into Claude, ChatGPT or your editor's assistant. - Every page is also at its own address with `.md` on the end, for example [/quickstart/booking.md](/quickstart/booking.md). - [/llms.txt](/llms.txt) is an index of every page, written for AI tools. - [/llms-full.txt](/llms-full.txt) is every page in one file. - [/openapi.yaml](/openapi.yaml) is the whole API as an OpenAPI 3.1 file. Most code generators and AI tools read it directly. ## Coming soon - **An MCP server**, so an assistant can read these docs and try requests against a test practice by itself, and later act on a practice with its owner's consent. - **`@orkero/sdk`**, a TypeScript library, and `npx orkero init` to set up a project. A good prompt to start with: > Read https://docs.orkero.app/llms-full.txt. I want my clinic's website to show free > eye examination times and let patients book. Write the server code, using a test key > from the environment variable ORKERO_KEY. --- # Changelog > What changed in the Orkero API, newest first. Source: https://docs.orkero.app/changelog ## 22 November 2026 - These docs, built from the OpenAPI file, with plain-text copies and `llms.txt`. - The [OpenAPI file](/openapi.yaml) published. - Voice designed and published for early access. ## 21 November 2026 - `GET /v1/accounts/between-companies` and `GET /v1/payroll/hours`. ## 20 November 2026 - Online booking: visits, free times, booking, moving and cancelling, and booking events. ## 19 November 2026 - Keys, limits and request ids. Patient feedback: visits in, the score out, events by webhook and by asking. The accounts feed. --- # Booking quickstart > Show a practice's free times and book a patient in, in five minutes. Source: https://docs.orkero.app/quickstart/booking 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 ```bash curl "https://api.orkero.app/v1/booking/visits?practice_id=$PRACTICE" \ -H "Authorization: Bearer $ORKERO_KEY" ``` ```json {"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 ```bash 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 ```bash 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 ```bash 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](/webhooks) for `booking.booked`, `booking.changed` and `booking.cancelled`: `data.by` says who did it (`api`, `patient` or `practice`). Full detail: [Booking reference](/reference/booking). --- # Feedback quickstart > Ask patients one question after a visit and read the practice's Net Promoter Score. Source: https://docs.orkero.app/quickstart/feedback Your system says a visit is done. We ask the patient "How likely are you to recommend us to a friend or family member?" (0 to 10) by email, at a sensible time, and you read the score. You need a key with `feedback.signals` and `feedback.figures`. ## 1. Tell us a visit is done ```bash curl https://api.orkero.app/v1/feedback/signals \ -H "Authorization: Bearer $ORKERO_KEY" \ -H "Content-Type: application/json" \ -d '{ "practice_id": "'$PRACTICE'", "visit_id": "V-1001", "person_id": "P-553", "visit_type_name": "Eye examination", "contact": {"first_name": "Jane", "email": "jane@example.org"} }' ``` `visit_id` and `person_id` are **your own** ids. The answer says what will happen: ```json {"ok": true, "question": {"state": "scheduled", "send_at": "2026-11-24T12:40:00+00:00"}} ``` Or `not_asked` with a `reason`, such as `asked_recently` or `person_said_no`. ## 2. Read the score ```bash curl "https://api.orkero.app/v1/feedback/figures?from=2026-09-01&to=2026-11-30" \ -H "Authorization: Bearer $ORKERO_KEY" ``` `score` runs from −100 to +100. It is `null` until there are enough answers (`min_answers`), in the total and in every breakdown, so a score never points at one person. ## Rules you cannot switch off One email per visit and no reminders. No link but the answer page and "don't ask me again". Sent inside the practice's hours. A person who says "don't ask me again" is never asked again, whatever you send. The name and email you send are used for that one question and cleared by the database itself. ## Hear what happened Each step is an event (`feedback.answer_received`, `feedback.low_score` and more), by [webhook](/webhooks) or by asking `GET /v1/feedback/events`. Events carry your own ids, never a name, an address or a comment. Full detail: [Feedback reference](/reference/feedback). --- # Voice quickstart > Give a practice an AI receptionist that answers its calls. In early access. Source: https://docs.orkero.app/quickstart/voice > **Early access.** Orkero Voice answers real practices' phones today. The API below is > designed and published so you can plan against it; it is not open yet. Ask for early > access to be told first. Voice answers a practice's calls in the practice's name. It finds the patient from their number or checks who they are, says whether their glasses or lenses are ready, books, moves and cancels with the same rules as online booking, and hands the call to a person for anything clinical or unusual. It never gives clinical advice, and anything urgent goes straight to a clinician. ## 1. Give a practice a line ```bash curl https://api.orkero.app/v1/voice/lines \ -H "Authorization: Bearer $ORKERO_KEY" \ -H "Content-Type: application/json" \ -d '{ "practice_id": "'$PRACTICE'", "number": "forward", "answer": "unanswered", "handover": "+441491000000", "can": ["booking", "orders", "hours"] }' ``` `answer` is `always`, `unanswered` (rings the practice first) or `off`. `can` is what Voice may do on a call. ## 2. Read the call log `GET /v1/voice/calls?practice_id=…` lists each call: why the person rang, what was done, how long it took and whether it was handed over. A transcript and the caller's number never appear in the log. ## 3. Hear about calls `call.completed`, `call.handover` and `call.callback_needed` events by [webhook](/webhooks). Full detail: [Voice reference](/reference/voice). --- # Keys reference > Check a key and what it may do. Source: https://docs.orkero.app/reference/keys Check a key and what it may do. | Request | What it does | Scope | | --- | --- | --- | | [`GET /v1/ping`](#ping) | Check a key | any key | ## Check a key `GET /v1/ping` Whose key it is, what it may do and which practices it covers. Scope: any live or test key. ### Example ```bash curl "https://api.orkero.app/v1/ping" \ -H "Authorization: Bearer $ORKERO_KEY" ``` ```typescript const res = await fetch("https://api.orkero.app/v1/ping", { method: "GET", headers: { Authorization: `Bearer ${process.env.ORKERO_KEY}`, }, }); const answer = await res.json(); ``` ```python import os, requests res = requests.get( "https://api.orkero.app/v1/ping", headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"}, ) answer = res.json() ``` ### Answer (200) ```json { "ok": true, "organisation": { "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "name": "" }, "key": { "starts": "", "test": true, "scopes": [ "feedback.signals" ] }, "practices": [ { "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "name": "" } ], "request_id": "web-000123" } ``` ### Errors | Status | When | | --- | --- | | 401 | `no_such_key`, `key_switched_off`, `key_ended`. | | 429 | `too_many_requests`, `too_many_requests_today`, `too_many_wrong_keys`, `booking_limit`, `practice_busy`. | --- # Booking reference > Online booking for practices that run their diary in Orkero. Source: https://docs.orkero.app/reference/booking 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`](#listbookingvisits) | List the visits a practice offers online | `booking.read` | | [`GET /v1/booking/times`](#listbookingtimes) | List free times for a visit | `booking.read` | | [`GET /v1/booking/bookings`](#getbookings) | Look up the key's bookings | `booking.write` | | [`POST /v1/booking/bookings`](#createbooking) | Book an appointment | `booking.write` | | [`POST /v1/booking/bookings/change`](#changebooking) | Move a booking to another time | `booking.write` | | [`POST /v1/booking/bookings/cancel`](#cancelbooking) | 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 ```bash curl "https://api.orkero.app/v1/booking/visits?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" \ -H "Authorization: Bearer $ORKERO_KEY" ``` ```typescript 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(); ``` ```python 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) ```json { "ok": true, "practice": { "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "name": "", "address": [ "
" ], "postcode": "", "phone": "", "email": "", "time_zone": "", "privacy_url": "" }, "currency": "GBP", "first_day": "2026-11-24", "last_day": "2026-11-24", "visits": [ { "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "name": "", "description": "", "minutes": 1, "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 ```bash 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" ``` ```typescript 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(); ``` ```python 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) ```json { "ok": true, "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "visit_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "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": "", "name": "", "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 ```bash curl "https://api.orkero.app/v1/booking/bookings?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" \ -H "Authorization: Bearer $ORKERO_KEY" ``` ```typescript 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(); ``` ```python 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) ```json { "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": "", "category": "" }, "starts_at": "2026-11-24T09:00:00+00:00", "ends_at": "2026-11-24T09:00:00+00:00", "clinician": { "key": "", "name": "", "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 ```bash 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":"","person":{"first_name":"Jane","last_name":"Smith","date_of_birth":"2026-11-24","mobile":"","phone":"","email":"jane@example.org"}}' ``` ```typescript 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": "", "person": { "first_name": "Jane", "last_name": "Smith", "date_of_birth": "2026-11-24", "mobile": "", "phone": "", "email": "jane@example.org" } }), }); const answer = await res.json(); ``` ```python 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": "", "person": { "first_name": "Jane", "last_name": "Smith", "date_of_birth": "2026-11-24", "mobile": "", "phone": "", "email": "jane@example.org" } }, ) answer = res.json() ``` ### Answer (200) ```json { "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": "", "category": "" }, "starts_at": "2026-11-24T09:00:00+00:00", "ends_at": "2026-11-24T09:00:00+00:00", "clinician": { "key": "", "name": "", "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 ```bash 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":""}' ``` ```typescript 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": "" }), }); const answer = await res.json(); ``` ```python 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": "" }, ) answer = res.json() ``` ### Answer (200) ```json { "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": "", "category": "" }, "starts_at": "2026-11-24T09:00:00+00:00", "ends_at": "2026-11-24T09:00:00+00:00", "clinician": { "key": "", "name": "", "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 ```bash 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"}' ``` ```typescript 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(); ``` ```python 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) ```json { "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": "", "category": "" }, "starts_at": "2026-11-24T09:00:00+00:00", "ends_at": "2026-11-24T09:00:00+00:00", "clinician": { "key": "", "name": "", "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`. | --- # Feedback reference > Same-day patient feedback (Net Promoter Score). Source: https://docs.orkero.app/reference/feedback Same-day patient feedback (Net Promoter Score). Your system says a visit is done; we ask one question at a sensible time; you read the score and hear what happened. | Request | What it does | Scope | | --- | --- | --- | | [`POST /v1/feedback/signals`](#sendfeedbacksignal) | Tell us a visit is done | `feedback.signals` | | [`GET /v1/feedback/figures`](#getfeedbackfigures) | Read the score | `feedback.figures` | | [`GET /v1/feedback/events`](#listfeedbackevents) | Ask for feedback events | `feedback.events` | ## Tell us a visit is done `POST /v1/feedback/signals` We ask the person one question by email at a sensible time, within the practice's rules (one email per visit, no reminders, the practice's hours, the gap between questions, "don't ask me again"), which no caller can switch off. The name and email are kept apart and cleared by the database itself. The same visit sent twice is taken once (`200`, `duplicate: true`). Scope: `feedback.signals`. ### Body | Field | Type | Needed | What it is | | --- | --- | --- | --- | | `practice_id` | string (uuid) | yes | | | `kind` | string | | One of `visit_done`, `course_started`, `visit_undone`. Default `visit_done`. | | `visit_id` | string | yes | Your own id for the visit. Comes back in events. 0 to 100 characters. | | `person_id` | string | yes | Your own id for the person, the same each time. 0 to 100 characters. | | `visit_type_id` | string | | 0 to 100 characters. | | `visit_type_name` | string | | | | `seen_by_id` | string | | 0 to 100 characters. | | `seen_by_name` | string | | | | `finished_at` | string (date‑time) | | Not in the future; at most three days ago. | | `course_id` | string | | 0 to 100 characters. | | `ends_course` | boolean | | | | `contact` | object | | | | `contact.first_name` | string | | | | `contact.email` | string (email) | | | | `contact.under_16` | boolean | | | ### Example ```bash curl -X POST "https://api.orkero.app/v1/feedback/signals" \ -H "Authorization: Bearer $ORKERO_KEY" \ -H "Content-Type: application/json" \ -d '{"practice_id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99","visit_id":"","person_id":""}' ``` ```typescript const res = await fetch("https://api.orkero.app/v1/feedback/signals", { method: "POST", headers: { Authorization: `Bearer ${process.env.ORKERO_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "visit_id": "", "person_id": "" }), }); const answer = await res.json(); ``` ```python import os, requests res = requests.post( "https://api.orkero.app/v1/feedback/signals", headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"}, json={ "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "visit_id": "", "person_id": "" }, ) answer = res.json() ``` ### Answer (200) ```json { "ok": true, "duplicate": true, "test": true, "kind": "", "visit_id": "", "question": { "state": "scheduled", "send_at": "2026-11-24T09:00:00+00:00", "wait_until": "2026-11-24T09:00:00+00:00", "sent_at": "2026-11-24T09:00:00+00:00", "reason": "asked_recently" }, "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`. | ## Read the score `GET /v1/feedback/figures` The Net Promoter Score and its counts. The score is `null` (`enough` false) until there are `min_answers` answers, in the total and in every breakdown row. Never a comment or anything about a person. Scope: `feedback.figures`. ### Query | Name | Type | Needed | What it is | | --- | --- | --- | --- | | `from` | string (date) | | | | `to` | string (date) | | | | `practice_id` | string | | One practice, several (repeat it, or separate with commas), or none for every practice the key covers. | ### Example ```bash curl "https://api.orkero.app/v1/feedback/figures" \ -H "Authorization: Bearer $ORKERO_KEY" ``` ```typescript const res = await fetch("https://api.orkero.app/v1/feedback/figures", { method: "GET", headers: { Authorization: `Bearer ${process.env.ORKERO_KEY}`, }, }); const answer = await res.json(); ``` ```python import os, requests res = requests.get( "https://api.orkero.app/v1/feedback/figures", headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"}, ) answer = res.json() ``` ### Answer (200) ```json { "ok": true, "figures": { "from": "2026-11-24", "to": "2026-11-24", "score": 1, "enough": true, "min_answers": 1, "answers": 1, "promoters": 1, "passives": 1, "detractors": 1, "asked": 1, "response_percent": 1.5, "low_scores": 1 }, "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`. | | 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`. | ## Ask for feedback events `GET /v1/feedback/events` The same events webhooks send, oldest first, after the event named or from the last 30 days. Keep `next_after` and send it as `after` next time. Scope: `feedback.events`. ### Query | Name | Type | Needed | What it is | | --- | --- | --- | --- | | `after` | string (uuid) | | | | `limit` | integer | | Default `50`. From 1 to 100. | | `type` | string | | One of `feedback.request_sent`, `feedback.answer_received`, `feedback.score_changed`, `feedback.comment_added`, `feedback.low_score`, `feedback.opted_out`, `feedback.follow_up_recorded`. | | `practice_id` | string (uuid) | | | ### Example ```bash curl "https://api.orkero.app/v1/feedback/events" \ -H "Authorization: Bearer $ORKERO_KEY" ``` ```typescript const res = await fetch("https://api.orkero.app/v1/feedback/events", { method: "GET", headers: { Authorization: `Bearer ${process.env.ORKERO_KEY}`, }, }); const answer = await res.json(); ``` ```python import os, requests res = requests.get( "https://api.orkero.app/v1/feedback/events", headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"}, ) answer = res.json() ``` ### Answer (200) ```json { "ok": true, "events": [ { "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "type": "feedback.request_sent", "created_at": "2026-11-24T09:00:00+00:00", "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "data": {} } ], "has_more": true, "next_after": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "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`. | | 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`. | --- # Accounts reference > The daily accounts feed, the tally between companies and payroll hours, for a ledger. Source: https://docs.orkero.app/reference/accounts The daily accounts feed, the tally between companies and payroll hours, for a ledger. | Request | What it does | Scope | | --- | --- | --- | | [`GET /v1/accounts/days`](#listaccountsdays) | Read each day's accounts figures | `accounts.feed` | | [`GET /v1/accounts/between-companies`](#getbetweencompanies) | Read the tally between companies | `accounts.tally` | | [`GET /v1/payroll/hours`](#getpayrollhours) | Read each person's hours for a pay period | `payroll.hours` | ## Read each day's accounts figures `GET /v1/accounts/days` For a ledger or accountant's system. Fields are in docs/api-guide.md, section 4. Scope: `accounts.feed`. ### Query | Name | Type | Needed | What it is | | --- | --- | --- | --- | | `from` | string (date) | | | | `to` | string (date) | | | | `practice_id` | string | | One practice, several (repeat it, or separate with commas), or none for every practice the key covers. | | `since` | string (date‑time) | | | | `revisions` | string | | One of `latest`, `all`. Default `latest`. | ### Example ```bash curl "https://api.orkero.app/v1/accounts/days" \ -H "Authorization: Bearer $ORKERO_KEY" ``` ```typescript const res = await fetch("https://api.orkero.app/v1/accounts/days", { method: "GET", headers: { Authorization: `Bearer ${process.env.ORKERO_KEY}`, }, }); const answer = await res.json(); ``` ```python import os, requests res = requests.get( "https://api.orkero.app/v1/accounts/days", headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"}, ) answer = res.json() ``` ### Answer (200) ```json { "ok": true, "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. | ## Read the tally between companies `GET /v1/accounts/between-companies` Scope: `accounts.tally`. ### Query | Name | Type | Needed | What it is | | --- | --- | --- | --- | | `from` | string (date) | | | | `to` | string (date) | | | ### Example ```bash curl "https://api.orkero.app/v1/accounts/between-companies" \ -H "Authorization: Bearer $ORKERO_KEY" ``` ```typescript const res = await fetch("https://api.orkero.app/v1/accounts/between-companies", { method: "GET", headers: { Authorization: `Bearer ${process.env.ORKERO_KEY}`, }, }); const answer = await res.json(); ``` ```python import os, requests res = requests.get( "https://api.orkero.app/v1/accounts/between-companies", headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"}, ) answer = res.json() ``` ### Answer (200) ```json { "ok": true, "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`. | ## Read each person's hours for a pay period `GET /v1/payroll/hours` Scope: `payroll.hours`. ### Query | Name | Type | Needed | What it is | | --- | --- | --- | --- | | `from` | string (date) | | | | `to` | string (date) | | | ### Example ```bash curl "https://api.orkero.app/v1/payroll/hours" \ -H "Authorization: Bearer $ORKERO_KEY" ``` ```typescript const res = await fetch("https://api.orkero.app/v1/payroll/hours", { method: "GET", headers: { Authorization: `Bearer ${process.env.ORKERO_KEY}`, }, }); const answer = await res.json(); ``` ```python import os, requests res = requests.get( "https://api.orkero.app/v1/payroll/hours", headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"}, ) answer = res.json() ``` ### Answer (200) ```json { "ok": true, "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`. | --- # Voice reference > The phone agent (Orkero Voice): answers a practice's calls, deals with them, books and hands over to a person when needed. Source: https://docs.orkero.app/reference/voice The phone agent (Orkero Voice): answers a practice's calls, deals with them, books and hands over to a person when needed. Designed here; not yet offered through the API (AMA-106). | Request | What it does | Scope | | --- | --- | --- | | [`GET /v1/voice/lines`](#listvoicelines) | List a practice's lines | `voice.lines` | | [`POST /v1/voice/lines`](#createvoiceline) | Give a practice a phone line answered by Voice | `voice.lines` | | [`POST /v1/voice/lines/change`](#changevoiceline) | Change when Voice answers, or what it may do | `voice.lines` | | [`GET /v1/voice/calls`](#listvoicecalls) | Read the call log | `voice.calls` | ## List a practice's lines `GET /v1/voice/lines` > **Early access.** Designed and published so you can plan against it; not open yet. Scope: `voice.lines`. ### Query | Name | Type | Needed | What it is | | --- | --- | --- | --- | | `practice_id` | string (uuid) | yes | | ### Example ```bash curl "https://api.orkero.app/v1/voice/lines?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" \ -H "Authorization: Bearer $ORKERO_KEY" ``` ```typescript const res = await fetch("https://api.orkero.app/v1/voice/lines?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", { method: "GET", headers: { Authorization: `Bearer ${process.env.ORKERO_KEY}`, }, }); const answer = await res.json(); ``` ```python import os, requests res = requests.get( "https://api.orkero.app/v1/voice/lines?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"}, ) answer = res.json() ``` ### Answer (200) ```json { "ok": true, "lines": [ { "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "number": "", "forwarding_to_us": true, "answer": "always", "handover": "", "can": [ "booking" ], "state": "setting_up" } ], "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`. | ## Give a practice a phone line answered by Voice `POST /v1/voice/lines` > **Early access.** Designed and published so you can plan against it; not open yet. A new number, or the practice's existing number forwarded. Voice answers in the practice's name, finds the patient from their number or starts a new record, deals with what it may (`can`) and hands over to a person for anything clinical or unusual. It never gives clinical advice. Calls are recorded only with consent and written to the audit trail. Scope: `voice.lines`. ### Body | Field | Type | Needed | What it is | | --- | --- | --- | --- | | `practice_id` | string (uuid) | yes | | | `number` | string | yes | A new number, or forward the practice's existing one. One of `new`, `forward`. | | `answer` | string | yes | When Voice answers. One of `always`, `unanswered`, `off`. | | `handover` | string | yes | Where a call is put through to a person (E.164 or a SIP address). | | `can` | array of string | | | | `request_id` | string | | 8 to 100 characters. | ### Example ```bash curl -X POST "https://api.orkero.app/v1/voice/lines" \ -H "Authorization: Bearer $ORKERO_KEY" \ -H "Content-Type: application/json" \ -d '{"practice_id":"0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99","number":"new","answer":"always","handover":"","can":["booking"],"request_id":"web-000123"}' ``` ```typescript const res = await fetch("https://api.orkero.app/v1/voice/lines", { method: "POST", headers: { Authorization: `Bearer ${process.env.ORKERO_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "number": "new", "answer": "always", "handover": "", "can": [ "booking" ], "request_id": "web-000123" }), }); const answer = await res.json(); ``` ```python import os, requests res = requests.post( "https://api.orkero.app/v1/voice/lines", headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"}, json={ "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "number": "new", "answer": "always", "handover": "", "can": [ "booking" ], "request_id": "web-000123" }, ) answer = res.json() ``` ### Answer (201) ```json { "ok": true, "line": { "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "number": "", "forwarding_to_us": true, "answer": "always", "handover": "", "can": [ "booking" ], "state": "setting_up" }, "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`. | ## Change when Voice answers, or what it may do `POST /v1/voice/lines/change` > **Early access.** Designed and published so you can plan against it; not open yet. Scope: `voice.lines`. ### Body | Field | Type | Needed | What it is | | --- | --- | --- | --- | | `practice_id` | string (uuid) | yes | | | `id` | string (uuid) | yes | | | `answer` | string | | When Voice answers. One of `always`, `unanswered`, `off`. | | `handover` | string | | | | `can` | array of string | | | ### Example ```bash curl -X POST "https://api.orkero.app/v1/voice/lines/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","answer":"always","handover":"","can":["booking"]}' ``` ```typescript const res = await fetch("https://api.orkero.app/v1/voice/lines/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", "answer": "always", "handover": "", "can": [ "booking" ] }), }); const answer = await res.json(); ``` ```python import os, requests res = requests.post( "https://api.orkero.app/v1/voice/lines/change", headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"}, json={ "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "answer": "always", "handover": "", "can": [ "booking" ] }, ) answer = res.json() ``` ### Answer (200) ```json { "ok": true, "line": { "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "number": "", "forwarding_to_us": true, "answer": "always", "handover": "", "can": [ "booking" ], "state": "setting_up" }, "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`. | | 422 | A field is wrong; the message says which and why. `refused` carries words for the person booking. | ## Read the call log `GET /v1/voice/calls` > **Early access.** Designed and published so you can plan against it; not open yet. Each call Voice took: why the person rang, what was done, how long it took and whether it was handed over. A transcript and the caller's number are never in the log: they stay in Orkero, behind the practice's own access rules. Scope: `voice.calls`. ### Query | Name | Type | Needed | What it is | | --- | --- | --- | --- | | `practice_id` | string (uuid) | yes | | | `after` | string (uuid) | | | | `limit` | integer | | Default `50`. From 1 to 100. | ### Example ```bash curl "https://api.orkero.app/v1/voice/calls?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" \ -H "Authorization: Bearer $ORKERO_KEY" ``` ```typescript const res = await fetch("https://api.orkero.app/v1/voice/calls?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", { method: "GET", headers: { Authorization: `Bearer ${process.env.ORKERO_KEY}`, }, }); const answer = await res.json(); ``` ```python import os, requests res = requests.get( "https://api.orkero.app/v1/voice/calls?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", headers={"Authorization": f"Bearer {os.environ['ORKERO_KEY']}"}, ) answer = res.json() ``` ### Answer (200) ```json { "ok": true, "calls": [ { "id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "line_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "started_at": "2026-11-24T09:00:00+00:00", "seconds": 1, "reason": "", "outcome": "dealt_with", "booking_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" } ], "has_more": true, "next_after": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99", "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`. | | 422 | A field is wrong; the message says which and why. `refused` carries words for the person booking. |