Voice reference
The phone agent (Orkero Voice): answers a practice's calls, deals with them, books and hands over to a person when needed.
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 |
List a practice's lines | voice.lines |
POST /v1/voice/lines |
Give a practice a phone line answered by Voice | voice.lines |
POST /v1/voice/lines/change |
Change when Voice answers, or what it may do | voice.lines |
GET /v1/voice/calls |
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
curl "https://api.orkero.app/v1/voice/lines?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" \
-H "Authorization: Bearer $ORKERO_KEY"
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();
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)
{
"ok": true,
"lines": [
{
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"number": "<number>",
"forwarding_to_us": true,
"answer": "always",
"handover": "<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
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":"<handover>","can":["booking"],"request_id":"web-000123"}'
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": "<handover>",
"can": [
"booking"
],
"request_id": "web-000123"
}),
});
const answer = await res.json();
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": "<handover>",
"can": [
"booking"
],
"request_id": "web-000123"
},
)
answer = res.json()
Answer (201)
{
"ok": true,
"line": {
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"number": "<number>",
"forwarding_to_us": true,
"answer": "always",
"handover": "<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
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":"<handover>","can":["booking"]}'
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": "<handover>",
"can": [
"booking"
]
}),
});
const answer = await res.json();
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": "<handover>",
"can": [
"booking"
]
},
)
answer = res.json()
Answer (200)
{
"ok": true,
"line": {
"id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"practice_id": "0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99",
"number": "<number>",
"forwarding_to_us": true,
"answer": "always",
"handover": "<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
curl "https://api.orkero.app/v1/voice/calls?practice_id=0b6e5a2c-4f1d-4c8e-9a3b-2d7f6e1c0a99" \
-H "Authorization: Bearer $ORKERO_KEY"
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();
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)
{
"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": "<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. |