Feedback reference
Same-day patient feedback (Net Promoter Score).
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 |
Tell us a visit is done | feedback.signals |
GET /v1/feedback/figures |
Read the score | feedback.figures |
GET /v1/feedback/events |
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
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>"}'
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();
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)
{
"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
curl "https://api.orkero.app/v1/feedback/figures" \
-H "Authorization: Bearer $ORKERO_KEY"
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();
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)
{
"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
curl "https://api.orkero.app/v1/feedback/events" \
-H "Authorization: Bearer $ORKERO_KEY"
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();
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)
{
"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. |