> ## 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.

# Create an HPR ID with Aadhaar OTP

> Verify a healthcare professional's Aadhaar and linked mobile, reuse their HPR ID if one exists, or create a new one from a suggested handle.

## In short

* Verify the professional's Aadhaar with an OTP, then check the Aadhaar-linked mobile.
* If Get HPR Info finds an existing HPR ID, save it and stop.
* Otherwise the professional picks a handle and you call Create HPR.
* Create takes `txnId` and `hprId` in camel case.

## When to use this

A doctor, nurse or other healthcare professional at the facility needs a Healthcare Professional Registry (HPR) ID. You want them to get it without leaving your HMS. The flow:

1. Verifies their Aadhaar with an OTP.
2. Confirms the mobile they give is the one linked to Aadhaar.
3. Returns the HPR ID they already have, or creates a new one.

A professional may already have an HPR ID and want to sign in with their mobile. For them, use [Log in to HPR with a mobile OTP](https://developer.eka.care/docs/hie-cm/workflows/hpr-mobile-login.md). You can also create HPR IDs by hand on the [ABDM portal](https://nhpr.abdm.gov.in/nhpr/v4/login).

## 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. Each operation in this workflow accepts `X-Pt-Id`, `X-Partner-Pt-Id` and `X-Hip-Id`. 
* The professional's Aadhaar number, the mobile linked to it, and their consent to use Aadhaar, recorded on your side.
* The professional's category and sub-category, email, pincode and a password, which Create needs. 

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant Phone as Professional's phone
  App->>Eka: POST /abdm/nhpr/v1/hpr/aadhaar/init
  Eka-->>Phone: OTP to the Aadhaar-linked mobile
  App->>Eka: POST /abdm/nhpr/v1/hpr/aadhaar/verify
  App->>Eka: POST /abdm/nhpr/v1/hpr/aadhaar/demo/verify
  App->>Eka: POST /abdm/nhpr/v1/hpr/aadhaar/check/exist
  alt No HPR ID yet
    App->>Eka: POST /abdm/nhpr/v1/hpr/aadhaar/suggest
    App->>Eka: POST /abdm/nhpr/v1/hpr/aadhaar/create
  end
```

## Steps

**1. Send the Aadhaar OTP**

Send `aadhaar` to [Get Aadhaar OTP](https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hpr/get-aadhar-otp.md). The response `data` carries `txn_id`, `mobile_num` and `hint`. Keep `txn_id`; every later call in this workflow needs it. The professional receives an OTP on the mobile linked to their Aadhaar.

**2. Verify the Aadhaar OTP**

Send `txn_id` and the `otp` the professional reads out to [Verify Aadhaar OTP](https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hpr/verify-aadhar-otp.md). The response `data` carries `txn_id`. Use the `txn_id` from this response in the next call. 

**3. Verify the linked mobile**

Send `txn_id` and the `mobile_num` the professional gives to [Verify Mobile](https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hpr/verify-mobile.md). Read `verified` in the response `data`. If `verified` is false, stop and show `reason`; the mobile does not match Aadhaar. If it is true, keep `txnId`. The response can also carry `hpr.hprId` and `suggested_hpr_ids`. 

**4. Check for an existing HPR ID**

Send `txn_id` and `mobile_num` to [Get HPR Info](https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hpr/check-hpr-exist.md). The response `data` carries the professional's profile (`first_name`, `last_name`, `category_id`, `pincode` and others), `hpr_id`, `hpr_id_number`, `new`, `token` and `txn_id`. If an HPR ID already exists, save `hpr_id` and `hpr_id_number` on the staff record and stop; do not create a second one. Otherwise continue to Suggest. 

**5. Get suggested HPR IDs**

Send `txn_id` to [Suggest IDs](https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hpr/suggest-ids.md). The response `data` is a list of suggested HPR ID handles. Show them to the professional and let them pick one, or type their own. 

**6. Create the HPR ID**

Send `txnId`, the chosen `hprId`, and the professional's details to [Create HPR](https://developer.eka.care/api-sdk/hie-cm/nhpr-abdm/hpr/create-hpr.md). Note the field names: this body uses `txnId` and `hprId` in camel case, where earlier calls use `txn_id`. Prefill `first_name`, `middle_name`, `last_name` and `pincode` from the Get HPR Info response. The response `data` carries `hprId` and `hpr_id_number`. Save both on the staff record.

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `txn_id` | Get Aadhaar OTP, then Verify Aadhaar OTP | Until Create returns | Every call in this workflow; sent as `txnId` to Create |
| `mobile_num` | The professional, checked by Verify Mobile | Until Get HPR Info returns | Verify Mobile and Get HPR Info |
| Profile fields (`first_name`, `last_name`, `pincode`) | Get HPR Info | Until Create returns | Prefilling the Create body |
| `hprId` or `hpr_id` | Create, or Get HPR Info for an existing ID | Permanently, on the staff record | Registering the facility, and identifying the professional in later ABDM calls |
| `hpr_id_number` | Create, or Get HPR Info for an existing ID | Permanently, on the staff record | Display and reconciliation with the HPR registry |
| `token` | Get HPR Info | | |

## 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` for the upstream 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 `aadhaar` | `ABDM-1006` | Fix the request; do not retry unchanged |
| Wrong OTP | `MIS-1013` | Let the professional enter it again |
| Too many OTP requests or attempts | `ABDM-1100` | Wait 30 minutes, then restart from Get Aadhaar OTP; show the professional the lockout |
| Transaction expired or unknown | `ABDM-1017` or `MIS-1026` | Restart from Get Aadhaar OTP |
| Mobile does not match Aadhaar | Verify Mobile returns `verified` false with `error_code` and `reason` | Show `reason`; ask for the Aadhaar-linked mobile |
| HPR ID handle already taken | | Offer another suggested handle |
| 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`. 

* [ ] Happy path for a new professional: Get Aadhaar OTP, Verify Aadhaar OTP, then Verify Mobile with `verified` true. Get HPR Info shows no existing ID, then Suggest IDs, then Create returns `hprId` and `hpr_id_number`
* [ ] Second run with the same Aadhaar: Get HPR Info returns the existing `hpr_id`, and your app stops without calling Create
* [ ] Wrong OTP once, then the correct OTP
* [ ] A mobile that is not linked to the Aadhaar: Verify Mobile returns `verified` false and your app shows `reason`
* [ ] Create with a handle that is already taken


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