---
title: "ABDM API — Patient"
description: "Nice HMS ABDM patient endpoints: create_patient, patient_by_id, patient_by_abhaAddress, and the two-step ABHA registration (patient_register_abha_otp_init / confirm)."
date: 2026-08-26
lastModified: 2026-08-26
category: "developer"
author: "Dr. Umesh Bilagi"
beta: true
---

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

| Name | Type | Required | Description |
|---|---|---|---|
| `patient.firstName` | string | Yes | Non-empty. |
| `patient.gender` | string | Yes | `"Male"` \| `"Female"` \| `"Other"`. |
| `patient.dob` | string | Yes | `YYYY-MM-DD`, a valid **past** date. |
| `patient.mobile` | string | Yes | Exactly 10 digits. |
| `patient.state` | string | Yes | Non-empty. |
| `patient.district` | string | Yes | Non-empty. |
| `patient.abhaAddress` | string | **No** | Rejected — see note below. |
| `patient.abhaNumber` | string | **No** | Rejected — see note below. |
| `patient.prefix` | string | No | `Mr` \| `Mrs` \| `Ms` \| `Dr` \| `NA` \| `Master` \| `Er`. |
| `patient.middleName` | string | No | |
| `patient.lastName` | string | No | |
| `patient.address` | string | No | |
| `patient.panNumber` | string | No | |
| `patient.aadharNumber` | string | No | |
| `patient.email` | string | No | |
| `patient.alternatePhoneNumber` | string | No | |
| `patient.pincode` | number | No | |

### Example request

```json
{
  "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

```json
{
  "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

| Name | Type | Required | Description |
|---|---|---|---|
| `patientId` | number | Yes | The unique patient id generated within Nice HMS. |

### Example request

```json
{
  "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

| Name | Type | Required | Description |
|---|---|---|---|
| `abhaAddress` | string | Yes | The patient's ABHA address, e.g. `savitribilagi@sbx`. |

### Example request

```json
{
  "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

| Name | Type | Required | Description |
|---|---|---|---|
| `abhaAddress` | string | Yes | ABHA address to register, e.g. `abcd@abdm`. |
| `authMode` | string | Yes | `"MOBILE_OTP"` \| `"AADHAAR_OTP"` \| `"DONT_KNOW"`. |

### Example request

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

### Example response

```json
{
  "auth": {
    "meta": {
      "hint": {},
      "expiry": "2023-06-04T06:57:19.082288652"
    },
    "mode": "MOBILE_OTP",
    "transactionId": "f455d2f9-18f1-4c6e-bfd0-df5ff2449f97"
  },
  "resp": {
    "requestId": "48c0f79a-a3aa-465c-a07d-f1e20663d1f4"
  },
  "requestId": "4615b2d6-6275-4122-9eba-01da0faf8aa6",
  "timestamp": "2023-06-04T04:57:19.082281323"
}
```

### Error codes

- `VALIDATION_ERROR` (400)
- `ABDM_GATEWAY_ERROR` (502) — e.g. auth mode not available for this ABHA address.
- 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

| Name | Type | Required | Description |
|---|---|---|---|
| `transactionId` | string | Yes | Returned by `patient_register_abha_otp_init`. |
| `otp` | string | Yes | The OTP the patient received. |
| `abhaAddress` | string | Yes | The ABHA address being registered. |

### Example request

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

### 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.
- shared codes