Clinical Intelligence StandardsVersion 0.2

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

Resource content

Elements this resource adds. It also carries the Instance, including patient_id.

NameCard.TypeFlagsDescription
encounter_type1..1code—Defaults to visit. Definitions supply opd_visit, teleconsult, and local types.
setting_id0..1id—ClinicalSetting.
start_at0..1dateTime—When it starts.
duration_min0..1integer—Planned duration.
reason0..1string—Why the patient is being seen.

State machine

pending → scheduled, closed, cancelled. scheduled → pending, closed, cancelled.

Frozen: closed and cancelled.

Invariants

Operations

MethodPathMeaning
GET/v1/encountersList encounter. Filter by patient_id, status, and where the model has them, encounter_id or definition_key.
POST/v1/encountersCreate 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}/transitionMove 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

Example

{ "patient_id": "pat_…", "encounter_type": "opd_visit", "start_at": "2026-10-20T09:30:00Z", "reason": "Review" }