ABDM v3 · M1–M4 implemented
Sandbox keys, issued on signup

M4 Health Facility Registry

Register and link facilities in the Health Facility Registry

Before a hospital, clinic or lab can link a single record, the network has to know two things: that the facility exists, and which software speaks for it. HFR records them separately, and most integrations only do the first.

Get sandbox keys The HPR side

01 The sequence

From nothing to a facility that can link records

Six steps in a fixed order, all in the Swastik portal — your integration never registers a hospital itself. Skipping the first costs weeks; skipping the fifth costs a failure that never names itself.

  1. Search the registry

    Facility registry in the portal, by name, HFR id, or state and district. A government hospital or an established private one is often there already, registered by someone else.

  2. Check for a near-duplicate

    The registration form checks the name and address against HFR first and shows facilities that look like this one — including entries with a slightly different spelling that a name search would miss.

  3. Sign in the facility manager

    HFR attributes a registration to a person, so the manager logs in with their HPR credentials by OTP. The token stays server-side, encrypted, for at most 30 minutes.

  4. Register, or claim what exists

    No entry: the four-step registration below. An entry that is already this facility’s: add it by its HFR id, and the connector reads the rest from HFR.

  5. Link its services to the bridge

    Bridge linkage registers the facility’s HIP and HIU services against this connector, under its HFR id.

  6. Activate, and give it to an application

    Activate it under Facilities, then choose it as the hospital of the application whose API key your system uses. From then on the key acts for that hospital, and GET /v1/facility shows it with its HFR record.

what your key sees Sandbox 
# registered and linked in the portal; then
GET /v1/facility
Authorization: Bearer swk_sand_…

← 200 OK
{
  "name": "Sunrise General Hospital",
  "hfr_id": "IN2710004770",
  "hip_id": "IN2710004770",
  "status": "active",
  "hfr_record": {
    "ownership": "PRIVATE",
    "facilityStatus": "Submitted",
    …
  }
}
   ↑ the key names the hospital; no call asks for it

# every other call lands there too
POST /v1/patients
{
  "reference_number": "MRN-1001",
  …
}

02 Registration

The four steps, and what each commits

HFR takes a facility in four calls that share one tracking id. Only the first returns that id and only the last creates anything — and HFR offers no way to look the id up again, so the connector keeps it for you.

Step 1

Basic information

The facility’s core identity, built from HFR’s own master codes, sent with the manager’s HPR token. HFR answers with the tracking id every later step quotes.

Portal · Facilities → Register in HFR, step 1

Step 2

Additional information

Linked programme ids and general information about the facility. Nothing is registered yet.

Portal · step 2

Step 3

Detailed information

Specialities, beds and medical infrastructure, pharmacy, blood bank, imaging and diagnostic services.

Portal · step 3

Step 4

Submit

The only call that creates an entry. A registration HFR reviews before issuing an id comes back submitted rather than registered; poll it until an hfr_id appears.

Portal · step 4 — the HFR id appears

Master data comes from HFR, not from a guess. Ownership, facility types and sub-types, specialities, and LGD states, districts and sub-districts are read live from HFR by the portal’s registration form. Several filter by a code from the list before them, which is why the form asks in that order.

03 Failure modes

The ways HFR fails without saying so

HFR’s errors rarely name their cause. These are the ones that cost integrators days. All but the first are absorbed below the API; the first only you can prevent.

Duplicates

Registering a facility that is already there

A facility cannot delete its own duplicate. Only NHA can merge the two, through a support request that takes weeks, and until it does, half the network addresses the wrong id.

Prevented · the duplicate check before step 1

Linkage

Stopping at registration

A facility registered in HFR authenticates, appears in search and looks finished. Until its services are registered against the bridge, every linking call it makes is rejected, and no ABDM error names missing linkage as the cause.

Handled · activation asks you to declare linkage done any other way

Host

Calling the host the guides name

Community write-ups give facilitysbx.abdm.gov.in for the sandbox registry. From many providers it answers with an ICMP unreachable, which looks exactly like a firewall problem. Both sandbox registries are served from apihspsbx.abdm.gov.in — and production is not that name with sbx dropped.

Handled · registry base URL set per credential

Shape

Leaving out a field you did not need

Facility search rejects a body that omits any key, with a message that names ownershipCode whether or not that was the one missing. The page parameter is page; pageNo is ignored and returns page one forever.

Handled · the whole shape is sent every time

Masters

Asking for the other registry’s list

HFR’s system-of-medicine master type is MEDICINE. SYSTEM_OF_MEDICINE is HPR’s name, and HFR refuses it with a 422.

Handled · HFR and HPR masters served and cached separately

04A facility that is already registered

Many facilities are in HFR before their software is: a state programme registered them, or an earlier vendor did. Registering again creates exactly the duplicate above. Add it by its HFR id instead: the portal reads HFR’s record, and HFR proves control with an OTP to the contact it already holds.

The OTP always goes to the contact HFR holds, never to one supplied in the request. That is what stops a facility being claimed by whoever asks first — and it means a stale contact has to be corrected with HFR before the claim can succeed.

05One entry per physical site

HFR registration is per physical facility. A group with eight sites needs eight entries, and the connector models facilities the same way: each carries its own HFR id, its own HIP and HIU ids and its own bridge linkage, while one API credential reaches all of them.

Records are attributed to the site that produced them and consent is scoped to it. That is evidence an audit asks for, and a group registered as a single entry cannot produce it afterwards. Hospital groups will find the rest of the rollout in ABDM for hospitals; teams building the software should read how to integrate ABDM with an HMIS for the order of work.

06In production

Registry work is not finished at certification. Once NHA grants production access through the process in the milestone guide, each facility that will act as a HIP is registered in HFR with its production bridge linked, following NHA’s steps for linking a verified health facility. Take the production registry host from your NHA onboarding pack rather than deriving it from the sandbox name.

Linkage is what makes a facility reachable for record sharing and for Scan & Share, since both depend on ABDM routing to it. A note on naming: this connector groups HFR and HPR as M4. Some ABDM material uses “M4” for insurance claims over NHCX instead, which is a separate programme.

Register a test facility in the sandbox

Sandbox keys are issued on signup. Search HFR, run a deduplication check, and walk a registration through all four steps.

Create an account Talk to us

FAQ Common questions

Frequently asked questions

What is HFR in ABDM?
The Health Facility Registry is ABDM's directory of verified health facilities — hospitals, clinics, labs and pharmacies, public and private. A facility needs an HFR entry before it can share or request records on the network.
Does each hospital branch need its own HFR ID?
Yes. HFR registration is per physical facility, so a group with eight sites needs eight entries. Records are attributed to the site that produced them, and consent is scoped to it.
What is bridge linkage in HFR?
Bridge linkage registers a facility's HIP and HIU services against the software that will carry its traffic. Without it the facility exists in HFR and authenticates, but its linking calls are rejected with no error that names the cause.
What happens if a facility is registered twice in HFR?
The facility cannot delete the duplicate itself; only NHA can merge the two, through a support request that takes weeks. Run a deduplication search before registering.