# Leave a note on a notification

Canonical page: https://docs.ovok.com/slim-apis/notifications/leave-a-note-on-a-notification

| Method | Path |
| --- | --- |
| `POST` | `/v1/slim/notifications/notes` |

[Authentication](/authentication) · [Access policies](/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 [#request]

### Body [#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 [#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`](/errors/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 [#example]

```bash
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 [#successful-response]

`201` — The note as stored.

```json
{
  "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 [#errors]

| Status | Meaning |
| --- | --- |
| [`401`](/errors/unauthenticated) | Bearer token is missing, invalid or expired. |
| [`403`](/errors/forbidden) | You lack `Patient:read`, are not a practitioner, or your session has no project. |
| [`404`](/errors/not-found) | The notification does not exist, or belongs to another project or another kind. |
| [`422`](/errors/validation-failed) | The body fails validation (unknown `kind`, `id` not 1 to 64 letters, digits or hyphens, or `text` empty or over 2000 characters). |
| [`503`](/errors/service-unavailable) | `kind` is `medical` or `alert` and Signals could not be reached. The body has `error: "signals_unavailable"` ([`signals_unavailable`](/errors/signals-unavailable)). |
