# FHIR R5 Patient API The HMIS FHIR R5 Patient API provides standard [HL7 FHIR R5](https://hl7.org/fhir/R5/) compliant endpoints for searching, reading, creating, and updating patient records. It enables external systems and integrations to exchange patient demographic data using the international [FHIR standard](https://hl7.org/fhir/). ## Overview | Property | Value | |----------|-------| | Base URL | `/api/fhir/Patient` | | FHIR Version | [R5](https://hl7.org/fhir/R5/) | | Resource Type | [Patient](https://hl7.org/fhir/R5/patient.html) | | Content Type | `application/fhir+json` | | Authentication | `FHIR` request header (API key) | ## Authentication All endpoints require a valid API key passed in the `FHIR` HTTP request header. ``` FHIR: your-api-key-value ``` To obtain an API key, navigate to **Settings → Manage My API Keys** and create a key with type **FHIR**. See [Managing API Keys](https://github.com/hmislk/hmis/wiki/Manage-My-API-Keys) for step-by-step instructions. If the key is missing, expired, or belongs to a retired/inactive user, the API returns: ```json { "status": "error", "code": 401, "message": "Invalid or missing FHIR API key" } ``` ## Field Mapping The API maps between HMIS internal fields and [FHIR R5 Patient resource](https://hl7.org/fhir/R5/patient.html) fields as follows: | FHIR R5 Field | HMIS Field | Notes | |---------------|-----------|-------| | `id` | `patient.id` | Internal DB id | | `active` | `!patient.retired` | Inverted | | `identifier` (system `urn:hmis:mrn`) | `patient.code` | Medical Record Number | | `identifier` (system `urn:lk:phn`) | `patient.phn` | Public Health Number | | `identifier` (system `urn:lk:nic`) | `person.nic` | National Identity Card | | `name[0].text` | `person.name` | Display name | | `name[0].given[0]` | `person.fullName` | First/given name | | `name[0].family` | `person.lastName` | Family name | | `name[0].prefix[0]` | `person.title` | Mr, Mrs, Dr, etc. | | `birthDate` | `person.dob` | | | `gender` | `person.sex` | male/female/other/unknown | | `telecom` (home phone) | `person.phone` | | | `telecom` (mobile phone) | `person.mobile` | | | `telecom` (email) | `person.email` | | | `address[0].text` | `person.address` | | --- ## Endpoints ### GET /api/fhir/Patient/{id} — Read by ID Retrieve a single patient by their internal HMIS database ID. **Request** ```bash curl -s \ -H "FHIR: your-api-key" \ http://your-server/rh/api/fhir/Patient/99401 ``` **Response — 200 OK** ```json { "resourceType": "Patient", "id": "99401", "active": true, "identifier": [ { "system": "urn:hmis:mrn", "value": "MRN001" } ], "name": [{ "use": "official", "text": "John Silva", "family": "Silva", "given": ["John"], "prefix": ["Mr."] }], "telecom": [ { "system": "phone", "use": "home", "value": "0112345678" }, { "system": "phone", "use": "mobile", "value": "0771234567" } ], "gender": "male", "birthDate": "1985-04-12", "address": [{ "text": "42 Main Street, Colombo" }] } ``` **Error Responses** | Code | Reason | |------|--------| | 401 | Missing or invalid API key | | 404 | No patient found with that ID | --- ### GET /api/fhir/Patient — Search Search for patients using query parameters. At least one parameter is required. **Query Parameters** | Parameter | Description | Example | |-----------|-------------|---------| | `name` | Partial name match (case-insensitive) | `?name=silva` | | `phone` | Exact phone or mobile number | `?phone=0771234567` | | `identifier` | Plain value (searches NIC, PHN, MRN) | `?identifier=901670123V` | | `identifier` | System-prefixed value | `?identifier=urn:lk:nic\|901670123V` | Supported identifier systems: - `urn:lk:nic` — National Identity Card - `urn:lk:phn` — Public Health Number - `urn:hmis:mrn` — Medical Record Number Returns a [FHIR Bundle](https://hl7.org/fhir/R5/bundle.html) of type `searchset` (max 50 results). **Search by name** ```bash curl -s \ -H "FHIR: your-api-key" \ "http://your-server/rh/api/fhir/Patient?name=silva" ``` **Search by phone** ```bash curl -s \ -H "FHIR: your-api-key" \ "http://your-server/rh/api/fhir/Patient?phone=0771234567" ``` **Search by NIC (plain)** ```bash curl -s \ -H "FHIR: your-api-key" \ "http://your-server/rh/api/fhir/Patient?identifier=901670123V" ``` **Search by PHN (system-prefixed)** ```bash curl -s \ -H "FHIR: your-api-key" \ "http://your-server/rh/api/fhir/Patient?identifier=urn%3Alk%3Aphn%7CD2DG9D1" ``` **Response — 200 OK** ```json { "resourceType": "Bundle", "type": "searchset", "total": 3, "entry": [ { "resource": { "resourceType": "Patient", "id": "12241965", "active": true, "name": [{ "use": "official", "text": "A.B. SILVA" }], "gender": "male" } } ] } ``` **Error Responses** | Code | Reason | |------|--------| | 400 | No search parameters provided | | 401 | Missing or invalid API key | --- ### POST /api/fhir/Patient — Create Create a new patient. The request body must be a valid [FHIR R5 Patient](https://hl7.org/fhir/R5/patient.html) resource in JSON format. - If `identifier` with system `urn:hmis:mrn` is included, that value is used as the Medical Record Number; otherwise one is auto-generated. - The API key's associated user becomes the creator; their institution is set as the patient's registered institution. **Request** ```bash curl -s -X POST \ -H "FHIR: your-api-key" \ -H "Content-Type: application/fhir+json" \ -d '{ "resourceType": "Patient", "name": [{ "use": "official", "text": "Nimal Perera", "family": "Perera", "given": ["Nimal"], "prefix": ["Mr"] }], "gender": "male", "birthDate": "1990-06-15", "telecom": [ { "system": "phone", "use": "home", "value": "0112233445" }, { "system": "phone", "use": "mobile", "value": "0771122334" } ], "address": [{ "text": "10 Galle Road, Matara" }], "identifier": [ { "system": "urn:lk:nic", "value": "901670123V" }, { "system": "urn:lk:phn", "value": "PHN12345" } ] }' \ http://your-server/rh/api/fhir/Patient ``` **Response — 201 Created** ```json { "resourceType": "Patient", "id": "12255403", "identifier": [ { "system": "urn:hmis:mrn", "value": "587" }, { "system": "urn:lk:nic", "value": "901670123V" }, { "system": "urn:lk:phn", "value": "PHN12345" } ], "active": true, "name": [{ "use": "official", "text": "Nimal Perera", "family": "Perera", "given": ["Nimal"], "prefix": ["Mr."] }], "gender": "male", "birthDate": "1990-06-15", "telecom": [ { "system": "phone", "use": "home", "value": "0112233445" }, { "system": "phone", "use": "mobile", "value": "0771122334" } ], "address": [{ "text": "10 Galle Road, Matara" }] } ``` **Error Responses** | Code | Reason | |------|--------| | 400 | Missing or invalid FHIR JSON body | | 401 | Missing or invalid API key | --- ### PUT /api/fhir/Patient/{id} — Update Partially update an existing patient. Only fields present in the request body are updated; omitted fields retain their existing values. **Request** ```bash curl -s -X PUT \ -H "FHIR: your-api-key" \ -H "Content-Type: application/fhir+json" \ -d '{ "resourceType": "Patient", "name": [{ "use": "official", "text": "Nimal Perera", "family": "Perera", "given": ["Nimal"], "prefix": ["Dr"] }], "telecom": [ { "system": "phone", "use": "mobile", "value": "0700000001" } ], "address": [{ "text": "456 New Road, Galle" }] }' \ http://your-server/rh/api/fhir/Patient/12255403 ``` **Response — 200 OK** Returns the full updated [FHIR R5 Patient](https://hl7.org/fhir/R5/patient.html) resource, including fields that were not changed. **Error Responses** | Code | Reason | |------|--------| | 400 | Missing or invalid FHIR JSON body | | 401 | Missing or invalid API key | | 404 | No patient found with that ID | --- ## Capabilities Endpoint To verify the FHIR Patient API is registered and available: ```bash curl -s http://your-server/rh/api/capabilities | python -m json.tool ``` Look for the `FHIR Patient` entry in the `resources` array. --- ## Related - [FHIR R5 Official Specification](https://hl7.org/fhir/R5/) - [FHIR R5 Patient Resource](https://hl7.org/fhir/R5/patient.html) - [FHIR R5 Bundle Resource](https://hl7.org/fhir/R5/bundle.html) - [FHIR R4 Background](https://github.com/hmislk/hmis/wiki/FHIR-R4) - [REST Security](https://github.com/hmislk/hmis/wiki/REST-Security) - [Managing API Keys](https://github.com/hmislk/hmis/wiki/Manage-My-API-Keys) - [API Overview](https://github.com/hmislk/hmis/wiki/API) [Back](https://github.com/hmislk/hmis/wiki/API)