An encounter represents a clinical interaction between a patient and a practitioner — an office visit, a hospital admission, a telehealth session, or an emergency room visit. The FHIR R4 Encounter resource ties together the context for all clinical documentation: observations, notes, prescriptions, and assessments created during that interaction all reference the encounter by ID.
Create an encounter
const { data: encounter } = await clinik.encounters.create({
status: 'in-progress',
class: 'AMB', // ambulatory
patientId: 'pt_abc123',
practitionerId: 'prac_def456',
type: 'Annual wellness visit',
serviceType: 'General Practice',
reasonCode: 'Routine health maintenance',
period: {
start: '2025-01-15T09:00:00Z',
},
location: 'Main Clinic - Room 204',
diagnosis: [
{ condition: 'Essential hypertension', use: 'AD', rank: 1 },
{ condition: 'Type 2 diabetes mellitus', use: 'DD', rank: 2 },
],
});
Encounter classes
| Code | Description |
|---|
AMB | Ambulatory (outpatient visit) |
IMP | Inpatient (hospital admission) |
EMER | Emergency |
HH | Home health |
VR | Virtual / telehealth |
Status values
Encounters progress through a defined lifecycle:
planned → arrived → triaged → in-progress → onleave → finished / cancelled
Read an encounter
const { data: encounter } = await clinik.encounters.read('enc_xyz789');
Update an encounter
When a visit ends, close it out by setting status: 'finished' and filling in the end time and duration:
const { data: updated } = await clinik.encounters.update('enc_xyz789', {
status: 'finished',
period: {
start: '2025-01-15T09:00:00Z',
end: '2025-01-15T09:45:00Z',
},
lengthMinutes: 45,
});
Delete an encounter
await clinik.encounters.delete('enc_xyz789');
Deleting an encounter does not remove resources that reference it. Observations, notes, and assessments linked to the encounter will retain their encounterId reference.
Search encounters
const { data: results } = await clinik.encounters.search({
patientId: 'pt_abc123',
status: 'finished',
dateFrom: '2025-01-01',
dateTo: '2025-03-31',
sort: '-date', // newest first
count: 20,
});
Linking resources to an encounter
Most clinical resources accept an encounterId field. Pass the encounter ID when creating observations, notes, prescriptions, and assessments to tie them to the visit:
// Observation recorded during the encounter
await clinik.observations.create({
status: 'final',
code: { system: 'http://loinc.org', code: '8867-4', display: 'Heart rate' },
patientId: 'pt_abc123',
encounterId: 'enc_xyz789',
valueQuantity: { value: 72, unit: 'beats/minute' },
});
// Clinical note from the encounter
await clinik.notes.create({
patientId: 'pt_abc123',
encounterId: 'enc_xyz789',
authorId: 'prac_def456',
title: 'Visit Summary',
content: 'Patient presents for annual wellness visit...',
type: 'progress-note',
});