> ## 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 face authentication

> Assisted ABHA creation where the patient authenticates with their face on a mobile device instead of an OTP.

## In short

* Face authentication on the patient's device replaces the Aadhaar OTP.
* Show the QR code from Face Auth Init, then poll Capture Face until `Verified`.
* Verify Face returns the identity, and Create uses the Aadhaar Create call.
* That create call is not yet confirmed for face authentication.

## When to use this

Use this for assisted ABHA creation with Aadhaar face authentication instead of an OTP. The patient scans a QR code you show and completes face authentication on a mobile device. The verified identity then creates a KYC-verified ABHA. 

Alternatives:

* The patient will use an Aadhaar OTP instead: [Create an ABHA with Aadhaar OTP](https://developer.eka.care/docs/hie-cm/workflows/create-abha-aadhaar-otp.md).
* 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).

## 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). You can send its HIP ID in the optional `X-Hip-Id` header and your own patient id 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).
* A screen that can show a QR code to the patient, and a mobile device on which the patient completes face authentication. 
* In hand: the patient's 12-digit Aadhaar number.

## Sequence

```mermaid theme={null}
sequenceDiagram
  participant App as Your app
  participant Eka
  participant Patient as Patient's device
  App->>Eka: POST /abdm/na/v1/face-auth/init
  App-->>Patient: Show the QR code from url
  Patient->>Patient: Scan and complete face authentication
  loop Until status is Verified
    App->>Eka: POST /abdm/na/v1/face-auth/capture
  end
  App->>Eka: POST /abdm/na/v1/face-auth/verify
  opt Mobile not linked with Aadhaar (not yet confirmed for face auth)
    App->>Eka: POST /abdm/na/v1/registration/aadhaar/mobile/verify
    opt OTP did not arrive
      App->>Eka: POST /abdm/na/v1/registration/aadhaar/mobile/resend
    end
  end
  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
```

## Steps

**1. Start face authentication**

Call [Face Auth Init](https://developer.eka.care/api-sdk/hie-cm/enrollment/face-auth/face-auth-init.md). It takes no request body. The response carries `txn_id` and `url`. Show `url` to the patient as a QR code to scan with their mobile device. 

Keep `txn_id`; every later call takes the `txn_id` from the most recent response.

**2. Poll until the face is verified**

Send `txn_id` to [Capture Face](https://developer.eka.care/api-sdk/hie-cm/enrollment/face-auth/face-auth-capture.md) repeatedly while the patient completes face authentication. The response carries `status`, `message` and `txn_id`. Keep polling while `status` is `Pending`. Stop when it is `Verified`. 

**3. Fetch the verified identity**

Send `txn_id` and `aadhaar` (the patient's Aadhaar number) to [Verify Face](https://developer.eka.care/api-sdk/hie-cm/enrollment/face-auth/face-auth-verify.md). The response carries a new `txn_id`, `skip_state`, `abha_profiles`, `profile` and `eka.oid`. `profile` holds the patient's name, date of birth, gender and address from Aadhaar.

Read `skip_state` and `abha_profiles`:

* `abha_create` with an empty `abha_profiles`: go to the next step.
* `abha_create` with a non-empty `abha_profiles`: the patient already has ABHA addresses. 
* `confirm_mobile_otp`: go to "Verify the mobile". 

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

> [!NOTE]
>
> This step is not yet confirmed for face authentication. flows/m1 draws a "Mobile linked with Aadhaar?" branch after Verify Face, with Mobile Verify OTP and Mobile Resend OTP, as in the Aadhaar OTP flow. Whether these calls accept the face-auth `txn_id` is not yet confirmed.

Send `txn_id` and the `otp` the patient receives to [Mobile Verify OTP](https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/mobile-verify.md). If the 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. 

**5. Create the ABHA**

> [!NOTE]
>
> The create call after face authentication is not yet confirmed. Verify Face returns the same `txn_id`, `skip_state`, `abha_profiles` and `eka` shape as the Aadhaar OTP Verify call. flows/m1 draws the same mobile check, then create, path for both. On that evidence this step uses the Aadhaar Create call.

The patient chooses an ABHA address. You can use [Suggest ABHA Address](https://developer.eka.care/api-sdk/hie-cm/commons/suggest-abha-address.md) and [Does ABHA Address Exist](https://developer.eka.care/api-sdk/hie-cm/commons/does-health-id-exist.md) as in [Create an ABHA with Aadhaar OTP](https://developer.eka.care/docs/hie-cm/workflows/create-abha-aadhaar-otp.md).

Send `txn_id` and `abha_address` to [Create](https://developer.eka.care/api-sdk/hie-cm/enrollment/aadhaar/create-abha.md). The response carries `profile.abha_number`, `profile.abha_address`, `eka.oid`, `token`, `refresh_token` and `skip_state`.

Eka also sends the [`abha.created`](https://developer.eka.care/docs/hie-cm/webhooks/abha-created) webhook with `abha_address`, `abha_number`, `oid`, `hip_id` and `partner_patient_id` in `data`. 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 returns | Every call in this workflow |
| `eka.oid` | Verify Face or Create; also `data.oid` on `abha.created` | Permanently, on the patient record | The `X-Pt-Id` header or `oid` query on every later call for this patient |
| `profile.abha_address` | Create; also `data.abha_address` on `abha.created` | Permanently, on the patient record | Care context linking, gateway session, login |
| `profile.abha_number` | Create; also `data.abha_number` on `abha.created` | Permanently, on the patient record | ABHA card, KYC, login by ABHA number |

## 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 the ABDM code. See [Error codes](https://developer.eka.care/docs/hie-cm/errors.md). 

| Situation | Code | Do |
| - | - | - |
| Patient never completes face authentication | Capture keeps returning `Pending` | Stop polling after your timeout and start again from Face Auth Init. |
| Aadhaar number does not match the face authenticated | Not documented | Ask the patient to check the number. |
| Expired or unknown transaction | `ABDM-1017`, `MIS-1026` | Start again from Face Auth Init. |
| Too many requests | `ABDM-1022` | Back off and retry. |
| ABHA address already taken | `ABDM-1101` | Ask for another address. |
| ABDM or a dependent service is down | `ABDM-1019`, `ABDM-1024`, `ABDM-1007` | 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: Face Auth Init, show `url`, poll Capture Face until `Verified`, Verify Face, Create. The response has `profile.abha_number` and `eka.oid`.
* [ ] `abha.created` arrives with the same `abha_address` and `oid`, and its signature verifies.
* [ ] Abandon face authentication: Capture Face stays `Pending` and your timeout restarts the flow.
* [ ] Verify Face with a different Aadhaar number from the one authenticated: record the code it returns in the failure table.


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