# 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":"<visit_id>","person_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": "<visit_id>",
    "person_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": "<visit_id>",
        "person_id": "<person_id>"
    },
)
answer = res.json()
```

### Answer (200)

```json
{
  "ok": true,
  "duplicate": true,
  "test": true,
  "kind": "<kind>",
  "visit_id": "<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`. |
