> ## Documentation Index
> Fetch the complete documentation index at: https://openloop.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Encounter notes

> Get the clinician's encounter note for an intake: keep the encounter id, add the charting events, and read the note by encounter from the response list.

By the end of this page you will be able to show, for an intake you submitted, the encounter note
the clinician wrote. The note reaches the partner surface as a **questionnaire response on the
same encounter** as your intake. The encounter id is the join: your submit returns it, the
`intake.*` events repeat it, and the `charting.*` events tell you when a form on that encounter
changes and carry the same id. There is no encounter read and no note read; the questionnaire-response list with the
`encounter_id` filter is the only read you need.

## What you'll do

**1. Keep the encounter id**

The `201` from the completed intake submit returns `data.encounter_id`. Store it beside the
response id; it is the key for everything on this page.

**2. Add the three charting events to your endpoint**

`charting.created`, `charting.signed` and `charting.completed` are not part of the default
intake set. Ask your implementation contact to add them (version `1.0`) to the endpoint you
already run.

**3. Learn the encounter id from the events**

`intake.*` and `charting.*` events carry `data.encounter_id`. On a charting event it is the
encounter the note belongs to; match it to the id you stored.

**4. Read the note**

`GET /v0.1/questionnaire-responses?encounter_id=<id>&status=completed` returns your intake and
the note. The note is the row whose `questionnaire_canonical` ends in the event's
`questionnaire_ref`.

## Why the encounter is the join

A completed intake submit creates an encounter and returns its id. When a clinician charts that
encounter, OpenLoop's charting workflow writes the note as a form stamped with the same
encounter, so the note arrives on the partner surface as a second questionnaire response with that
`encounter_id`. Nothing on the note names your response id. The events can carry your `/v0.1`
patient id as `data.emr_patient_id`, but that names the patient, not the intake, and `patient_ref` is
an opaque reference that is not guaranteed to be your `/v0.1` patient id. The encounter id is the one
value that ties the note to your intake, which is why the submit returns it, the events repeat it, and the list filter accepts it.

These are signed webhooks delivered by the same pipeline as every OpenLoop event: one envelope, one
signature scheme, one delivery policy, all documented in [Events](https://openloop.mintlify.site/events.md).

## Recipe 4.6 · Add the charting events to your endpoint

Your endpoint receives only the event types it is subscribed to. The intake family gives you your
own submissions back; the charting family is separate and must be added. Send your implementation
contact the three types, or the family:

| Event type | Version | Sent when |
| - | - | - |
| `charting.created` | `1.0` | A clinician's charting form is created against the encounter |
| `charting.signed` | `1.0` | The form is signed |
| `charting.completed` | `1.0` | The form is completed (finished / locked); the note is final |

A `charting.*` subscription covers all three. `charting.completed` is the one to act on: it sets
`data.status` to `completed`, and the note it announces is readable as a completed response. The
events carry form metadata only, never the note text, so a delivery is a signal to read, not the
content.

Two things to know when you ask. Selections are expanded when the endpoint is saved, so an
endpoint registered with `*` before these types existed still needs updating. And charting fires
for every non-intake clinical form, so consents and provider forms raise these events too: not
every `charting.completed` is a note. Act on the events whose `encounter_id` you hold, and on the
`questionnaire_ref` your implementation contact names as the note form.

> [!NOTE]
>
> Everything on this page is **staging only today**. Charting emission in production is one
> environment-wide switch that OpenLoop has not turned on yet, and the `encounter_id` filter on the
> questionnaire-response list is not in the production release yet either. Your implementation
> contact will tell you when each reaches production.

## Recipe 4.7 · Learn the encounter id from the events

Every `intake.*` and `charting.*` event carries `data.encounter_id`. It is the same value your
completed submit returned, so you can match a delivery to your own record before reading anything.
It is `null` when the form is not linked to an encounter: a charting form a clinician starts outside
the charting workflow, or an intake that did not create one (`status: "in-progress"`, no `subject`).

An `intake.completed` delivery for the intake you submitted:

```json theme={null}
{
  "id": "…",
  "type": "intake.completed",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-19T23:22:29Z",
  "data": {
    "resource_id": "…",
    "status": "completed",
    "patient_ref": "<opaque patient reference; do not assume it is your /v0.1 id>",
    "emr_patient_id": "<your /v0.1 patient id; omitted when not known>",
    "questionnaire_ref": "…",
    "encounter_id": "<the id your submit returned>",
    "…": "…"
  }
}
```

A `charting.completed` delivery for the note written against that encounter:

```json theme={null}
{
  "id": "…",
  "type": "charting.completed",
  "eventVersion": "1.0",
  "occurredAt": "2026-10-20T15:04:11Z",
  "data": {
    "resource_id": "<id of the charting form>",
    "status": "completed",
    "patient_ref": "<opaque patient reference>",
    "emr_patient_id": "<your /v0.1 patient id; omitted when not known>",
    "questionnaire_ref": "<form id>",
    "encounter_id": "<the same id>",
    "authored_at": "2026-10-20T15:04:09Z",
    "extra_fields": { "…": "form metadata only, no answers" }
  }
}
```

Handle it like any other event: verify the signature, drop a repeated envelope `id`, and look up
`data.encounter_id` in the records you keyed in step 1. A charting event whose `encounter_id` you
do not hold is a form on an encounter you did not create; ignore it or log it. A charting event with
`encounter_id: null` is a form outside the workflow; Recipe 4.8 says what you can do with it.

The full field lists are on [Intake payload](https://openloop.mintlify.site/events.md#intake) and [Charting payload](https://openloop.mintlify.site/events.md#charting).

## Recipe 4.8 · Read the note by encounter

On `charting.completed` (or on a schedule, if you are not subscribed yet), list the completed
responses on the encounter. Do not read on `charting.created` or `charting.signed`: the form is
still `in_progress` then (a signed form is not yet locked) and `status=completed` returns nothing
for it.

```
GET /v0.1/questionnaire-responses?encounter_id=<data.encounter_id>&status=completed
Authorization: Bearer <service token>
```

```json theme={null}
{
  "items": [
    {
      "id": "<your intake response id>",
      "questionnaire_id": "<the questionnaire you submitted>",
      "questionnaire_canonical": "Questionnaire/<questionnaire id>",
      "status": "completed",
      "subject": { "type": "Patient", "id": "<your /v0.1 patient id>" },
      "encounter_id": "<the id>",
      "answers": { "…": "your answers, keyed by link_id" },
      "updated_at": "2026-10-19T23:22:03Z"
    },
    {
      "id": "<the note's response id>",
      "questionnaire_canonical": "<the form URL, ending in /<questionnaire_ref>>",
      "status": "completed",
      "subject": { "type": "Patient", "id": "<your /v0.1 patient id>" },
      "encounter_id": "<the id>",
      "answers": { "…": "the note text, keyed by the form's item ids" },
      "updated_at": "2026-10-20T15:04:10Z"
    }
  ],
  "request_id": "…"
}
```

Pick the note with two tests:

1. `questionnaire_canonical` ends in `/<questionnaire_ref>`, the event's `data.questionnaire_ref`
   (the canonical of a charting form is that form's URL; match the tail, the prefix is
   not a contract).
2. `status` is `completed` (the filter already guarantees it).

If several rows match, take the newest `updated_at`. If none is listed yet, retry with backoff: the
event and the row are written by different steps, and the row can land shortly after the delivery.
Do not compare `updated_at` to the event's `occurredAt`; their order is not guaranteed.

Its `answers` carry the note text. Rows the charting workflow writes this way omit `questionnaire_id`
(the key is absent, not `null`), so never filter the list by `questionnaire_id` to find a note, and
never take a row by position: the list also holds your intake, and can hold an in-progress copy of
it that the workflow echoes back (dropped by `status=completed`).

> [!WARNING]
>
> **The note is PHI.** `answers` on that row is the clinician's clinical note about the patient.
> Handle it with the same care as patient data: store it only where you store clinical records, do
> not log it, and do not put it in URLs or analytics.

Without `status=completed` the same call returns every response on the encounter, which is how you
check that the encounter exists and holds your intake before any note is written.

**When `encounter_id` is `null`.** A form a clinician starts outside the charting workflow is
written against the patient only, so find it through the patient. `data.emr_patient_id` is your
`/v0.1` patient id, the `id` that `GET /v0.1/patients/{id}` takes, when the event carries it. That
patient's completed responses list the form:

```
GET /v0.1/questionnaire-responses?subject=Patient/<data.emr_patient_id>&status=completed
```

This list spans every encounter the patient has, so the two tests above can also match an older copy
of the same form. Skip rows you already took for an earlier event, and retry with backoff while no
new one is listed.

The key can be missing: it is omitted when the id isn't known, never `null`. Without it, the event
has only `data.patient_ref`, which is not guaranteed to be a `/v0.1` patient id, so how your tenant
maps it to a patient is agreed with your implementation contact when the endpoint is registered (see
*Matching webhook events to your patients* in [Known gaps and staging](https://openloop.mintlify.site/cookbook/known-gaps-and-staging.md)).

## What comes back

| Field | Where | You key on it for |
| - | - | - |
| `data.encounter_id` | Submit `201`, `GET /v0.1/questionnaire-responses/{id}`, `intake.*` and `charting.*` events | The join between your intake and the note |
| `data.emr_patient_id` | `intake.*` and `charting.*` events, when the id is known | Your `/v0.1` patient id; the `subject` filter for that patient's responses when `encounter_id` is `null` |
| `data.questionnaire_ref` | `charting.*` events | Which form the note is; matches the tail of `questionnaire_canonical` |
| `occurredAt` (envelope) | `charting.*` events | Ordering deliveries for the same form |
| `questionnaire_canonical` | List items | Identifying the note row (ends in `/<questionnaire_ref>`) |
| `answers` | List items | The note text |
| `subject.id` | List items | Your `/v0.1` patient id, the one id on the note that is yours |

## Gotchas

> [!WARNING]
>
> **The event is not the note.** `charting.*` events carry form metadata only: no answers, no note
> body. Read the note with the list filter; do not expect it in the delivery.

> [!WARNING]
>
> **Subscribe to the charting family, or you will never hear about the note.** The intake family does
> not include it, and nothing else announces a note. Until your implementation contact adds
> `charting.*`, the list filter in Recipe 4.8 is the only way to see one.

> [!WARNING]
>
> **`questionnaire_id` is absent on the note.** The key is omitted, not `null`. Match on
> `questionnaire_canonical`, not on `questionnaire_id`, and never by list position.

> [!NOTE]
>
> Webhook events cannot be exercised by the conformance runner, and no check locks this page yet. The
> encounter filter and the note's shape were verified on staging on 2026-10-19; `data.encounter_id` on
> intake and charting events is the contract deployed to staging as of that date.

## Related

> [card] [Integration flow](https://openloop.mintlify.site/cookbook/integration-flow.md)
>
> Recipe 2.3: the completed submit that creates the encounter and returns its id

> [card] [Events](https://openloop.mintlify.site/events.md)
>
> The envelope, the signature, and the intake and charting payloads field by field

> [card] [Order status and tracking](https://openloop.mintlify.site/cookbook/order-status-and-tracking.md)
>
> Recipe 4.1: giving OpenLoop your endpoint, verifying, deduping


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.