> ## Documentation Index
> Fetch the complete documentation index at: https://developer.eka.care/llms.txt
> Use this file to discover all available pages before exploring further.

# Register and onboard a facility

> Find the facility in the Health Facility Registry or register it, link it to the Eka Bridge, and onboard it to Eka as a HIP.

## In short

* Search HFR, register the facility if absent, link it to the Eka Bridge, then onboard it to Eka.
* The onboarding call returns the HIP ID your HMS uses on every later HIP call.
* It is a one-time setup per facility.

## When to use this

A facility needs to act as a Health Information Provider (HIP) through Eka. You take four steps:

* Search the Health Facility Registry (HFR) for it.
* Register it if it is not there.
* Link it to the Eka Bridge.
* Onboard it to Eka.

The last call returns the HIP ID your HMS uses on every later HIP call. This is a one-time setup per facility.

If the facility was registered on the [ABDM portal](https://nhpr.abdm.gov.in/nhpr/v4/login) and linked there under Software Linkage with the Eka Bridge ID, skip to the last step.

## Before you start

* A bearer token for the Eka API. See [Authorization](https://developer.eka.care/api-sdk/auth/getting-started.md).
* The headers your integration sends on ABDM Connect calls. The three HFR operations accept `X-Pt-Id`, `X-Partner-Pt-Id` and `X-Hip-Id`. 
* At least one professional at the facility with an HPR ID, from [Create an HPR ID with Aadhaar OTP](https://developer.eka.care/docs/hie-cm/workflows/create-hpr-id.md). Registering a facility needs the authorizing doctor's OID.
* The facility's HFR ID if it has one, and your own `clinic_id` for it.
* The facility's name, for the onboarding call.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  App->>Eka: GET /abdm/nhpr/v1/hfr/search/{hfrId}
  alt Facility not in HFR
    App->>Eka: POST /abdm/nhpr/v1/hfr/onboard
  end
  App->>Eka: POST /abdm/nhpr/v1/hfr/link
  App->>Eka: POST /abdm/v1/hip/onboard
```

## Steps

**1. Search for the facility**

Call [Search HFR](https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hfr/search-facility.md) with the HFR ID in the path as `hfrId`. If the facility exists, the response `data` carries `facilityId`, `facilityName`, `facilityStatus`, `facilityType`, `ownership` and the address fields. Check `facilityName` and the address with the admin before you go on. If it exists, skip to Link. 

**2. Register the facility if it is absent**

Call [Onboard HFR](https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hfr/onboard-facility.md). The spec gives this body only `clinic_id` and `hfr_id`. The response `data` carries `facility_id`. Keep it as the facility's HFR ID. 

**3. Link the facility to the Eka Bridge**

Send `hfr_id` and `clinic_id` to [Link HFR](https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hfr/link-facility.md). Use `facilityId` from Search, or `facility_id` from Onboard HFR, as `hfr_id`. The response `data` echoes `hfr_id` and `clinic_id`; check `success` is true. This connects the facility to the Eka Bridge so it can exchange health data. 

**4. Onboard the facility to Eka**

Send `hip_id` and `name`, both required, and your `clinic_id` to [Onboard facility](https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/onboarding.md). The response carries `hip_id`, `hip_code`, `hip_name` and `scan_share_url`. Save them on the facility record. 

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| HFR ID (`facilityId` or `facility_id`) | Search HFR, or Onboard HFR | Permanently, on the facility record | Link HFR as `hfr_id`, and the HIP ID for onboarding |
| `clinic_id` | Your own system | Permanently, on the facility record | Link HFR and Onboard facility |
| `hip_id` | Onboard facility | Permanently, on the facility record | The `X-Hip-Id` header on later HIP calls |
| `hip_code` | Onboard facility | Permanently, on the facility record | |
| `scan_share_url` | Onboard facility | Permanently, on the facility record | The facility's Scan and Share link |

## When it fails

> [!WARNING]
>
> Which of these codes each call returns is not yet confirmed. The codes come from the [errors page](https://developer.eka.care/docs/hie-cm/errors.md), matched by meaning. Log the code you actually receive.

Errors come back as `4XX` or `5XX` with a body carrying `code`, `error` and `source_error` (`code`, `message`). Read `source_error.code` and look it up on the [errors page](https://developer.eka.care/docs/hie-cm/errors.md).

| Situation | Code | Do |
| - | - | - |
| Malformed body, such as a missing `hip_id` or `name` on Onboard facility | `ABDM-1006` | Fix the request; do not retry unchanged |
| Facility not in HFR | | Register it with Onboard HFR |
| Facility already registered | `ABDM-1053` | Search for it and continue from Link |
| Invalid HIP ID on Onboard facility | `ABDM-1035` (the [errors page](https://developer.eka.care/docs/hie-cm/errors.md) lists two meanings: Invalid HIP ID on a 500, and OTP does not match on a 400; tell them apart by HTTP status and `source_error.message`) | Check the `hip_id` you sent |
| Facility not yet approved | | Wait for approval, then retry from Link |
| ABDM registry unavailable | `ABDM-1019` or `ABDM-1024` | Retry later |

## Test it

The [testing page](https://developer.eka.care/docs/hie-cm/testing.md) has the sandbox base URL, credentials and the happy path for every journey.

Run against the sandbox base URL `https://api.dev.eka.care`. 

* [ ] Existing facility: Search HFR returns it, Link HFR returns `success` true, Onboard facility returns `hip_id` and `scan_share_url`
* [ ] New facility: Search HFR finds nothing, Onboard HFR returns `facility_id`, then Link and Onboard facility
* [ ] Onboard facility without `name`: the call fails and your app shows the error
* [ ] Run Onboard facility twice for the same facility 


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.