openmrs-sdk

Lightweight, zero-dependency JavaScript/TypeScript client for the OpenMRS REST and FHIR R4 APIs.

Works in Node.js 18+, Deno, Bun, and modern browsers - anywhere fetch is available.

Why openmrs-sdk?

The OpenMRS ecosystem has many frontend-specific packages (@openmrs/esm-*), but no standalone SDK for backend or server-side use. If you're building a Node.js integration, a CLI tool, a data pipeline, or any server-side application that talks to OpenMRS, you've been writing raw fetch calls with Basic Auth headers every time.

openmrs-sdk fills that gap:

Zero dependencies: just your runtime's built-in fetch Dual API support: both REST and FHIR R4 from one client Full TypeScript types: every response is fully typed Tiny footprint: under 20KB minified + gzipped Human-readable errors: "Authentication failed" not "401"

Installation

npm install openmrs-sdk

yarn add openmrs-sdk

pnpm add openmrs-sdk

Quick Start

import { OpenMRS } from 'openmrs-sdk';

const client = new OpenMRS({
  baseUrl: 'https://demo.openmrs.org/openmrs',
  username: 'admin',
  password: 'Admin123',
});

// Validate connection
const isConnected = await client.validate();
console.log('Connected:', isConnected);

// Search patients
const results = await client.patient.search({ q: 'John' });
console.log('Found:', results.results.length, 'patients');

// Get a specific patient
const patient = await client.patient.get('patient-uuid-here');
console.log('Patient:', patient.display);

REST API

The REST API provides full access to OpenMRS resources with CRUD operations.

Patient

// Search by name or identifier
const results = await client.patient.search({ q: 'John Doe' });

// Get by UUID
const patient = await client.patient.get('abc-123-def-456');

// Create
const newPatient = await client.patient.create({
  person: {
    names: [{ givenName: 'Jane', familyName: 'Doe' }],
    gender: 'F',
    birthdate: '1990-01-15',
  },
  identifiers: [
    {
      identifier: 'MRN-001',
      identifierType: 'identifier-type-uuid',
      location: 'location-uuid',
    },
  ],
});

// Update
await client.patient.update('abc-123', { person: { gender: 'M' } });

// Delete (void)
await client.patient.delete('abc-123', 'Duplicate record');

Encounter

// Get all encounters for a patient
const encounters = await client.encounter.getByPatient('patient-uuid');

// Get specific encounter
const encounter = await client.encounter.get('encounter-uuid');

// Create encounter
const newEncounter = await client.encounter.create({
  patient: 'patient-uuid',
  encounterType: 'encounter-type-uuid',
  encounterDatetime: '2026-01-15T10:30:00.000+0000',
  obs: [
    {
      concept: 'concept-uuid',
      value: 120,
    },
  ],
});

Observation

// Get all observations for a patient
const obs = await client.obs.getByPatient('patient-uuid');

// Get specific observation
const observation = await client.obs.get('obs-uuid');

// Create observation
await client.obs.create({
  person: 'patient-uuid',
  concept: 'concept-uuid',
  obsDatetime: '2026-01-15T10:30:00.000+0000',
  value: 37.5,
});

Visit

// Get all visits for a patient
const visits = await client.visit.getByPatient('patient-uuid');

// Get specific visit
const visit = await client.visit.get('visit-uuid');

// Create visit
const newVisit = await client.visit.create({
  patient: 'patient-uuid',
  visitType: 'visit-type-uuid',
  startDatetime: '2026-01-15T08:00:00.000+0000',
});

// End a visit
await client.visit.update('visit-uuid', {
  stopDatetime: '2026-01-15T17:00:00.000+0000',
});

Person

// Get person details
const person = await client.person.get('person-uuid');

// Search
const people = await client.person.search({ q: 'Jane' });

// Update demographics
await client.person.update('person-uuid', { gender: 'F' });

Location

// List all locations
const locations = await client.location.list();

// Search
const results = await client.location.search({ q: 'Clinic' });

// Get specific location
const location = await client.location.get('location-uuid');

Session

// Get current session info
const session = await client.session.get();
console.log('User:', session.user?.username);
console.log('Locale:', session.locale);

// Validate credentials
const valid = await client.session.validate();

FHIR R4 API

The FHIR API provides standardized access to clinical data following the HL7 FHIR R4 specification.

FHIR Patient

// Get by ID
const patient = await client.fhir.patient.get('patient-uuid');
console.log(
  'Name:',
  patient.name?.[0]?.given?.join(' '),
  patient.name?.[0]?.family,
);

// Search
const bundle = await client.fhir.patient.search({ name: 'John' });

// List (returns unwrapped array)
const patients = await client.fhir.patient.list({ _count: 20 });

FHIR Observation

// Get all observations for a patient
const observations = await client.fhir.observation.list({
  patient: 'patient-uuid',
  _count: 100,
});

// Search with specific code
const vitals = await client.fhir.observation.search({
  patient: 'patient-uuid',
  code: '5085AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA',
});

FHIR Condition

// Get diagnoses for a patient
const conditions = await client.fhir.condition.list({
  patient: 'patient-uuid',
});

FHIR Encounter

const encounters = await client.fhir.encounter.list({
  patient: 'patient-uuid',
  _count: 50,
});

FHIR MedicationStatement

const medications = await client.fhir.medicationStatement.list({
  patient: 'patient-uuid',
});

FHIR DiagnosticReport

const reports = await client.fhir.diagnosticReport.list({
  patient: 'patient-uuid',
});

Configuration

const client = new OpenMRS({
  // Required
  baseUrl: 'https://demo.openmrs.org/openmrs',
  username: 'admin',
  password: 'Admin123',

  // Optional
  timeout: 30000, // Request timeout in ms (default: 30000)
});

| Option | Type | Required | Default | Description | | ---------- | -------- | -------- | ------- | ---------------------------------------------- | | baseUrl | string | Yes | - | OpenMRS instance URL (include /openmrs path) | | username | string | Yes | - | OpenMRS username | | password | string | Yes | - | OpenMRS password | | timeout | number | No | 30000 | Request timeout in milliseconds |

Error Handling

All errors throw OpenMRSError with clear, actionable messages:

import { OpenMRS, OpenMRSError } from 'openmrs-sdk';

try {
  const patient = await client.patient.get('nonexistent-uuid');
} catch (error) {
  if (error instanceof OpenMRSError) {
    console.log(error.message); // "Resource not found: check the ID or endpoint"
    console.log(error.status); // 404
    console.log(error.statusText); // "Not Found"
    console.log(error.body); // Raw response body
  }
}

| Status | Message | | ------ | -------------------------------------------------------------------- | | 401 | Authentication failed: check your username and password | | 403 | Access denied: your user does not have permission for this operation | | 404 | Resource not found: check the ID or endpoint | | 500 | OpenMRS server error: the server encountered an internal error | | 0 | Network error or request timeout |

Real-World Examples

Clinical Decision Support Pipeline

Pull patient data for AI-powered clinical insights:

const client = new OpenMRS({
  baseUrl: 'https://my-clinic.org/openmrs',
  username: 'integration-user',
  password: 'secure-password',
});

// Gather comprehensive patient data
const patient = await client.fhir.patient.get(patientId);
const observations = await client.fhir.observation.list({
  patient: patientId,
  _count: 200,
});
const conditions = await client.fhir.condition.list({ patient: patientId });
const medications = await client.fhir.medicationStatement.list({
  patient: patientId,
});

// Feed into your analysis pipeline
const clinicalSummary = {
  demographics: patient,
  labs: observations,
  diagnoses: conditions,
  treatments: medications,
};

OpenMRS → DHIS2 Reporting

Aggregate clinical data for national health reporting:

// Fetch encounters for a reporting period
const encounters = await client.encounter.getByPatient(patientId);

// Count encounters by type for aggregate reporting
const malariaCases = encounters.results.filter(
  (e) => e.encounterType.display === 'Malaria Consultation',
);

// Push count to DHIS2 via dhis2 API or n8n-nodes-dhis2
console.log(`Malaria cases this month: ${malariaCases.length}`);

Bulk Patient Search

// Paginate through all patients
let startIndex = 0;
const allPatients = [];

while (true) {
  const page = await client.patient.search({
    v: 'default',
    limit: 100,
    startIndex,
  });

  allPatients.push(...page.results);

  if (page.results.length < 100) break;
  startIndex += 100;
}

console.log(`Total patients: ${allPatients.length}`);

Express.js API Endpoint

import express from 'express';
import { OpenMRS } from 'openmrs-sdk';

const app = express();
const client = new OpenMRS({
  baseUrl: process.env.OPENMRS_URL!,
  username: process.env.OPENMRS_USER!,
  password: process.env.OPENMRS_PASS!,
});

app.get('/api/patients/:id', async (req, res) => {
  try {
    const patient = await client.patient.get(req.params.id);
    res.json(patient);
  } catch (error) {
    res.status(error.status || 500).json({ error: error.message });
  }
});

API Reference

REST Resources

| Resource | Methods | | ----------- | ------------------------------------------------------------- | | patient | get, search, create, update, delete | | encounter | get, search, getByPatient, create, update, delete | | obs | get, search, getByPatient, create, delete | | visit | get, search, getByPatient, create, update, delete | | person | get, search, update | | location | get, search, list | | session | get, validate |

FHIR R4 Resources

| Resource | Methods | | -------------------------- | ----------------------- | | fhir.patient | get, search, list | | fhir.encounter | get, search, list | | fhir.observation | get, search, list | | fhir.condition | get, search, list | | fhir.medicationStatement | get, search, list | | fhir.diagnosticReport | get, search, list |

search returns the raw FHIR Bundle. list returns an unwrapped array of resources.

Compatibility

• Runtime: Node.js 18+, Deno, Bun, modern browsers
• OpenMRS: 2.3+ with FHIR2 module (for FHIR endpoints)
• Module: ESM and CommonJS (dual package)
• TypeScript: Full type definitions included

Demo Server

You can test against the OpenMRS demo server:

Base URL:  https://demo.openmrs.org/openmrs
Username:  admin
Password:  Admin123

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Related Projects

• n8n-nodes-openmrs - n8n community node for OpenMRS workflow automation
• n8n-nodes-dhis2 - n8n community node for DHIS2 health data reporting

License

MIT - Copyright (c) 2026 Monfort Brian N.

Support

• Issues: GitHub Issues
• OpenMRS Wiki: wiki.openmrs.org
• FHIR R4 Spec: hl7.org/fhir/R4

Made with ❤️ for the global health community