Abha Specification
Abha Specification
1 | Page
TABLE OF CONTENTS
(Ayushman Bharat Digital Mission) 1
Purpose 3
Introduction 3
Prerequisites for integration 4
1. Registration for ABHA (Health ID) 4
a. Registration via Aadhaar Number 4
b. Registration via Other Documents 6
2. Login with ABHA (Health ID) 8
2.1 Login with Aadhaar OTP 8
2.2 Login with Mobile OTP 8
3. Login to your ABHA using Mobile 9
4. Retrieve your account 10
Retrieve ABHA via Aadhaar OTP 10
Retrieve ABHA via Mobile OTP 11
5. User Profile 12
Get Profile 12
GET QR Code 13
EDIT Profile 13
a. Update E-mail 13
b. Update Mobile 15
6. Delete ABHA (Health ID) 18
7. Deactivate ABHA (Health ID) 20
8. Reactivate ABHA (Health ID) 21
9. Annexure 1 : API Summary 23
10. Annexure 2 : Error Codes and Description 25
2 | Page
Working with ABHA ( Health – ID) APIs
Purpose
This purpose of the document is to outline and demystify ABHA creation APIs and
associated flows for the integrator. This document has the details of APIs and sequence
diagrams for Milestone One/M-1 (Creation and Verification of ABHA Number).
Introduction
Ayushman Bharat Health Account (earlier known as Health ID) is used for the purposes
of uniquely identifying persons, authenticating them, and threading their health records
(only with the informed consent of the patient) across multiple systems and
stakeholders. An integrator can start The ABDM Sandbox is ready to be integrated with
Hospital and Lab software such as EMR, HIMS, LIMS, Telemedicine, among others
through the ABDM APIs. All the services on the sandbox are designed to work with the
Healthidsbx environment.
Implementer’s guide to get started with ABDM’s APIs can be found here :
https://sandbox.abdm.gov.in/docs/getting_started_with_apis.
The complete API documentation with request / response parameters can be found
here: https://sandbox.abdm.gov.in/docs/healthid
For any technical concerns regarding integration, kindly post query on the
https://devforum.abdm.gov.in/
For the complete API summary, please refer to ANNEXURE -1 at the end of the
document.
Error codes with descriptions have been provided in the ANNEXURE-2 in this
document.
3 | Page
Prerequisites for integration
API Security
You need Authorization Token and X-HIP-ID to consume APIs.
1. In case you want to consume the Health ID APIs and use creation on your own interface, use
authentication methods as OTP only.
2. In order to have access to HealthID APIs, your clientId must have hid role in gateway. So if you
want access to these APIs then please request it in your ABDM on-boarding request.
3. When calling APIs, please ensure that the Authorization header must have format as Bearer
{Token_Value}. Please note that prefix Bearer followed by space before token value.
4. Please use the latest version of APIs (currently latest V2) as older versions may get deprecated
soon.
5. Check the state and district codes from LGD directory click here
6. Additionally, please note, following enhanced security measures have been introduced in version 2
APIs
i. Sensitive data(Data like OTP, Aadhaar Number, Password, Username etc) have to be
encrypted.
ii. Data is encrypted by the public certificate. The certificate can be downloaded from the
/v2/auth/cert API under Authentication tag in the version 2.
iii. RSA Encryption to encrypt the data. Cipher Type - RSA/ECB/PKCS1Padding. online tool
to encrypt data click here
4 | Page
To enable beneficiary registration using Aadhaar Biometric, a client needs to have a
Aadhaar Registered Device (RD Device) that allows capture and processing of
Biometrics of the beneficiary. This RD Service returns an encrypted PID block
containing signed biometrics (using device private key within the registered devices
secure zone) back to the calling application.
5 | Page
b. Registration via Other Documents
Currently we support Driving License (DL) & PAN for ABHA number generation,
apart from Aadhaar . ABDM plans to roll out other ID documents as well to
enable creation. The same will be communicated and updated in the
documentation as necessary. However, the integration flow will remain as the
DL/PAN flow.
● Name
● Date of birth
● Gender
6 | Page
The submitted demographic details are then matched against the DL/PAN
database. ABHA system also checks the details against the existing ABHA
(Health ID) or Enrolment number database to prevent duplication.
Users are requested to upload scanned front and back images of their DL/PAN.
Post submission, an enrollment number is generated. Health care
workers/Facility Managers are expected to ensure that the submitted DL/PAN is
of the end user requesting creation of ABHA. They can ensure the same by
matching the picture in the uploaded document with the requesting person.
Please note, ABHA creation via Aadhaar is a one step process wherein, ABHA is
created instantaneously. However, in case of other ID documents, an enrollment
number is generated first which can only be converted to ABHA once a manual
verification of identity is complete.
ABHA (Health ID) created through Self mode via using Driving license/PAN, an
Enrolment number has been issued which can be verified at any facility centers.
The sequence of APIs used via other documents’ method is shown in the
diagram below.
7 | Page
Note: ABDM will soon roll out features that will support ABHA (Health ID) creation with
other ID documents such as PAN card, Driving License, etc. in assisted mode at
participating health facilities.
When an ABHA (health ID) is created, the API confirms if the ABHA (Health ID) is valid
and also the authentication methods supported for the ABHA ( HealthID). The user can
choose an appropriate option to authenticate/Login the user.
To begin the process, the Authentication token public certificate API is called. This
certificate is also used to encrypt the data. Then the API checks if ABHA (Health ID) is
reserved/used which includes permanently deleted HIDs. Before using the method of
login, ensure *Initiate authentication* API has been called already for the given ABHA.
The following Authentication (Login) methods are supported. Client has to choose one
login method from below given methods.
An OTP is triggered with the Aadhaar linked mobile number of the patient. The patient
must provide the OTP to the user to complete the authentication
An OTP is sent to the patient’s mobile number that is linked with the Health ID. The
patient must share the OTP with the user for verification. A token has been returned
and can be used for Profile APIs purpose.
The sequence of APIs used via this method is shown in the diagram below.
8 | Page
3. Login to your ABHA using Mobile
Users will now be able to login to their ABHA using their Mobile Number. In case
multiple ABHA numbers are linked to a Mobile Number, users will be able to
choose the account they want to login to.
An OTP is sent to the patient’s mobile number that is linked with the ABHA. The
patient must share the OTP with the user for verification. A token has been
returned and can be used for Profile APIs purpose.
9 | Page
4. Retrieve your account
If a user has forgotten his/her ABHA (Health ID), it can be retrieved via the following
two methods
10 | Page
Retrieve ABHA via Mobile OTP
To retrieve ABHA (Health ID), an OTP is sent on mobile number along with the user's
demographic detail .User's health ID is retrieved from the ABDM server.
The sequence of APIs used via this method is shown in the diagram below.
11 | Page
5. User Profile
Get Profile
12 | Page
Response :
GET QR Code
EDIT Profile
a. Update E-mail
OTP will be sent to the provided e-mail address. OTP will be valid for 10 minute
only. To Update or Changes the existing e-mail Address (Verified/Unverified
email). Send the New Email Address required in the request.
13 | Page
EndPoint: /v2/account/email/verification/send/otp: Authentication token
has been used in header. E-mail address is sent in the request body. Transaction
ID is returned in the response.
Request:
Response :
Transaction ID is returned.
Endpoint /v2/account/email/verification/verify/otp:
Transaction ID & encrypted OTP is passed in the requested body. An authentication
token is used in the header. OTP should be in the encrypted form. Status is returned in
the response body.
14 | Page
Response :
b. Update Mobile
Update Mobile via Aadhaar Otp
The sequence of APIs used via this method is shown in the diagram
below.
15 | Page
Update Mobile via Mobile Otp :
The sequence of APIs used via this method is shown in the diagram
below.
16 | Page
17 | Page
6. Delete ABHA (Health ID)
1. Your ABHA (Health ID) will be permanently deleted, along with all
your demographic details .
2. You will not be able to retrieve any information tagged to your
ABHA (Health ID) in future.
3. You will never be able to access ABDM applications or any health
records over the ABDM network with your deleted ABHA (Health
ID).
The sequence of APIs used via this method is shown in the diagram
below.
18 | Page
19 | Page
7. Deactivate ABHA (Health ID)
The sequence of APIs used via this method is shown in the diagram
below.
20 | Page
8. Reactivate ABHA (Health ID)
Users may Reactivate his/her ABHA (Health ID) via Aadhaar OTP or
Mobile OTP by using the below endpoints .
21 | Page
Endpoint: /v2/auth/reactivate/init
Endpoint: /v2/auth/reactivate
22 | Page
9. Annexure 1 : API Summary
The following table lists down all the rest APIs rolled out by the ABHA system for consumption
by the integrators. The same APIs can be used to develop system specific user flows by the
integrators.
Link : https://sandbox.abdm.gov.in/docs/healthid
Sequen
Type of API API Endpoint Description Request Response
ce
Generate Aadhaar OTP on Registered
1 v1/registration/aadhaar/generateOtp Aadhaar Trxn ID
mobile number
Verify Aadhaar OTP received on
2 v1/registration/aadhaar/verifyOTP OTP,Trxn ID Trxn ID
Registered mobile number
3 v1/registration/aadhaar/generateMobileOTP Generate Mobile OTP for verification. Mobile, Trxn ID Trxn ID
Verify Mobile OTP in an existing
Registration via 4 v1/registration/aadhaar/verifyMobileOTP OTP,Trxn ID Trxn ID
transaction.
Aadhaar
v1/registration/aadhaar/createHealthIdWithPreVe Create Health ID using pre-verified Health ID,
5 Trxn ID , Demo
rified Aadhaar & Mobile. Token
Check the Health ID in our system.This
API checks if HealthID is
6 v1/search/existsByHealthId Health ID Status
reserved/used which includes
permanently deleted HIDs.
1 /v1/registration/aadhaar/verifyBio Verify aadhaar via biometric Aadhaar, PID, Auth type Trxn ID
Registration via
Aadhaar biometric v1/registration/aadhaar/createHealthIdWithPreVe Create Health ID using pre-verified Health ID,
2 Trxn ID
rified Aadhaar & Mobile. Token
Generate Mobile OTP to start
1 v2/registration/mobile/generateOtp Mobile Trxn ID
registration transaction
Verify Mobile OTP sent as part of
2 v2/registration/mobile/verifyOtp OTP, Trxn ID Token
registration transaction.
Registration via
Create Health ID with verified mobile Health ID,
Mobile 3 v2/registration/mobile/createHidViaMobile Demo, Token
token token
Resend Mobile OTP in an existing
4 v2/registration/mobile/resendOtp transaction in case previous OTP is Trxn ID Status
not received.
1 v2/document/generate/mobile/otp Generate Mobile OTP Mobile No Mobile, Txn
2 v2/document/verify/mobile/otp Verify Mobile OTP Otp, Txn ID Token
Match the provided demographic
details against document and check
Registration via Document,Name, Verification
3 v2/document/validate for the already created HID or
Other documents DOB, Gender Status,token
Enrollment number against the
document
Create Health ID using ID documents
4 v2/document Token Health ID
like Driving Licence
23 | Page
Sequen
Type of API API Endpoint Description Request Response
ce
1 v1/auth/cert Authentication token public certificate. GET Auth Token
Check the Health ID in our system.This
API checks if HealthID is Account
2 v1/search/searchByHealthId Health ID
reserved/used which includes detail
Login Via permanently deleted HIDs.
Aadhaar/Mobile Initiate authentication process for given
3 v1/auth/init Auth Method, Health ID Trxn ID
OTP Health ID
Authentication with Aadhaar OTP
4 v1/auth/confirmWithAadhaarOtp OTP, Trxn ID Token
based auth transaction
Authentication with Mobile OTP based
6 v1/auth/confirmWithMobileOTP OTP, Trxn ID Token
auth transaction.
Api Accepts Aadhaar and then creates
1 /v2/forgot/healthId/aadhaar/generateOtp Aadhaar Trxn ID
OTP for linked Mobile number
Retrieve for 2 /v2/forgot/healthId/aadhaar Check the Health ID in our system. Trxn ID, OTP Health ID
forgotten ABHA Api Accepts Mobile Number and then
3 /v1/forgot/healthId/mobile/generateOtp Mobile Trxn
generates OTP for it
4 /v1/forgot/healthId/mobile Check the Health ID in our system. OTP, Trxn ID, Demo Health ID
User Profile
v1/account/profile Get account information Auth Token Account detail
Get User Profile 1
Get Quick Response code in PNG format
v1/account/qrCode Auth Token QR Code
Get QR code 1 for this account.
Generate OTP on new mobile need to
v2/account/change/mobile/new/generateOTP Mobile Trxn ID
1 update existing account mobile number
Verify Mobile OTP to complete new mobile
v2/account/change/mobile/new/verifyOTP OTP, Trxn ID Trxn ID
2 update verification.
Update Mobile via
Generate Aadhaar OTP on Registered
Aadhaar Otp v2/account/change/mobile/aadhaar/generateOTP Trxn ID New Trxn ID
3 mobile number to start mobile update
Change mobile number via
v2/account/change/mobile/update/authentication password/aadhaar/existing mobile for OTP, Trxn ID Status
4 Health ID.
Generate OTP on new mobile need to
v2/account/change/mobile/new/generateOTP Mobile Trxn ID
1 update existing account mobile number
Verify Mobile OTP to complete new mobile
v2/account/change/mobile/new/verifyOTP OTP, Trxn ID Trxn ID
2 update verification.
Generate Mobile OTP to start mobile
v2/account/change/mobile/old/generateOTP Trxn ID New Trxn ID
3 update.
Change mobile number via
Update Mobile via v2/account/change/mobile/update/authentication password/aadhaar/existing mobile for OTP, Trxn ID Status
Mobile Otp 4 Health ID.
Send the Email Verification Activation Link Auth Token, Auth
Update Email Via v2/account/email/verification/auth/initiate/send Trxn ID
1 to verify the E-mail Address Method,Email
Aadhaar Otp/Mobile
v2/account/email/verification/auth/verify Verfiy the user initiate the Activation Link Trxn ID, OTP,Auth Method Status
OTP 2
Generate Aadhaar OTP on Registered for
Delete HID using v2/account/aadhaar/generateOTP Aadhaar, Auth token Trxn ID
1 link account with aadhar number
Aadhaar/Mobile 2 v2/account/profile/delete Delete account Auth Token, OTP, Trxn ID Status
Delete HID using 1 v2/account/mobile/generateOTP Generate Mobile OTP to start mobile txn. Auth Token Trxn ID
Mobile 2 v2/account/profile/delete Delete account Auth Token, OTP, Trxn ID Status
Generate Aadhaar OTP on Registered for
v2/account/aadhaar/generateOTP Aadhaar, Auth token Trxn ID
1 link account with aadhar number
Deactivate HID Deactivate the account using mobile or Auth method, OTP, Trxn
v2/account/profile/deactivate Status
using Aadhaar 2 aadhaar otp. ID
1 v2/account/mobile/generateOTP Generate Mobile OTP to start mobile txn. Auth Token Trxn ID
Deactivate HID Deactivate the account using mobile or Auth method, OTP, Trxn
v2/account/profile/deactivate Status
using Mobile 2 aadhaar otp. ID
24 | Page
10. Annexure 2 : Error Codes and Description
Error Code Description
HIS-422 Unable to process the current request due to incorrect data entered.
HIS-1010 Must contain an uppercase, a lowercase, a number, a special character and at least 8
or more characters. It should not contain any sequences (like 123).
25 | Page
HIS-1013 The OTP that you have entered is incorrect. Please try again.
HIS-1015 A Health ID already exists with these details. Click here to login to your Health ID
HIS-1018 Currently, Health IDs can be made only in Chandigarh, Ladakh, Dadra and Nagar
Haveli and Daman and Diu, Puducherry, Andaman & Nicobar Islands and
Lakshadweep.
HIS-1020 The given Health Facility ID is already registered with Health ID number
#healthIdNumber.
HIS-1023 Please wait for 30 seconds before sending another OTP request.
HIS-1029 The provided Health ID number #healthIdNumber is already registered with Aadhaar.
HIS-1030 Name entered by you does not match with your Aadhaar data.
26 | Page
HIS-1031 Password not set for #healthIdNumber. Please use another login method and change
the password.
HIS-1033 The password that you have entered is incorrect. Please try again.
HIS-1035 Please enter a valid Health ID. It should contain 4 (min) to 32 (max) characters. For
instance- xxxx.1523
HIS-1037 Please provide at least one of the fields in the request parameter.
HIS-1039 You have exceeded the maximum limit of failed attempts. Please try to login using other
modes or try again in 12 hours.
HIS-1040 The selected file exceeds the maximum allowable size of 100kb. Only files with the
following extensions are allowed: png, jpeg, jpg.
HIS-1041 You have reached the maximum verify attempts. Exit your browser and try again.You
have reached the maximum verify attempts. Exit your browser and try again.
HIS-1046 The provided mobile number same as the existing mobile number of the Health ID:
#healthIdNumber. Please use another mobile number.
27 | Page
HIS-1047 Input OTP/PASSWORD must be encrypted form.
HIS-1049 Consent flag in your request body is not 'True'. Please collect consent from the user
and try again.
HIS-1052 The mobile user provided by you is already linked to 10 other Health IDs. Please
provide a different Mobile Number.
HIS-1053 Current password and new password are same. Please try with different new password.
HIS-1055 Current password and new password are same. Please try with different password.
HIS-1058 Please enter the valid Gender code. Male - M, Female - F, Other - O.
HIS-2001 Invalid Aadhaar number entered. Please enter a valid Aadhaar number.
28 | Page
HIS-2002 Unauthorized ASA channel.
HIS-2017 You have requested multiple OTPs in this transaction. Please try again in 30 minutes.
29 | Page
HIS-2019 BioType is invalid. Please use (FMR for 'Fingerprint Minutiae Record', FIR for
'Fingerprint Image Record', IIR for 'Iris Image Record', FID for 'Face Image
Data'.).
HIS-2023 \u201Ctxn\u201D value did not match with \u201Ctxn\u201D value used in Request
OTP API.
30 | Page
HIS-2036 Invalid Input.
HIS-2045 Current password and new password are same. Please try with different password.
HIS-3006 The details you've entered against the document is not matching. Please enter the
correct details.
31 | Page
HIS-4000 The details provided by you do not match against your Driving Licence details. Please
provide the correct details.
32 | Page