# 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": "<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

```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":"<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": "<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": "<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": "<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

```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":"<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": "<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": "<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": "<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

```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": "<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. |
