Skip to main content

Encounters

An encounter represents a clinical interaction — an office visit, hospital admission, telehealth session, or emergency room visit.

Create an Encounter

const { data: encounter } = await clinik.encounters.create({
  status: 'in-progress',
  class: 'AMB', // ambulatory
  patientId: 'pt_abc123',
  practitionerId: 'prac_def456',
  participants: [
    { practitionerId: 'prac_nurse01', role: 'nurse' },
  ],
  type: 'Annual wellness visit',
  serviceType: 'General Practice',
  reasonCode: 'Routine health maintenance',
  period: {
    start: '2025-01-15T09:00:00Z',
  },
  location: 'Main Clinic - Room 204',
  serviceProvider: 'Austin Family Medicine',
  appointmentId: 'appt_abc123',
  diagnosis: [
    { condition: 'Essential hypertension', use: 'AD', rank: 1 },
    { condition: 'Type 2 diabetes mellitus', use: 'DD', rank: 2 },
  ],
});

Encounter Classes

CodeDescription
AMBAmbulatory (outpatient visit)
IMPInpatient (hospital admission)
EMEREmergency
HHHome health
VRVirtual / telehealth

Status Values

plannedarrivedtriagedin-progressonleavefinished / cancelled

Read an Encounter

const { data: encounter } = await clinik.encounters.read('enc_xyz789');

Update an Encounter

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,
  serviceProvider: 'Austin Family Medicine',
  diagnosis: [
    { condition: 'Essential hypertension', use: 'AD', rank: 1 },
    { condition: 'Type 2 diabetes mellitus', use: 'DD', rank: 2 },
    { condition: 'Obesity', use: 'DD', rank: 3 },
  ],
});

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,
});

Inpatient Encounters

For hospital admissions, include hospitalization details:
const { data: admission } = await clinik.encounters.create({
  status: 'in-progress',
  class: 'IMP', // inpatient
  patientId: 'pt_abc123',
  practitionerId: 'prac_def456',
  type: 'Surgical admission',
  reasonCode: ['Appendicitis', 'Acute abdominal pain'],
  hospitalization: {
    admitSource: 'Emergency department',
    origin: 'Austin General ER',
    dietPreference: ['regular'],
    specialArrangement: ['wheelchair'],
  },
  location: 'Ward 3B - Bed 12',
});

// Discharge the patient
await clinik.encounters.update(admission.id!, {
  status: 'finished',
  hospitalization: {
    admitSource: 'Emergency department',
    dischargeDisposition: 'Home',
    destination: 'Patient residence',
  },
});

Sub-Encounters

Link related encounters using partOfId:
// Pre-op consultation as part of the admission
await clinik.encounters.create({
  status: 'finished',
  class: 'AMB',
  patientId: 'pt_abc123',
  practitionerId: 'prac_anesthesia01',
  type: 'Pre-operative assessment',
  partOfId: admission.id!,
});

Linking Resources to Encounters

Most clinical resources reference an encounter:
// Observation during an 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' },
});

// 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',
});