Docs
View as Markdown

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"

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"}'

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"]}'

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"

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.