ABDM API — Patient

All patient endpoints are POST and authenticated (Authorization: Bearer <idToken>).

/create_patient — POST (auth)

Creates a non-ABHA patient (written to both MySQL and the GCP FHIR store).

Request fields — patient object

Example request

{
  "patient": {
    "prefix": "Mr",
    "firstName": "Umesh",
    "middleName": "",
    "lastName": "Bilagi",
    "gender": "Male",
    "dob": "1989-04-26",
    "district": "Dharwad",
    "state": "KARNATAKA",
    "mobile": "9233235620",
    "address": "Hno11 , near pulley school",
    "panNumber": "APYVB3402Q",
    "aadharNumber": "514782451234",
    "email": "rameshH007@gmail.com",
    "alternatePhoneNumber": "0836223456"
  }
}

Example response

{
  "patient": {
    "id": 231,
    "prefix": "Mr",
    "firstName": "Umesh",
    "middleName": "",
    "lastName": "Bilagi",
    "gender": "Male",
    "dob": "1989-04-26T00:00:00.000Z",
    "orgId": 1,
    "gcpFhirId": "b6165fd2-b76a-48e3-81ad-202b3919d668",
    "abhaAddress": "",
    "abhaNumber": "",
    "district": "Dharwad",
    "state": "KARNATAKA",
    "mobile": "9233235620",
    "address": "Hno11 , near pulley school",
    "panNumber": "APYVB3402Q",
    "aadharNumber": "514782451234",
    "email": "rameshH007@gmail.com",
    "alternatePhoneNumber": "0836223456",
    "pincode": 580030
  }
}

Error codes

Shared codes only (no route-specific extras).

Note: ABHA patients must be created via /patient_register_abha_otp_init + /patient_register_abha_otp_confirm. Passing abhaAddress or abhaNumber here returns 400 VALIDATION_ERROR with message "The direct input of Abha Address or Abha number is not possible."

/patient_by_id — POST (auth)

Fetches a single patient by Nice HMS (MySQL) id.

Request fields

Example request

{
  "patientId": 236
}

Example response

Same PatientRes shape as /create_patient (a patient object).

Error codes

• PATIENT_NOT_FOUND (404) — no patient matches this id for your organization.
• shared codes

/patient_by_abhaAddress — POST (auth)

Fetches a single patient by ABHA address. The patient must already be registered in Nice HMS under your organization using their ABHA address (via Aadhar/mobile OTP, ABHA card QR, or the reception-generated HFR QR code).

Request fields

Example request

{
  "abhaAddress": "savitribilagi@sbx"
}

Example response

Same PatientRes shape as /create_patient.

Error codes

• PATIENT_NOT_FOUND (404)
• shared codes

/patient_register_abha_otp_init — POST (auth)

Step 1 of ABHA registration: search the ABHA address and request an OTP. Returns a transactionId used in step 2.

Request fields

authMode selects which mobile number the OTP goes to:

• "MOBILE_OTP" — the mobile registered against the ABHA in ABDM.
• "AADHAAR_OTP" — the mobile linked to the patient's Aadhaar. Use this when the ABHA has no ABDM-verified mobile; it also works for patients who do.
• "DONT_KNOW" — no OTP is sent. The response lists the modes the ABHA supports so the caller can ask the patient to choose.

The mode you pass here must also be passed to /patient_register_abha_otp_confirm, otherwise the verification is attempted on the wrong channel.

authMode is required here. If you omit it, the request fails with 400 VALIDATION_ERROR (details[].field = "authMode"). There is no mobile field — the number the OTP goes to is chosen entirely by authMode.

The response's auth.modes lists every mode the ABHA actually supports, and you can read it without sending an OTP by passing "DONT_KNOW". If you pass a mode that is not in auth.modes, or one that is blocked for this ABHA, the call fails with 502 ABDM_GATEWAY_ERROR and a message naming the available modes — choose one of those and retry.

DONT_KNOW is init-only: /patient_register_abha_otp_confirm accepts only MOBILE_OTP or AADHAAR_OTP.

Registering an ABHA with no mobile number

If the patient's ABHA has no mobile registered in ABDM, MOBILE_OTP will not work (there is no number to send to). Use either:

• AADHAAR_OTP — the OTP goes to the mobile linked to the patient's Aadhaar; or
• DONT_KNOW first, to read auth.modes and pick a mode the ABHA supports.

Passing MOBILE_OTP for an ABHA with no ABDM mobile returns 502 ABDM_GATEWAY_ERROR naming the modes that are available.

Example request

{
  "abhaAddress": "abcd@abdm",
  "authMode": "MOBILE_OTP"
}

Example response

OTP sent:

{
  "auth": {
    "transactionId": "f455d2f9-18f1-4c6e-bfd0-df5ff2449f97",
    "modes": ["MOBILE_OTP", "AADHAAR_OTP"]
  }
}

authMode: "DONT_KNOW" — no transactionId, because no OTP was sent:

{
  "auth": {
    "modes": ["MOBILE_OTP", "AADHAAR_OTP"]
  }
}

Pass auth.transactionId to /patient_register_abha_otp_confirm.

Error codes

• VALIDATION_ERROR (400)
• ABDM_GATEWAY_ERROR (502) — the auth mode is not available or is blocked for this ABHA address; or ABDM rejected the request. error.message carries ABDM's own reason.
• shared codes

/patient_register_abha_otp_confirm — POST (auth)

Step 2 of ABHA registration: verify the OTP and create the patient. Call this after patient_register_abha_otp_init (which returns the transactionId).

Request fields

Example request

{
  "transactionId": "f455d2f9-18f1-4c6e-bfd0-df5ff2449f97",
  "otp": "886367",
  "abhaAddress": "abcd1234@abdm",
  "authMode": "MOBILE_OTP"
}

Omitting authMode behaves exactly as "MOBILE_OTP" — existing integrations are unaffected.

Example response

Returns the created PatientRes (same shape as /create_patient).

Error codes

• VALIDATION_ERROR (400)
• ABDM_GATEWAY_ERROR (502) — OTP verification failed / no user returned; or the OTP was requested on a different authMode than the one sent here. error.message carries ABDM's own reason.
• shared codes

/scan_and_share — POST (auth)

Registers and returns a patient from an ABDM Scan-and-Share token. The patient scans your facility's HFR QR code with their ABHA/PHR app; ABDM pushes the shared demography to Nice HMS and the patient's app displays a token number. Submit that token number here to register the patient in Nice HMS (MySQL and the FHIR store) and retrieve their demography. If the patient is already registered under your organization, the existing record is returned — no duplicate is created.

The token is valid for 48 hours after the scan.

Request fields

Example request

{
  "tokenNumber": 128
}

Example response

Returns the registered PatientRes (same shape as /create_patient), populated from the shared demography: name, gender, date of birth, mobile, ABHA address, ABHA number and address.

Error codes

• SCAN_TOKEN_NOT_FOUND (404) — no scanned profile exists for this token under your facility (unknown token, a token minted for a different facility, or a share body that carried no patient demography).
• SCAN_TOKEN_EXPIRED (410) — the token is older than 48 hours; ask the patient to scan the QR code again.
• shared codes