Skip to main content

​
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:

​
Before you start

  • A client access token, sent as a Bearer token on every call. See Client login.
  • 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.
  • 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

​
Steps

1

Start face authentication

Call Face Auth Init. 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 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. 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)

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. If the OTP does not arrive, send txn_id to Mobile Resend OTP and use the txn_id it returns.
5

Create the ABHA

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 and Does ABHA Address Exist as in Create an ABHA with Aadhaar OTP.Send txn_id and abha_address to Create. The response carries profile.abha_number, profile.abha_address, eka.oid, token, refresh_token and skip_state.Eka also sends the 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.

​
State you must persist

​
When it fails

Which of these codes each call returns is not yet confirmed. The codes come from the errors page, 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.

​
Test it

The testing page 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.