Skip to main content

Create ABHA - verify Aadhaar OTP

Verifies the Aadhaar OTP and creates the ABHA number, or returns the existing ABHA if one is already linked to the Aadhaar.

POST/abha/api/v3/enrollment/enrol/byAadhaar

The response contains the ABHA profile, tokens.token (user X-token) and a refresh token. mobile is the number to link with the ABHA. If it is not the Aadhaar-linked mobile, verify it next with After ABHA creation - send OTP to verify mobile (optional).

Endpoint: POST /abha/api/v3/enrollment/enrol/byAadhaar

Flow: Create ABHA - Aadhaar OTP - step 2 of 8

  • Previous: Send Aadhaar OTP for ABHA enrolment
  • Next: After ABHA creation - send OTP to verify mobile (optional)

Headers (plus Authorization: Bearer <gateway token>):

Header Required Description
TIMESTAMP yes Current UTC timestamp in ISO-8601 format.
REQUEST-ID yes Unique UUID for every request.
Benefit-Name no Applicable for user who is enrolling via Benefit Program.

Request body for this use case:

Field Value / Type Required Description
authData object yes Authentication payload for this use case.
authData.authMethods ["OTP"] yes Authentication method used in this step.
authData.otp object yes OTP authentication block.
authData.otp.txnId string yes Transaction ID returned by the previous step of this flow.
authData.otp.otpValue string yes OTP received by the user, RSA-encrypted.
authData.otp.mobile string no Mobile number to be linked with the ABHA (plain, 10 digits).
consent object yes Consent captured from the user for ABHA enrolment.
consent.code string yes Consent code. Use ABHA-enrollment.
consent.version string yes Consent version. Use 1.4.

Responses

200

Success: Create ABHA by verifying OTP - Positive flow

messagestring
tokensobject
tokens.tokenstring
tokens.expiresIninteger
tokens.refreshTokenstring
tokens.refreshExpiresIninteger
ABHAProfileobject
ABHAProfile.firstNamestring
ABHAProfile.middleNamestring
ABHAProfile.lastNamestring
ABHAProfile.dobstring
ABHAProfile.genderstring
ABHAProfile.mobilestring
ABHAProfile.phrAddressstring[]
ABHAProfile.districtCodestring
ABHAProfile.stateCodestring
ABHAProfile.abhaTypestring
ABHAProfile.stateNamestring
ABHAProfile.districtNamestring
ABHAProfile.ABHANumberstring
ABHAProfile.abhaStatusstring
isNewboolean
400

Bad Request (request validation failed): Create ABHA by verifying OTP-Invalid Transaction Id; Create ABHA by verifying OTP-Invalid authMethod; Create ABHA by verifying OTP-Invalid Mobile Number

Error codes for this module

txnIdstring
timestampstring
401

Unauthorized (invalid / expired gateway token, X-token or benefit access): Invalid Benefit Name (generic)

Everything returns 401

messagestring
timestampstring
422

Unprocessable Entity (business rule or UIDAI failure): Create ABHA by verifying OTP- Invalid OTP value

Error codes for this module

errorobject
error.codestring
error.messagestring
500

Internal Server Error.

Error codes for this module