> ## 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 ABHA with Aadhaar OTP

> Verify the patient's Aadhaar with an OTP and create a KYC-verified ABHA number and ABHA address.

## In short

* This workflow gives a KYC-verified ABHA number and ABHA address.
* Send the Aadhaar number, verify the OTP, choose an address, then call Create.
* Each call takes the latest `txn_id`.
* A patient who already has an ABHA on this Aadhaar logs in with Auto Login instead.

## When to use this

The patient has an Aadhaar number and can receive an OTP on the mobile linked to it. This workflow produces a KYC-verified 14-digit ABHA number and an ABHA address such as `shyam@abdm`. Aadhaar is the KYC.

Alternatives:

* The patient will not use Aadhaar: [Create an ABHA address with mobile OTP](https://developer.eka.care/docs/hie-cm/workflows/create-abha-mobile-otp.md). That address is not KYC-verified.
* Assisted creation where the patient authenticates with their face on a mobile device instead of an OTP: [Create an ABHA with face authentication](https://developer.eka.care/docs/hie-cm/workflows/create-abha-face-auth.md).
* The patient already knows their ABHA address: [Log in to an existing ABHA](https://developer.eka.care/docs/hie-cm/workflows/login-abha.md).

If the patient already has an ABHA on this Aadhaar, this workflow finds it at the verify step. It then logs them in instead of creating a duplicate.

## Before you start

* A client access token, sent as a Bearer token on every call. See [Client login](https://developer.eka.care/api-sdk/auth/client-login.md).
* Your facility onboarded as a Health Information Provider (HIP), with its HIP ID. You can send it in the optional `X-Hip-Id` header.
* Your own patient id for this person. You can send it in the optional `X-Partner-Pt-Id` header. 
* A webhook endpoint registered with Eka, so you receive `abha.created`. See [Register a webhook](https://developer.eka.care/api-sdk/webhooks/register-webhook.md).
* In hand:
  * the patient's 12-digit Aadhaar number
  * the 10-digit mobile number they want on the ABHA
  * their consent to use Aadhaar, recorded on your side

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant Patient as Patient's phone
  App->>Eka: POST /abdm/na/v1/registration/aadhaar/init
  Eka-->>Patient: OTP to the Aadhaar-linked mobile
  opt OTP did not arrive
    App->>Eka: POST /abdm/na/v1/registration/aadhaar/resend
  end
  App->>Eka: POST /abdm/na/v1/registration/aadhaar/verify
  alt skip_state is confirm_mobile_otp
    Eka-->>Patient: OTP to the mobile you sent
    opt OTP did not arrive
      App->>Eka: POST /abdm/na/v1/registration/aadhaar/mobile/resend
    end
    App->>Eka: POST /abdm/na/v1/registration/aadhaar/mobile/verify
  end
  alt abha_profiles is non-empty, patient picks an existing address
    App->>Eka: POST /abdm/na/v1/registration/aadhaar/auto-login
  else patient creates a new address
    App->>Eka: GET /abdm/na/v1/registration/suggest
    App->>Eka: POST /abdm/na/v1/registration/phr/check
    App->>Eka: POST /abdm/na/v1/registration/aadhaar/create-phr
    Eka-->>App: webhook abha.created
  end
```

## Steps

**1. Send the Aadhaar number**

Send `aadhaar_number` to [Generate OTP](https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/initiate-registration.md). ABDM sends an OTP to the mobile linked to that Aadhaar. The response carries `txn_id` and a `hint` with the masked mobile number, for example `OTP sent successfully to your mobile number ******90973`. Show the hint to the patient so they know which phone to check.

Keep `txn_id`. Every later call in this workflow takes the `txn_id` from the most recent response.

If the OTP does not arrive, send `txn_id` to [Resend OTP](https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/aadhaar-resend-otp.md). It returns a `txn_id`; use that one from now on. 

**2. Verify the Aadhaar OTP**

Send `txn_id`, the `otp` the patient reads out, and `mobile` to [Verify OTP](https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/verify-otp.md). All three are required. `mobile` is the number the ABHA will be linked to. It can differ from the mobile linked to the Aadhaar.

The response carries a new `txn_id`, `skip_state`, `abha_profiles`, `profile` and `eka.oid`. Read `skip_state` and `abha_profiles` to decide the next call:

* `skip_state` is `confirm_mobile_otp`: the `mobile` you sent is not the one linked to the Aadhaar. Go to the next step to verify it.
* `skip_state` is `abha_create` and `abha_profiles` is empty: the patient has no ABHA address on this Aadhaar. Skip to "Choose an ABHA address".
* `skip_state` is `abha_create` and `abha_profiles` is non-empty: the patient already has one or more ABHA addresses. Show each `abha_address` and `name` from `abha_profiles`. If the patient picks one, go to "Log in to the existing address". If they want a new one, go to "Choose an ABHA address".
* `skip_state` is `abha_select`: the patient has several ABHA addresses and must choose one to log in. 
* `skip_state` is `abha_end`: the flow is complete; no further call is needed. 

**3. Verify the new mobile (only if skip\_state is confirm\_mobile\_otp)**

An OTP goes to the `mobile` you sent in the previous step. Send `txn_id` and that `otp` to [Mobile Verify OTP](https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/mobile-verify.md). The response has the same shape as Verify OTP. Read `skip_state` and `abha_profiles` again and branch exactly as in the previous step.

If this OTP does not arrive, send `txn_id` to [Mobile Resend OTP](https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/mobile-resend-otp.md) and use the `txn_id` it returns.

**4. Choose an ABHA address**

The patient chooses the ABHA address to create. Two helpers make this reliable.

Call [Suggest ABHA Address](https://developer.eka.care/api-sdk/hie-cm/commons/suggest-abha-address.md) with `transactionId` set to your current `txn_id`. You can also pass `fn`, `mn`, `ln` and `dob` (format `YYYY-MM-DD`). The response's `suggestions` lists available addresses.

Before you submit, send the chosen `abha_address` to [Does ABHA Address Exist](https://developer.eka.care/api-sdk/hie-cm/commons/does-health-id-exist.md). If `exists` is `true`, ask the patient for another one.

**5. Log in to the existing address (only if the patient picked one)**

Send `txn_id` and the chosen `abha_address` from `abha_profiles` to [Auto Login](https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/auto-login.md). Read its response as in [Complete the Aadhaar login](https://developer.eka.care/docs/hie-cm/workflows/login-abha.md#complete-the-aadhaar-login), and see [Milestone 1](https://developer.eka.care/docs/hie-cm/flows/m1). The patient is logged in. Stop here; do not call Create.

**6. Create the ABHA**

Send `txn_id` and the chosen `abha_address` to [Create](https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/create-abha.md). Both are required. The response carries:

* `profile.abha_number`: the 14-digit ABHA number, for example `12-3456-7856-8912`.
* `profile.abha_address`: the patient's ABHA address.
* `eka.oid`: Eka's id for this patient. Later calls take it in the `X-Pt-Id` header or the `oid` query parameter.
* `token` and `refresh_token`: the ABHA tokens ABDM issues. 
* `skip_state`. 

Eka also sends the [`abha.created`](https://developer.eka.care/docs/hie-cm/webhooks/abha-created) webhook to your server. Its `data` carries `abha_address`, `abha_number`, `oid`, `hip_id` and `partner_patient_id`. Use the webhook, not only the API response, to provision the patient in your database. Acknowledge it and verify its signature as described in [Webhooks](https://developer.eka.care/docs/hie-cm/webhooks#delivery-signature-and-acknowledgement). 

## State you must persist

| Field | From | Keep | For |
| - | - | - | - |
| `txn_id` | The latest response in this workflow | Until Create or Auto Login returns | Every call in this workflow |
| `eka.oid` | Verify, Mobile Verify, Create or Auto Login; also `data.oid` on `abha.created` | Permanently, on the patient record | The `X-Pt-Id` header or `oid` query on every later ABDM Connect call for this patient |
| `profile.abha_address` | Create or Auto Login; also `data.abha_address` on `abha.created` | Permanently, on the patient record | Care context linking, gateway session, login |
| `profile.abha_number` | Create or Auto Login; also `data.abha_number` on `abha.created` | Permanently, on the patient record | Printing the ABHA card, KYC, login by ABHA number |
| `transaction_id` | `abha.created` webhook | Until processed | Ignoring a repeated delivery of the same event |

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

Error responses carry `code`, `error` and `source_error`. `source_error.code` holds codes such as `MIS-1013`. 

| Situation | Code | Do |
| - | - | - |
| Wrong OTP | `MIS-1013` | Ask the patient to re-enter the OTP. |
| Too many OTP requests or wrong attempts | `ABDM-1100` | Tell the patient to try again in 30 minutes. Start again from Generate OTP. |
| Patient blocked | `ABDM-1027` | Tell the patient to try again after 24 hours. |
| Too many requests | `ABDM-1022` | Back off and retry. |
| Expired or unknown transaction | `ABDM-1017`, `MIS-1026` | Start again from Generate OTP. |
| Aadhaar number not found | `ABDM-1112` | Ask the patient to check the number. |
| Malformed request, for example a missing `mobile` on Verify | `ABDM-1006`, `ABDM-1010` | Fix the request body against the reference page. |
| ABHA address already taken | `ABDM-1101` | Ask for another address. Call Does ABHA Address Exist before Create to avoid this. |
| Mobile verification still pending | `ABDM-1102` | Complete the Mobile Verify OTP step before Create. |
| Mobile number already claimed by another account | `EKA-1002` | Not documented yet. |
| ABDM or a dependent service is down or slow | `ABDM-1019`, `ABDM-1024`, `ABDM-1007`, `ABDM-1004` | Retry later. |
| `abha.created` never arrives | none | Use the Create response to proceed. |

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

* [ ] Happy path: Generate OTP, Verify OTP with `mobile` set to the Aadhaar-linked number, Suggest, Does ABHA Address Exist returns `exists: false`, Create. The response has `profile.abha_number` and `eka.oid`.
* [ ] `abha.created` arrives with the same `abha_address` and `oid`, and its signature verifies.
* [ ] Wrong OTP once, then the correct OTP: `MIS-1013`, then success. Record the code you receive; the expected code is not confirmed.
* [ ] Verify OTP with a `mobile` that is not the Aadhaar-linked one: `skip_state` is `confirm_mobile_otp`, then Mobile Verify OTP succeeds.
* [ ] Resend on both OTPs: each returns a `txn_id` that the next call accepts.
* [ ] Second run with the same Aadhaar: Verify OTP returns `abha_create` with a non-empty `abha_profiles`; Auto Login succeeds.
* [ ] Create with an address that Does ABHA Address Exist reports as taken: `ABDM-1101`. Record the code you receive; the expected code is not confirmed.


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