How to integrate ABDM with your HMIS, step by step

01Decide the scope

An HMIS team usually receives the requirement as “make us ABDM compliant”. That is not a specification. ABDM certifies integrations by milestone, and the first decision is which ones you are claiming:

• M1 — create and verify ABHA for patients.
• M2 — act as a Health Information Provider: link records to ABHA and share them under consent.
• M3 — act as a Health Information User: request records from elsewhere with the patient’s consent.

A hospital HMIS almost always needs all three, because a hospital both creates records and needs to read them; the HIP versus HIU guide explains why. The registries, the Health Facility Registry (HFR) and Healthcare Professional Registry (HPR), are prerequisites for all of it, and some vendors count them as a fourth milestone. The milestones guide covers what “M4” means to different people.

The second decision is who owns the ABDM protocol work: your team, or a connector you call. That choice changes the effort of steps 3, 6 and 9 below far more than the rest, so it is discussed at the end, once the work is visible.

02Register the facility

Nothing on the network works for a hospital that is not in HFR. Linking, consent and Scan & Share are all per facility, keyed on its HFR identity.

A facility manager with an HPR identity

HFR registration is done by a person, the facility manager, who signs in with a Healthcare Professional Registry identity. If your customer’s administrator has none, creating one (Aadhaar OTP, mobile verification, an HPR ID) is the first task, and it takes longer than people expect because it depends on one specific person being available with their phone.

One entry per physical site, found before it is created

Register each physical site a patient can walk into, not each legal entity or each department. A hospital group with three campuses needs three entries.

Search first. Hospitals are often already in HFR, entered by a state programme or by a previous vendor, and a duplicate cannot be removed by you: only NHA can merge it, through a support conversation that takes weeks. HFR offers a deduplication check; run it for every site. If the facility already exists, the manager proves control of it through an OTP sent to the contact HFR holds, rather than registering again.

New registration is a short multi-step flow: basic details, additional information, detailed information, then submit, all tied together by a tracking id that only the first step returns. Keep that id; there is no way to look it up later. Some submissions go to review before HFR issues an id, so model “submitted” and “registered” as different states.

03Bridge and linkage

ABDM is asynchronous. You send a request to the gateway; the answer arrives later as an HTTP call from ABDM to a URL you registered, called the bridge URL. It must be public HTTPS, reachable from the internet, and it is the same URL for every facility your software serves. On-premise HMIS installations therefore need a public endpoint somewhere, even if the database never leaves the hospital.

Then comes the step most often missed: bridge linkage. Each facility’s HIP and HIU services must be linked to your software’s bridge in HFR. A facility that skips it is in HFR, authenticates against the gateway without complaint, and has every linking call rejected, with no error that names linkage as the cause. Put a check for it in your onboarding checklist and in your support runbook.

The integration walkthrough covers the gateway session token and request headers that every call needs.

04ABHA at registration

The ABHA screen sits beside the existing new-patient and revisit screens. The design problem is the queue: a government OPD at nine in the morning has one operator and patients who did not all bring a phone. Offer every route ABDM supports, not just the OTP one.

Two things catch HMIS teams out. Find ABHA returns masked numbers; they help the operator pick the right account but are not identifiers, and must never be saved to a patient record. And there is no ABDM v3 call that verifies an existing ABHA against the name and birth date you already hold. Write-ups that describe one are describing the retired v1 API. Do not promise a hospital that feature.

Link the ABHA to the MRN

Once identity is established, store the ABHA number and address against the hospital’s own patient record. Every later visit reuses it. If the MRN is already linked to a different ABHA, refuse and ask a human to resolve it. Silently re-pointing the link would route one person’s future records to another’s account.

05Map care contexts

A care context is the unit the patient sees in their PHR app and the unit they consent over. Choosing it well is a product decision disguised as a data-model one.

• OPD visit → one care context, carrying the consultation and prescription.
• Inpatient admission → one care context, whose main record is the discharge summary.
• Lab or radiology order → one care context per order, carrying the report.

Three rules keep the mapping sound:

1. A stable reference. Use the HMIS’s own visit, admission or order id. Re-sending the same reference updates the record; a freshly generated one duplicates it in the patient’s timeline.
2. A clinical date. Store when the care happened, not when the row was written. Consent date ranges are about clinical time, and a report uploaded late must still fall inside the right range.
3. A display the patient recognises. “OPD – General Medicine, 3 Sep 2026” rather than “ENC-000481223”.

Each care context also carries a health information type, such as OPConsultation, Prescription, DiagnosticReport or DischargeSummary. It decides how the record is coded and which consents can reach it.

06Generate FHIR records

Records travel as FHIR R4 document bundles conforming to the profiles published by NRCeS, the National Resource Centre for EHR Standards. For an HMIS the work divides into three parts:

• Mapping. Your prescription table becomes MedicationRequest resources, lab results become Observations inside a DiagnosticReport, and so on, all under a Composition whose type matches the care context’s health information type.
• Coding. SNOMED CT for clinical concepts and LOINC for lab tests, where you can map them reliably. Free text remains valid, and a wrong code is worse than none.
• Scanned paper. Many hospital records exist only as a PDF. They can be embedded as attachments, provided they really are PDFs.

Validate each bundle when the record is created, not when a consent arrives months later. At creation time the person who typed the record can fix it; at transfer time the patient simply sees a gap. The FHIR guide covers bundle structure, codes and the validation errors that most often cause rejection.

07Link and notify

A care context the patient cannot see is useless to them. Linking puts it on their ABHA, and there are two paths, both of which an HMIS needs.

HIP-initiated

When the ABHA is already on the MRN, the HMIS links new care contexts itself: request a link token for the patient, then add the care contexts with it. Trigger this from the events that already exist in the HMIS — visit closed, discharge signed, report authorised — rather than from a nightly batch, so the record appears while the patient still remembers the visit.

Pair it with the deep-link SMS, which tells the patient that the hospital has records for them and takes them to their PHR app.

User-initiated

A patient can also search for the hospital in their PHR app. ABDM then calls your bridge with their identifiers; you find the matching patient, list the unlinked care contexts, send an OTP to confirm, and complete the link when it comes back. Your matching must be strict. A verified ABHA address is conclusive; a mobile number shared by a family matches several patients and should be reported as ambiguous rather than resolved to the first hit.

Discovery and link responses group care contexts by health information type, with hiType given once for each group. Sending it inside each care context instead is rejected, even when the value is valid.

08Handle consent

As a HIP, the HMIS receives consent artefacts granted over its records and, later, requests for data under them. It must check the artefact again when the request arrives and release only the care contexts inside its health information types, date range and patient. The HIP never sees the original request, only what the patient granted.

As an HIU, the HMIS needs clinician-facing screens: a “request records” action on the patient chart that raises a consent request with a purpose, the types and dates wanted, and an erase-by date; a status the doctor can see while the patient decides; and a viewer for received records. Behind the viewer sit two obligations: erase received records when the artefact’s erase-by date passes, and stop showing them the moment consent is revoked.

The full sequence, and who sees which status, is laid out in the HIP versus HIU guide.

09Callbacks and audit

Most abandoned ABDM projects do not stop at the first API call. They stop when answers start arriving on a separate channel, out of order, sometimes twice, sometimes days later. Treat the bridge as a first-class component:

• Verify every callback. ABDM signs its calls; check the token against the gateway’s published signing keys (its JWKS). Without that, anyone who discovers your bridge URL can forge a consent notification.
• Persist before processing. Write the raw callback to the database, acknowledge, then process from a queue. A bug in processing becomes a replay, not a lost message and a support case with NHA.
• Be idempotent. The gateway delivers at least once. Key each callback on its path and request id so a duplicate is recognised, and reuse the same request id when you retry outbound calls.
• Correlate. Store the request id of everything you send and the business object it belongs to, so a callback can find the registration, link or consent it answers.
• Separate the slow work. Building and encrypting a large transfer should not delay an acknowledgement ABDM is waiting for.
• Surface failures. A callback that fails every retry must reach a person. Silence means a hospital believes a record was shared and the patient believes it was not.

The audit trail

Record every outbound ABDM call, every inbound callback and every privacy-significant change — link created, consent granted, records released, records erased — with who, what, when and under which artefact. Make it append-only. You will need it during testing, during the security audit, and the first time a patient asks who saw their records.

10Sandbox to production

Build and test everything against the ABDM sandbox first. Sandbox access is open to any registered integrator; production is gated. The usual sequence:

Prepare before booking the testing agency, whose time is paid for. Have a recorded walkthrough of each milestone on the HMIS a hospital will actually use, including the patient’s side in the PHR app, and keep the request ids of each run: when someone asks what you sent, that id is what their systems can find. Many test cases have a user-interface half — consent text, OTP resend timers, how the ABHA card is shown — that only the HMIS can demonstrate.

Production keys are issued to your software, but every hospital still goes live individually: its own HFR entry, its own linkage to your production bridge. Budget onboarding effort per customer, not just once. The sandbox page has more on the environment itself.

11Build or use a connector

Looking back over the list, the work splits in two. Registration screens, MRN linkage, care-context mapping, clinician workflows and record mapping are HMIS work no one else can do, because they depend on your data model and your users. Gateway sessions, callback verification, correlation, retries, FHIR assembly, encryption and the ABDM payload quirks are protocol work, the same for every HMIS.

Building the protocol layer yourself gives you full control and no third party in the data path. The cost is months of specialist work, then a permanent obligation to follow every ABDM specification change, sandbox quirk and security finding, usually with a team that has other priorities.

Using a connector removes most of that build from the timeline and turns ABDM into ordinary REST calls and webhooks. The cost is a dependency: a vendor’s uptime, pricing and roadmap now sit in your path, and records pass through their infrastructure, so their security posture becomes part of your audit and your contracts with hospitals. Neither option removes the functional testing, the security audit or the HMIS-side work above.