FHIR R5 Patient API - hmislk/hmis GitHub Wiki

FHIR R5 Patient API

The HMIS FHIR R5 Patient API provides standard HL7 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.

Overview

Property Value
Base URL /api/fhir/Patient
FHIR Version R5
Resource Type Patient
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 Main Menu → ⚙ (Cogwheel) → Manage My API Keys and create a key with type FHIR. See Managing API Keys for step-by-step instructions.

If the key is missing, expired, or belongs to a retired/inactive user, the API returns:

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

curl -s \
  -H "FHIR: your-api-key" \
  http://your-server/rh/api/fhir/Patient/99401

Response — 200 OK

{
  "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 of type searchset (max 50 results).

Search by name

curl -s \
  -H "FHIR: your-api-key" \
  "http://your-server/rh/api/fhir/Patient?name=silva"

Search by phone

curl -s \
  -H "FHIR: your-api-key" \
  "http://your-server/rh/api/fhir/Patient?phone=0771234567"

Search by NIC (plain)

curl -s \
  -H "FHIR: your-api-key" \
  "http://your-server/rh/api/fhir/Patient?identifier=901670123V"

Search by PHN (system-prefixed)

curl -s \
  -H "FHIR: your-api-key" \
  "http://your-server/rh/api/fhir/Patient?identifier=urn%3Alk%3Aphn%7CD2DG9D1"

Response — 200 OK

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

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

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

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 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:

curl -s http://your-server/rh/api/capabilities | python -m json.tool

Look for the FHIR Patient entry in the resources array.

Related

Back