Functional standard / Interactions / PatientInstance
Encounter
A clinical interaction grouped by time and setting: a visit, a teleconsult, a home visit, an admission.
- Kind
- encounter
- Collection
- /v1/encounters
- Initial state
- pending
- Classification
- Operational
Scope and usage
The container for a clinical record. A connector such as Calendly may open a scheduled encounter and later cancel it. It uses a system actor.
Boundaries and relationships
- The note is not on the encounter. It is a NotePage inside a ClinicalRecord.
- A booking in an external calendar is not stored here beyond start time, type, and status.
Resource content
Elements this resource adds. It also carries the Instance, including patient_id.
| Name | Card. | Type | Flags | Description |
|---|---|---|---|---|
| encounter_type | 1..1 | code | — | Defaults to visit. Definitions supply opd_visit, teleconsult, and local types. |
| setting_id | 0..1 | id | — | ClinicalSetting. |
| start_at | 0..1 | dateTime | — | When it starts. |
| duration_min | 0..1 | integer | — | Planned duration. |
| reason | 0..1 | string | — | Why the patient is being seen. |
State machine
pending/ initial — Opened, not yet timed.scheduled— Has a time. A calendar connector uses this.closed— The interaction is over. Frozen.cancelled— Did not happen. Frozen.
pending → scheduled, closed, cancelled. scheduled → pending, closed, cancelled.
Frozen: closed and cancelled.
Invariants
ccs-enc-1— A system actor from a calendar connector may create and cancel. It may not finalize a note page in this encounter.
Operations
| Method | Path | Meaning |
|---|---|---|
| GET | /v1/encounters | List encounter. Filter by patient_id, status, and where the model has them, encounter_id or definition_key. |
| POST | /v1/encounters | Create a encounter. Body is the resource minus harness-owned elements. |
| GET | /v1/encounters/{id} | Read one encounter. |
| PATCH | /v1/encounters/{id} | Update elements that are not immutable, frozen, or harness-owned. |
| POST | /v1/encounters/{id}/transition | Move status. Body is { to, reason }. A gated move returns 202 and an Approval. |
| DELETE | /v1/encounters/{id}?reason= | Soft-delete. Reason is required. Refused when the resource is not deletable or is frozen. |
Notes
- Definition kind encounter. The definition can name note pages to open by default.
Example
{ "patient_id": "pat_…", "encounter_type": "opd_visit", "start_at": "2026-10-20T09:30:00Z", "reason": "Review" }