Skip to main content

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

​
Steps

1

Send the Aadhaar number

Send aadhaar_number to Generate OTP. 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. 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. 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. 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 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 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. 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. Read its response as in Complete the Aadhaar login, and see Milestone 1. 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. 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 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.

​
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 codes such as MIS-1013.

​
Test it

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