Notifications

Leave a note on a notification

Leave a note on a notification using Ovok’s Slim API.

MethodPath
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

NameTypeRequiredDescription
kind"oob" | "alarm" | "medical" | "alert"YesThe kind of notification the note is for.
idstringYesThe 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.
textstringYesThe note. Trimmed, then 1 to 2000 characters.

Behaviour

  • kind names the feed the notification comes from: oob or alarm with the row's commId as id, medical with the row's episode.id, or alert with a raw Signals alert's id.
  • id must belong to a notification of that kind in 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.
  • text is 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.
  • medical and alert notes are read from Signals first, so they answer 503 signals_unavailable while Signals is down. For medical the body carries retryAfterSec and the response has a Retry-After header. 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"
}
FieldTypeDescription
idstring (uuid)The note's id. Use it with the edit, replace and delete routes.
targetobjectThe 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.idstringThe 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.
patientIdstring (uuid) | nullThe resident's Patient id. null when the notification has no resident.
textstringThe note's text, trimmed.
authorobjectThe practitioner who wrote the note.
author.practitionerIdstring (uuid) | nullThe author's Practitioner id.
author.namestring | nullThe author's display name when the note was written.
createdAtstring (ISO 8601 date-time) | nullWhen the note was written.
updatedAtstring (ISO 8601 date-time) | nullWhen the note was last changed.

Errors

StatusMeaning
401Bearer token is missing, invalid or expired.
403You lack Patient:read, are not a practitioner, or your session has no project.
404The notification does not exist, or belongs to another project or another kind.
422The body fails validation (unknown kind, id not 1 to 64 letters, digits or hyphens, or text empty or over 2000 characters).
503kind is medical or alert and Signals could not be reached. The body has error: "signals_unavailable" (signals_unavailable).

Last updated on

On this page