Encounter

The Encounter resource represents an interaction between a patient and a healthcare provider. Every visit, consultation, or care episode is recorded as an Encounter.

API convention: the primary patient reference is sent as a flat string field (subjectId) rather than a nested FHIR reference object. Other references inside the request (participant individuals, service providers, etc.) use the standard reference shape when the API accepts them. All resource ids are raw UUIDs (v4) — no type prefixes.

Encounter Classes

The class field is sent as a short string code (max 20 chars). Common values:

Code	Description
`ambulatory`	Office or outpatient visit
`emergency`	Emergency room visit
`inpatient`	Hospital admission
`day`	Day procedure or clinic
`field`	Home or worksite visit

Creating an Encounter

curl -X POST https://api.esus.health/fhir/Encounter \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/fhir+json" \
  -d '{
    "status": "finished",
    "class": "ambulatory",
    "subjectId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "serviceProviderId": "b8c2d3e4-f5a6-7890-bcde-f01234567890",
    "reasonCode": [
      { "coding": [{ "code": "185345009", "display": "Encounter for symptom" }] }
    ]
  }'

Participants and Practitioners

Nested participants use the standard FHIR reference shape:

{
  "participant": [
    {
      "type": [{ "coding": [{ "code": "PPRF", "display": "Principal Performer" }] }],
      "individual": {
        "reference": "Practitioner/a7b1c2d3-e4f5-6789-abcd-ef0123456789",
        "display": "Dr. Maria Garcia"
      }
    }
  ]
}

Encounter Statuses

Status	Meaning
`planned`	Scheduled but not yet started
`arrived`	Patient has arrived
`triaged`	Patient is triaged and waiting
`in-progress`	Encounter is ongoing
`onleave`	Patient is temporarily off-site
`finished`	Encounter completed
`cancelled`	Encounter was cancelled

Lifecycle Operations

Beyond standard CRUD, the API exposes operations for admission workflows:

POST /fhir/Encounter/{id}/$admit — transition to admitted state
POST /fhir/Encounter/{id}/$discharge — finalize and discharge
POST /fhir/Encounter/{id}/$transfer — move to another location
GET /fhir/Encounter/{id}/$everything — return the patient chart bundle centered on this encounter

Why Encounters Matter

Every clinical record — observations, conditions, procedures — should be linked to an Encounter. This creates a complete record of the patient’s care journey.