Skip to main content

Labs

Labs (FHIR DiagnosticReport) represent diagnostic reports — lab panels, radiology reports, pathology results. They group related observations and provide clinical conclusions.

Create a Lab Report

const { data: lab } = await clinik.labs.create({
  status: 'final',
  code: {
    system: 'http://loinc.org',
    code: '24323-8',
    display: 'Comprehensive metabolic 2000 panel',
  },
  patientId: 'pt_abc123',
  encounterId: 'enc_xyz789',
  category: 'LAB',
  effectiveDateTime: '2025-01-15T10:30:00Z',
  performer: 'prac_lab_tech',
  resultsInterpreter: 'prac_def456',
  resultIds: ['obs_glucose', 'obs_sodium', 'obs_potassium', 'obs_creatinine'],
  conclusion: 'All values within normal limits. No significant abnormalities.',
  conclusionCodes: [
    {
      system: 'http://snomed.info/sct',
      code: '281900007',
      display: 'No abnormality detected',
    },
  ],
});

Effective Period

For reports that span a time range (e.g. 24-hour urine collection):
const { data } = await clinik.labs.create({
  status: 'final',
  code: { system: 'http://loinc.org', code: '21482-5', display: '24 hour urine protein' },
  patientId: 'pt_abc123',
  category: 'LAB',
  effectivePeriod: {
    start: '2025-01-14T08:00:00Z',
    end: '2025-01-15T08:00:00Z',
  },
  conclusion: 'Protein within normal range.',
});

Based On (ServiceRequest)

Link a report to the order that requested it:
const { data } = await clinik.labs.create({
  status: 'final',
  code: { system: 'http://loinc.org', code: '24323-8', display: 'CMP' },
  patientId: 'pt_abc123',
  basedOn: ['sr_lab_order_001'],
  // ...
});

Media / Images

Attach images or media to the report:
const { data } = await clinik.labs.create({
  status: 'final',
  code: 'Chest X-Ray',
  patientId: 'pt_abc123',
  category: 'RAD',
  media: [
    { comment: 'PA view', linkId: 'media_xray_pa' },
    { comment: 'Lateral view', linkId: 'media_xray_lat' },
  ],
  conclusion: 'No acute cardiopulmonary disease.',
});

Categories

CodeDescription
LABLaboratory
RADRadiology
PATPathology

Linking Observations

A lab report groups related observations. Create the observations first, then reference their IDs:
// Create individual lab results
const { data: glucose } = await clinik.observations.create({
  status: 'final',
  code: { system: 'http://loinc.org', code: '2339-0', display: 'Glucose' },
  patientId: 'pt_abc123',
  category: 'laboratory',
  valueQuantity: { value: 95, unit: 'mg/dL' },
  interpretation: 'N',
  referenceRange: { low: { value: 70, unit: 'mg/dL' }, high: { value: 100, unit: 'mg/dL' } },
});

// Create the report linking them
const { data: report } = await clinik.labs.create({
  status: 'final',
  code: { system: 'http://loinc.org', code: '24323-8', display: 'CMP' },
  patientId: 'pt_abc123',
  category: 'LAB',
  resultIds: [glucose.id!],
  conclusion: 'All values within normal limits.',
});

Update a Lab Report

await clinik.labs.update('lab_abc123', {
  status: 'amended',
  conclusion: 'Updated: Glucose slightly elevated on recheck.',
  conclusionCodes: [
    { system: 'http://snomed.info/sct', code: '166922008', display: 'Glucose elevated' },
  ],
  resultsInterpreter: 'prac_senior_doc',
});

Read with Included Observations

const { data } = await clinik.labs.read('lab_abc123', {
  include: ['Observation'],
});

Attached Documents

Attach PDF reports or images:
const { data } = await clinik.labs.create({
  status: 'final',
  code: { system: 'http://loinc.org', code: '24323-8', display: 'CMP' },
  patientId: 'pt_abc123',
  category: 'LAB',
  conclusion: 'See attached report.',
  presentedForm: [
    {
      contentType: 'application/pdf',
      url: 'https://storage.clinic.com/reports/lab-2025-001.pdf',
      title: 'CMP Lab Report - Jan 2025',
    },
  ],
});

Status Lifecycle

registeredpartialpreliminaryfinalamended / corrected / appended / cancelled

Search Labs

const { data } = await clinik.labs.search({
  patientId: 'pt_abc123',
  status: 'final',
  dateFrom: '2025-01-01',
  sort: '-date',
});