NZ Shared Digital Health Record API
0.4.0 - draft

NZ Shared Digital Health Record API - Local Development build (v0.4.0) built by the FHIR (HL7® FHIR® Standard) Build Tools. See the Directory of published versions

API Docs

API Documentation

The SDHR API is comprised of multiple FHIR resources. This page provides technical guidance for applicaiton developers who wish to integrate their applications with the Shared Digital Health Record APIs

Resource Description
API Capability Statement FHIR API Capability Statement
API Artifacts List of FHIR Artifacts for this API
OpenAPI Specification Machine readable OpenAPI specification for this API

Logical View

SDHR API - Logical ViewSDHR API - Logical View«system»Secondary Care API Consumers«system»Secondary Care Systems«system»Primary Care API Consumers«system»Primary Care Systems«system_boundary»«boundary»Health NZ | Te Whatu Ora[system]«system_boundary»«boundary»HNZ Connector Plane[system]«system_boundary»«boundary»SDHR Data Services[system]«New-Capability»«system»FHIR APIs«system_boundary»«boundary»National Dataservices[system]«Existing-Capability»«system»FHIR APIs«person»e.g. EmergencyDepartments,Hospitals Medical professionalsinvolved in secondarycare delivery«container»Regional ClinicalPortals«container»Regional SHERs«person»e.g. GeneralPractice Medical professionalsinvolved in primary caredelivery.«container»PatientManagementSystemsSDHR Condition FHIR APIConditionmethods(GET, POST,PUT)SDHR Encounter FHIRAPIEncountermethods(GET, POST,PUT)SDHR Observation FHIRAPIObservationmethods(GET, POST,PUT)SDHR AllergyIntoleranceFHIR APIAllergyIntolerancemethods(GET, POST,PUT)AIR Immunization FHIRAPIImmunizationmethods(GET, POST,PUT)Medicine DataRepository FHIR APIMedicationmethods(GET, POST,PUT)Medical Warning SystemFHIR APIAlertmethods(GET, POST,PUT)National Health IndexPatientmethods(GET, POST,PUT)«person»Patients Patients using healthcare servicesLegend ▯ person ▯ system ▯ container ▯ system boundary ▯ New-Capability ▯ Existing-Capability 


API Search Behaviour

The Shared Digital Health Record FHIR API supports the FHIR search pattern. See below for some example search queries.

Search for Conditions by Patient and Source

This query will return all Condition resources for a given Patient and meta.source.

GET /Condition?patient=https://api.hip.digital.health.nz/fhir/Patient/ZKC7284&_source=https://api.hip.digital.health.nz/fhir/Location/F38006-B

Click to view example response
In this example the search returns 2 active conditions for the patient `ZKC7284` that were sourced from the HPI location `F38006-B` 

{
    "resourceType": "Bundle",
    "id": "92e3f5a6-2f8e-4e9d-a8f9-e5e6c578dd53",
    "meta": {
        "lastUpdated": "2025-05-01T21:23:04.818Z"
    },
    "type": "searchset",
    "total": 2,
    "link": [
        {
            "relation": "self",
            "url": "https://server.url/Condition?_source=https%3A%2F%2Fapi.hip.digital.health.nz%2Ffhir%2FLocation%2FF38006-B&patient=https%3A%2F%2Fapi.hip.digital.health.nz%2Ffhir%2FPatient%2FZKC7284"
        }
    ],
    "entry": [
        {
            "search": {
                "mode": "match"
            },
            "fullUrl": "https://server.url/Condition/635b2a1c-bdd1-4a20-8c2f-6d8348352f6a",
            "resource": {
                "identifier": [
                    {
                        "system": "https://standards.digital.health.nz/ns/health-record-key-id",
                        "value": "ef5b3aad-14c2-4904-aa25-7411dcb21327"
                    }
                ],
                "extension": [
                    {
                        "valueBoolean": true,
                        "url": "http://hl7.org.nz/fhir/StructureDefinition/long-term-condition"
                    }
                ],
                "recorder": {
                    "reference": "https://api.hip.digital.health.nz/fhir/Practitioner/99ZZZZ",
                    "display": "Dottie McStuffins",
                    "type": "Practitioner"
                },
                "code": {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "38341003",
                            "display": "HT - Hypertension"
                        }
                    ],
                    "text": "Hypertension"
                },
                "verificationStatus": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
                            "code": "confirmed"
                        }
                    ]
                },
                "subject": {
                    "reference": "https://api.hip.digital.health.nz/fhir/Patient/ZKC7284",
                    "display": "Carrey Carrington",
                    "type": "Patient"
                },
                "recordedDate": "2023-11-26T10:02:45+13:00",
                "clinicalStatus": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
                            "code": "active"
                        }
                    ]
                },
                "onsetDateTime": "2011-02-05T00:00:00+13:00",
                "asserter": {
                    "reference": "https://api.hip.digital.health.nz/fhir/Practitioner/91ZZXN",
                    "display": "DR Julian Subatoi Bashir",
                    "type": "Practitioner"
                },
                "meta": {
                    "lastUpdated": "2025-03-21T00:34:52.819Z",
                    "versionId": "1",
                    "profile": [
                        "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRCondition"
                    ],
                    "source": "https://api.hip.digital.health.nz/fhir/Location/F38006-B"
                },
                "id": "635b2a1c-bdd1-4a20-8c2f-6d8348352f6a",
                "resourceType": "Condition"
            }
        },
        {
            "search": {
                "mode": "match"
            },
            "fullUrl": "https://server.url/Condition/c3605e85-6785-4fa9-94a5-6d8015416c53",
            "resource": {
                "identifier": [
                    {
                        "system": "https://standards.digital.health.nz/ns/health-record-key-id",
                        "value": "ef5b3aad-14c2-4904-aa25-7411dcb21327"
                    }
                ],
                "extension": [
                    {
                        "valueBoolean": true,
                        "url": "http://hl7.org.nz/fhir/StructureDefinition/long-term-condition"
                    }
                ],
                "recorder": {
                    "reference": "https://api.hip.digital.health.nz/fhir/Practitioner/99ZZZZ",
                    "display": "Dottie McStuffins",
                    "type": "Practitioner"
                },
                "code": {
                    "coding": [
                        {
                            "system": "http://snomed.info/sct",
                            "code": "13645005",
                            "display": "Chronic obstructive pulmonary disease"
                        }
                    ],
                    "text": "Hypertension"
                },
                "verificationStatus": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
                            "code": "confirmed"
                        }
                    ]
                },
                "subject": {
                    "reference": "https://api.hip.digital.health.nz/fhir/Patient/ZKC7284",
                    "display": "Carrey Carrington",
                    "type": "Patient"
                },
                "recordedDate": "2023-11-26T10:02:45+13:00",
                "clinicalStatus": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
                            "code": "active"
                        }
                    ]
                },
                "onsetDateTime": "2011-02-05T00:00:00+13:00",
                "asserter": {
                    "reference": "https://api.hip.digital.health.nz/fhir/Practitioner/91ZZXN",
                    "display": "DR Julian Subatoi Bashir",
                    "type": "Practitioner"
                },
                "meta": {
                    "lastUpdated": "2025-03-21T00:41:35.416Z",
                    "versionId": "1",
                    "profile": [
                        "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRCondition"
                    ],
                    "source": "https://api.hip.digital.health.nz/fhir/Location/F38006-B"
                },
                "id": "c3605e85-6785-4fa9-94a5-6d8015416c53",
                "resourceType": "Condition"
            }
        }
    ]
}


Search for Resources by Patient and Identifier

In this API identifier can be used to track source system unique identifiers. This should enable systems such as Patient Management Systems to track the provenance of resources. There is no limit on the number of identifiers that a resource can contain.

Request Condition resources for a specific identifier GET Condition?patient=https://api.hip.digital.health.nz/fhir/Patient/ZKC7284&identifier=38cb6f26-9534-46e5-b659-536992faf0cc

Request Condition resources for a specific identifier AND system, GET /Condition?patient=https://api.hip.digital.health.nz/fhir/Patient/ZKC7284&identifier=https://some.local.system/ehr-key%7Cd2ed3bc7-da4a-45b8-ae3f-82176f5c64a4

Click to view example response
In this example the above query returns a single result. Note that in most cases omission of the `patient` would return a single result but to avoid any possiblility of identifier non-uniqueness the `patient` modifier **SHOULD** be used. 


{
    "resourceType": "Bundle",
    "id": "4c3cf2a4-4424-46f4-b4af-00c46812ec7e",
    "meta": {
        "lastUpdated": "2025-05-01T22:23:57.904Z"
    },
    "type": "searchset",
    "total": 1,
    "link": [
        {
            "relation": "self",
            "url": "https://server.url/Condition?identifier=38cb6f26-9534-46e5-b659-536992faf0cc&patient=https%3A%2F%2Fapi.hip.digital.health.nz%2Ffhir%2FPatient%2FZKC7284"
        }
    ],
    "entry": [
        {
            "search": {
                "mode": "match"
            },
            "fullUrl": "https://server.url/Condition/72ca633a-23cc-4848-a512-5111750508fb",
            "resource": {
                "identifier": [
                    {
                        "system": "https://some.local.system/ehr-key",
                        "value": "38cb6f26-9534-46e5-b659-536992faf0cc"
                    }
                ],
                "extension": [
                    {
                        "valueBoolean": true,
                        "url": "http://hl7.org.nz/fhir/StructureDefinition/long-term-condition"
                    }
                ],
                "recorder": {
                    "reference": "https://api.hip.digital.health.nz/fhir/Practitioner/99ZZZZ",
                    "display": "Dottie McStuffins",
                    "type": "Practitioner"
                },
                "code": {
                    "coding": [
                        {
                            "system": "http://health.govt.nz/read-codes",
                            "code": "SN3..",
                            "display": "Local pressure"
                        }
                    ],
                    "text": "Hypertension"
                },
                "verificationStatus": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-ver-status",
                            "code": "confirmed"
                        }
                    ]
                },
                "subject": {
                    "reference": "https://api.hip.digital.health.nz/fhir/Patient/ZKC7284",
                    "display": "Carrey Carrington",
                    "type": "Patient"
                },
                "recordedDate": "2023-11-26T10:02:45+13:00",
                "clinicalStatus": {
                    "coding": [
                        {
                            "system": "http://terminology.hl7.org/CodeSystem/condition-clinical",
                            "code": "active"
                        }
                    ]
                },
                "onsetDateTime": "2011-02-05T00:00:00+13:00",
                "asserter": {
                    "reference": "https://api.hip.digital.health.nz/fhir/Practitioner/91ZZXN",
                    "display": "DR Julian Subatoi Bashir",
                    "type": "Practitioner"
                },
                "meta": {
                    "lastUpdated": "2025-05-01T22:23:37.587Z",
                    "versionId": "1",
                    "profile": [
                        "https://fhir-ig.digital.health.nz/sdhr/StructureDefinition/SDHRCondition"
                    ],
                    "source": "https://api.hip.digital.health.nz/fhir/Location/F38006-B"
                },
                "id": "72ca633a-23cc-4848-a512-5111750508fb",
                "resourceType": "Condition"
            }
        }
    ]
}


SDHR Resource updates

This section describes the process of SDHR API Consumer system interacting with the SDHR FHIR server to update existing resources.

GET before PUT

To maintain data integrity, API Consumers authorized to make updates to resources must use a "GET before PUT" approach. By always fetching the current state of a resource before attempting an update, you ensure that the modifications reflect the most accurate and recent information, without overwriting updates which may have been made by other API Consumers.

Shared Digital Health Record - GET before PUTShared Digital Health Record - GET before PUTSDHR FHIR ServerSDHR FHIR ServerAPI ConsumerSDHR FHIR ServerAPI ConsumerAPI ConsumerSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerPOST /Condition (Create)201 Created, serverResourceId returnedTime passes, the resource has been updated at sourceGET /Condition/{serverResourceId} (Read current resource)Make changes to resource, e.g. update statusPUT /Condition/{serverResourceId} (Update resource)200 OK


Searching for resources before update

The SDHR API reflects the FHIR Search parameters which are documented in the Server Capability Statement and well as a direct HTTP GET for a resource.

Case 1: The SDHR Server assigned resource ID is known by the API Consumer:

In this scenario, an HTTP GET for the resource can be made to retrieve the resource: GET /Condition/{serverResourceId}.

Once the update has been made, the resource can be updated in the SDHR Server by using an HTTP PUT to the resource: PUT /Condition/{serverResourceId}

Case 2: The SDHR Server assigned resource ID is unknown by the API Consumer:

In this scenario, a FHIR Search must be used with search parameters available to the API Consumer, as the server resource ID cannot be used for a direct HTTP GET.

Option 1: FHIR Search by local PMS identifier, stored as a FHIR Identifier

To improve accuracy in this process, API Consumers who submit or update records may append an identifier known to them to the shared record. This may be a representation or a copy of a local identifier used within the local PMS system. When a local identifier is stored, a FHIR Search using an identifier search parameter can be used to retrieve a record.

Shared Digital Health Record - FHIR Search by identifierShared Digital Health Record - FHIR Search by identifierSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerAPI ConsumerSDHR FHIR ServerAPI ConsumerAPI ConsumerSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerPOST /Condition (Create, including local identifier)201 Created, serverResourceId returnedTime passes, the resource has been updated at sourceGET /Condition?identifier=&_source=https://api.hip.digital.health.nz/fhir/Location/F38006-B(Search by identifier and facilityId)Bundle (Containing Condition Resource)Make changes to resource, e.g. update statusPUT /Condition/{serverResourceId} (Update)200 OK


Option 2: FHIR Search using resource search parameters

When a local identifier is not submitted to a resource, the search parameters for each resource must be used, which are documented in the Server Capability Statement. This will return a FHIR Bundle which may contain multiple records which must be handled by the API Consumer.

Shared Digital Health Record - FHIR Search by known parametersShared Digital Health Record - FHIR Search by known parametersSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerAPI ConsumerSDHR FHIR ServerAPI ConsumerAPI ConsumerSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerSDHR FHIR ServerPOST /Condition (Create)201 Created, serverResourceId returnedTime passes, the resource has been updated at sourceGET /Condition?code=http:snomed.info/sct|442387007&status=active&subject=https:api.hip.digital.health.nz/fhir/Patient/ZKC7284(Search by subject, status and code)Bundle (Containing Condition Resource)Make changes to resource, e.g. update statusPUT /Condition/{serverResourceId} (Update)200 OK