FHIR Patient Resource: A Developer's Guide to Modelling Indian Patients in HMIS

The FHIR Patient resource is the foundation of every healthcare information system. Every encounter, every observation, every prescription traces back to a patient. In India, the stakes are even higher — the Ayushman Bharat Digital Mission (ABDM) has made the ABHA (Ayushman Bharat Health Account) number a national standard for uniquely identifying patients across the healthcare ecosystem.

If you're building an HMIS or any health IT system in India, understanding how to model a Patient resource correctly isn't optional — it's the difference between systems that interoperate and systems that get siloed.

This is the first of a 14-part deep-dive series on FHIR resources. Let's start where every clinical record starts: the patient.

---

The FHIR Patient Resource at a Glance

The Patient resource captures demographic and administrative information about an individual receiving healthcare services. Here's a minimal representation:

{
  "resourceType": "Patient",
  "id": "patient-001",
  "identifier": [
    {
      "use": "usual",
      "system": "https://abdm.gov.in/fhir/abha-address",
      "value": "14-digit-abha-number"
    }
  ],
  "active": true,
  "name": [
    {
      "use": "official",
      "family": "Patel",
      "given": ["Rajeshkumar", "Mohanbhai"]
    }
  ],
  "gender": "male",
  "birthDate": "1985-03-15",
  "address": [
    {
      "use": "home",
      "type": "physical",
      "line": ["42, Sardar Patel Road"],
      "city": "Ahmedabad",
      "district": "Ahmedabad",
      "state": "GJ",
      "postalCode": "380001",
      "country": "IN"
    }
  ]
}

Now let's look at how to create and consume this in Java using HAPI FHIR.

---

HAPI FHIR: Creating a Patient Resource

HAPI FHIR is the gold-standard Java library for FHIR operations. If your HMIS is on Spring Boot, HAPI FHIR is almost certainly your best choice.

Adding the Dependency

<!-- Maven -->
<dependency>
    <groupId>ca.uhn.hapi.fhir</groupId>
    <artifactId>hapi-fhir-server-openr4</artifactId>
    <version>7.4.0</version>
</dependency>

Or with Gradle:

implementation 'ca.uhn.hapi.fhir:hapi-fhir-server-openr4:7.4.0'

Building a Patient with ABHA Identifier

import ca.uhn.fhir.model.api.annotation.*;
import ca.uhn.fhir.rest.api.MethodOutcome;
import ca.uhn.fhir.rest.client.api.*;
import org.hl7.fhir.r4.model.*;

public class PatientService {

    private final IGenericClient fhirClient;

    public PatientService(IGenericClient fhirClient) {
        this.fhirClient = fhirClient;
    }

    public MethodOutcome createPatientWithABHA(
            String abhaNumber,
            String givenName,
            String familyName,
            String birthDate,
            Enumerations.AdministrativeGender gender,
            String district,
            String state
    ) {
        Patient patient = new Patient();

        // ABHA Identifier — the mandatory national ID
        IdentifierComponent abhaIdentifier = patient.addIdentifier();
        abhaIdentifier.setUse(Identifier.IdentifierUse.USUAL);
        abhaIdentifier.setSystem("https://abdm.gov.in/fhir/abha-address");
        abhaIdentifier.setValue(abhaNumber);
        abhaIdentifier.setType(new CodeableConcept(
            new Coding("http://terminology.hl7.org/CodeSystem/v2-0203", "MR", "Medical Record Number")
        ));

        // HumanName: Indian naming conventions (given + family, no middle in many cases)
        HumanName name = patient.addName();
        name.setUse(HumanName.NameUse.OFFICIAL);
        name.addGiven(givenName);
        name.setFamily(familyName);
        // Hindi/regional script names if captured
        name.setText(givenName + " " + familyName);

        patient.setGender(gender);
        patient.setBirthDateElement(new DateType(birthDate));

        // Address following Indian address norms
        Address addr = patient.addAddress();
        addr.setUse(Address.AddressUse.HOME);
        addr.setType(Address.AddressType.PHYSICAL);
        addr.addLine("42, Sardar Patel Road");
        addr.setDistrict(district);
        addr.setState(state);
        addr.setPostalCode("380001");
        addr.setCountry("IN");

        // ABDM requires patients to be active in the ecosystem
        patient.setActive(true);

        // The XDSb metadata extension for ABDM health documents
        patient.addExtension()
            .setUrl("https://abdm.gov.in/fhir/StructureDefinition/PatientABHA")
            .setValue(new BooleanType(true));

        return fhirClient.create().resource(patient).execute();
    }
}

Searching for Patients by ABHA

public Patient readPatientByABHA(String abhaValue) {
    Bundle results = fhirClient.search()
        .forResource(Patient.class)
        .where(Patient.IDENTIFIER.exactly().systemAndCode(
            "https://abdm.gov.in/fhir/abha-address", abhaValue))
        .returnBundle(Bundle.class)
        .execute();

    if (results.hasEntry()) {
        return (Patient) results.getEntryFirstRep().getResource();
    }
    throw new ResourceNotFoundException("No patient found with ABHA: " + abhaValue);
}

---

India-Specific Considerations

ABHA: The 14-Digit National Health Identifier

Under ABDM, every patient is assigned an ABHA number — a 14-digit unique health identifier. This is not the same as Aadhaar (which is an ID proof, not a health ID). The ABHA is:

• Voluntary but increasingly required for government scheme benefits (Ayushman Bharat, CGHS, ESIC)
• Portable — the same ABHA works across any ABDM-compliant facility in India
• Linked to health records, prescriptions, and diagnostic reports

Your HMIS should generate or accept ABHA during patient registration and store it in the identifier field with system https://abdm.gov.in/fhir/abha-address.

Multilingual Names

India has 22 scheduled languages. A patient may register under an English transliteration, a regional script (Gujarati, Tamil, Bengali, etc.), or both. Store the full text in HumanName.text:

// Store the display text in the original script
name.setText("રાજેશકુમાર પટેલ"); // Gujarati script
name.addGiven("Rajeshkumar"); // Latin transliteration
name.setFamily("Patel");

District and State — Not Just City

Unlike US addresses where city + state suffice, Indian address schemas need district explicitly. District courts, public health offices, and government schemes all operate at the district level. Always populate Address.district.

Gender Coding

FHIR uses male, female, other, unknown. For Indian government schemes, the CGHS and ESIC systems also expect these same values — align your internal enum to FHIR's AdministrativeGender.

---

Storing and Querying Patients in ArogyaPlus HMIS

In ArogyaPlus HMIS — the SnowCare Health Tech hospital management system — patient registration captures the ABHA during intake. For hospitals running on ArogyaPlus, the FHIR Patient resource maps directly to the internal patient master:

FHIR Field	ArogyaPlus Field
Patient.identifier	ABHA Number, MRN
Patient.name	Patient Name (EN + regional)
Patient.birthDate	Date of Birth
Patient.address	Full Address
Patient.gender	Gender
Patient.telecom	Phone, Email

ArogyaPlus generates FHIR-compliant Patient resources on demand for ABDM health lockers, enabling patients to access their records through the ABDM app — a key differentiator for hospitals competing on digital readiness.

---

What's Next

In the next article of this series, we'll look at the FHIR Practitioner Resource — how to model doctors, nurses, and paramedics, including their HPR (Healthcare Professional Registry) identifiers and MCI registration numbers that are mandatory for ABDM compliance.

If you're building or evaluating an HMIS in India, talk to the ArogyaPlus team at SnowCare Health Tech: hmis.snowcarehealth.tech

---

This article is part of a 14-part series on FHIR resources for Indian healthcare IT developers. Next up: Practitioner Resource.