Notifications
Leave a note on a notification
Leave a note on a notification using Ovok’s Slim API.
| Method | Path |
|---|---|
POST | /v1/slim/notifications/notes |
Authentication · Access policies
Leaves a note on a notification. A note is a practitioner's comment on a notification, stored as a FHIR Communication whose basedOn points at the alert. The alert itself is never changed.
Auth: Bearer token. The caller must be a practitioner, an admin, a super admin, or hold the "System Owner" access policy. The access policy must grant Patient:read (admins and super admins skip this check). Only a practitioner can write notes.
Scope: The caller's project (from the token). An alert or note from another project, of another kind, or that does not exist answers the same 404.
Request
Body
| Name | Type | Required | Description |
|---|---|---|---|
kind | "oob" | "alarm" | "medical" | "alert" | Yes | The kind of notification the note is for. |
id | string | Yes | The notification's id, 1 to 64 letters, digits or hyphens: the row's commId for oob and alarm, the row's episode.id for medical, the raw alert's id for alert. |
text | string | Yes | The note. Trimmed, then 1 to 2000 characters. |
Behaviour
kindnames the feed the notification comes from:ooboralarmwith the row'scommIdasid,medicalwith the row'sepisode.id, oralertwith a raw Signals alert'sid.idmust belong to a notification of thatkindin your project. Anything else answers 404.- A note on a raw alert is also listed and counted on that alert's episode. Which episode is decided once, when the note is written.
textis trimmed and must be 1 to 2000 characters.- The author is the calling practitioner, never a body field.
- Notes can be left on acknowledged notifications too.
medicalandalertnotes are read from Signals first, so they answer 503signals_unavailablewhile Signals is down. Formedicalthe body carriesretryAfterSecand the response has aRetry-Afterheader. Retry once Signals is back.- Answers 201 with the note as stored.
Example
curl -X POST 'https://api.sandbox.ovok.com/v1/slim/notifications/notes' \
-H "Authorization: Bearer ${OVOK_TOKEN}" \
-H 'Content-Type: application/json' \
-d '{ "kind": "oob", "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21", "text": "Resident was in the bathroom." }'Successful response
201 — The note as stored.
{
"id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b22",
"target": { "kind": "oob", "id": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b21" },
"patientId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b23",
"text": "Resident was in the bathroom.",
"author": { "practitionerId": "3f1c2b7e-8d4a-4c1e-9b2f-6a7d5e4c3b24", "name": "Demo Nurse" },
"createdAt": "2026-10-09T01:58:12.345Z",
"updatedAt": "2026-10-09T01:58:12.345Z"
}| Field | Type | Description |
|---|---|---|
id | string (uuid) | The note's id. Use it with the edit, replace and delete routes. |
target | object | The notification the note was written on. |
target.kind | "oob" | "alarm" | "medical" | "alert" | The kind of notification. A note written on a raw Signals alert and listed on that alert's episode keeps "alert". |
target.id | string | The notification's id: the row's commId for oob and alarm, the row's episode.id for medical, the raw alert's id for alert. |
patientId | string (uuid) | null | The resident's Patient id. null when the notification has no resident. |
text | string | The note's text, trimmed. |
author | object | The practitioner who wrote the note. |
author.practitionerId | string (uuid) | null | The author's Practitioner id. |
author.name | string | null | The author's display name when the note was written. |
createdAt | string (ISO 8601 date-time) | null | When the note was written. |
updatedAt | string (ISO 8601 date-time) | null | When the note was last changed. |
Errors
| Status | Meaning |
|---|---|
401 | Bearer token is missing, invalid or expired. |
403 | You lack Patient:read, are not a practitioner, or your session has no project. |
404 | The notification does not exist, or belongs to another project or another kind. |
422 | The body fails validation (unknown kind, id not 1 to 64 letters, digits or hyphens, or text empty or over 2000 characters). |
503 | kind is medical or alert and Signals could not be reached. The body has error: "signals_unavailable" (signals_unavailable). |
Last updated on