Docs
View as Markdown

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

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"

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"

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.