Skip to main content
An encounter is a visit, as the clinic documents it: one visit note. Every clinical note a clinic writes about a patient is an encounter, and an encounter’s id is the same as the note’s id, so you can read the note’s text with Notes when your key may. An encounter carries no clinical text. It tells you that a visit happened or is open, its type, when it started and ended, the reason given for it, who the clinician is, and where it came from. The note itself, its diagnoses, treatment and signatures stay behind notes:read, and billing is never part of it. Opening an encounter opens a draft visit. It appears in the clinic’s consultation list for a clinician to complete. Nothing is ordered, prescribed, billed, signed, locked or finalised by your request, and no request can do any of those. These are patient-data permissions: the API add-on, the agreement and, for an organization, the approval for the Visits kind all apply. See Permissions. A patient the clinic has restricted, a visit that does not exist, and a note the clinic has marked sensitive all return 404 with code: "not_found". They are never told apart, and a sensitive note is never listed. See Errors.

​
What an encounter looks like

A visit documented by staff before this release has no class, period or reason: they read as null.

​
List visits

​
Open a draft visit

The answer is 201 Created with the encounter. Idempotency-Key is required. Repeating a request with the same key and the same body returns the same encounter with idempotent_replay: true; the same key with a different body is refused. See Retries and duplicates. You may send patient_id, clinician_id, class, started_at, ended_at, reason and origin_assistant_name. patient_id and clinician_id are required, and clinician_id must be a clinician who may hold a note at that clinic. There is no field for note text: a field this list does not name, note_content included, is refused with invalid_request and the error names the field. ended_at cannot be before started_at, and reason is at most 500 characters. What a clinician then sees:
  • A draft note for the patient, marked From your app’s name and not yet reviewed. It is in the clinic’s consultation list, waiting to be completed.
  • The visit details you sent, under Visit details on the note.
  • The note is empty. Nothing is ordered, prescribed or billed by opening it, and the clinician writes the note.

​
Change a visit’s details

PATCH accepts class, started_at, ended_at and reason, at least one. Each value you send replaces the current one. patient_id and clinician_id cannot be changed. You can change only a draft your own app opened, and only until a person has touched it: A clinician can edit a visit’s details on the note, on any note they may edit. Once they do, the visit is theirs and your app can no longer change it. This is deliberate. Read the visit again to see what the clinic recorded. See Errors.

​
One id for the visit and its note

An encounter and its note are the same record, so the id works in both places. A key with notes:read can read the note’s text at GET /v1/clinics/{clinic_id}/notes/{id}; encounters:read alone never returns it. Notes created through the API cannot carry treatment, service or diagnosis blocks: those are refused with unknown_field, which is why a draft visit opens empty and stays free of orders.

​
As FHIR

Send Accept: application/fhir+json and a list becomes a Bundle of Encounter, a single read a bare Encounter. A visit with no known class is shown as unknown rather than guessed. Writes are JSON only: a FHIR body on these routes is refused. See FHIR.

​
Test keys

A test key sees one fictional completed encounter for each sandbox patient, plus the draft visits it opens itself. A test key’s clinician_id must be one of the sandbox clinicians.